Ask Reuben
RTFM – Read The FOUR Js Manual
I can’t find something in the documentation?
What document format is best?
RTFM = Read The FOUR Js Manual, of course, what else could it mean? 🙂 .
In all seriousness, now that I have hooked you with an interesting title, navigating around the Four Js documentation is a skill that can lead you to getting more out of our product.
When I am first on-site with a developer, if I ask them to bring up the documentation, the speed with which they bring up the documentation and navigate to the appropriate page tells me a lot about their existing ability. I find that a good developer will either use a bookmark in their browser to open up the online documentation, or bring up the Genero Studio Help from within Genero Studio, and from either navigate to the appropriate page.
If I see them struggle to open the documentation and then navigate within it, then not only are they not getting the most of the documentation, they are probably not getting the most of our product. I will include them in this category if, when I ask them to bring up the documentation, they type www.4js.com into the browser and then navigate via the Support or Download tab to https://4js.com/download/documentation/. If they are doing that every time they need to access the documentation then IMHO they are not reading the documentation often enough; if they were, they would have figured out a faster way to do this, such as creating a bookmark.
So I am going to give a few tips to help you get the most out of your documentation
Tips
Where is the documentation?
The documentation can be found at https://4js.com/download/documentation/, or if you are on www.4js.com by selecting Download->Documentation.
If using Genero Studio, documentation is available by a keyboard accelerator (F1), or via the Toolbar by clicking the Help icon, or via TopMenu by selecting Help->Help. The name of the help executable is Assistant or QtAssistant, so if you see an assistant.exe, that is the Genero Studio Help program.
Documentation is available in 3 formats
The 3 formats are
- The online documentation (HTML)
- The Genero Studio documentation
These differing formats are created using a documentation tool that builds each format from a single set of document sources. It is the same content in each of these formats, organized in the same fashion. You are not missing out on any content by using one tool or the other. “Write Once, Read Anywhere” if you will.
What will differ between these formats is when the documentation was last updated and what search algorithm and engine is used.
Not all Genero products have a PDF version generated, for instance Genero Studio and Genero Browser Client do not have PDF versions generated. If we did, the Genero Studio PDF would be over 1000 pages.
When is Documentation Updated
Documentation is periodically updated, to add details about features included in maintenance releases, or to expand upon or correct existing content. You can anticipate updated documentation with each maintenance release, however there can be more.
The online documentation will be the most up-to-date.
If you have downloaded a PDF or the HTML documentation and reference that, then what you are reading is as per the date you downloaded it. You should periodically check to see if a newer version has been released.
Within Genero Studio Help there is an auto-update feature that, when enabled, updates Genero Studio with the latest documentation release. Enable this from within Genero Studio to be assured that your documentation is the most current.https://4js.com/online_documentation/fjs-gst-manual-html/#gst-topics/c_gst_check_updates.html (Note: this was added to Genero Studio 3.10, so not available Genero Studio 3.00 or earlier)
There is more than one piece of documentation
Each Genero product can have its piece of documentation. If you look at the list here https://4js.com/download/documentation/#toggle-id-1 … , there are eleven separate documents.
Genero Studio ships with 8 of these documents.
The key lesson to be aware of is that there is more than just the Business Development Language documentation. Sometimes the info you need is in the GDC, GBC, GST, or GAS documentation.
Also note that installation and licensing instructions for each product are combined into the Install and License Your Genero Products documentation https://4js.com/online_documentation/fjs-genero-manual-install-html/ , and that there is a seperate document giving an overview of licensing https://4js.com/online_documentation/fjs-genero-manual-licensing-html/
These tools have different search algorithms
Online documentation, Genero Studio documentation, and PDF readers have different search engines. If you do a search in either of these 3 tools, the result order will most likely be different as each tool has different search algorithms and syntax.
Genero Studio uses a tool called QtAssistant (https://doc.qt.io/qt-5/qtassistant-index.html). If you look through its documentation, you will see clues about its search rules https://doc.qt.io/qt-5/assistant-details.html
For example
- inp — lists all the documents that contain the word inp
- inp* — lists all the documents that contain a word beginning with ‘inp’
- Input array — lists all documents that contain both “input” and “array”
- “input array” — list all documents that contain the phrase ‘input array”
By default Genero Studio search searches across ALL the documents that are shipped with Genero Studio. A search on “width” will find BDL results, Form Designer results, Genero Report Writer results etc. The filter functionality enables you to restrict the range of documents that a search will look through. A number of filters are included, and you can use the filter functionality to add filters to limit search to a particular subset of the documentation. Read here for more details https://4js.com/online_documentation/fjs-gst-manual-html/#gst-topics/c_gst_f1help.html.
You should make a habit of checking any result about what product it is referring to, as we have had support calls where the developer was attempting to use Genero Report writer syntax in Genero BDL etc.
Outside of the various in-documentation search features, a handy tip is to also do a Google search prefixing your search with “site:4js.com”, or “site:4js.com/online_documentation” to search through the online documentation. Again pay attention to the resultant URL as it may point you at some 2.x documentation that is still available online and/or Google has cached.
Documentation Versions
With the online documentation, if the URL does not contain a version number, then this indicates it is for the current version e.g. https://4js.com/online_documentation/fjs-fgl-manual-html/. When we release a new version, then the documentation for the old version is made available and it has the version inserted into the URL e.g. https://4js.com/online_documentation/fjs-fgl-3.10.00-manual-html/, https://4js.com/online_documentation/fjs-fgl-3.00.05-manual-html/
You can find these links on the main documentation download page for older versions that are still under support (at the time of writing 3.00 and 3.10).
For older versions that are no longer under support then these are found on the right hand side under Archived Releases.
When sharing links we will typically use the on-line documentation version. So if you are still using an older version of our product, be aware of this, and if the documentation does not match what you are experiencing, find the appropriate version documentation.
If the URL begins with qthelp (e.g., qthelp://genero/gst_docbooks/fgl/fgl-topics/r_fgl_presentation_styles_common_style_attributes.html) then we know it is a page in the Studio help. You can copy and paste those “qthelp” URLs into the Studio help, just as you can copy and paste a typical URL into a browser.
One Page or Many Smaller Pages
Those with long memories back to the previous format of the documentation may remember that topics were on a single page and that you could scroll down a topic. A topic such as this one for example https://4js.com/online_documentation/fjs-fgl-manual-html/#fgl-topics/c_fgl_Dictionary.html might have been one page and you scrolled with the mouse wheel through the five sub-topics. With the current format this is many separate pages and some including myself initially struggled with this thinking the documentation was incomplete. The light bulb moment is to use the sidebar on the left to navigate through the various sub-topics. Think to yourself: I want to see the methods click here, I want to see the examples, click here; as opposed to the previous thought pattern of scroll up or down until I came to the method list or examples.
Useful Pages To Remember
New Features
Each document should have a section labelled “New Features”. This is the fun section to read. I would encourage you to read this periodically and to make sure you read it for past versions as well. You might re-read it and discover that something that was introduced to our product in versions past can be used to solve a current problem. So don’t just read what is new in 3.20, go back and periodically re-read what was new in 3.10, 3.00,…,1.10. Note how we make this easy for you to do by collating all these in one place https://4js.com/online_documentation/fjs-fgl-manual-html/#fgl-topics/c_fgl_nf.html
Upgrading
Each document will have a section labelled “Upgrading”. Every time you upgrade a major or minor release, you should read this to see if there are any changes required to be made to your code or configuration. If New Features is the fun section to read, then this is the mandatory section to read. https://4js.com/online_documentation/fjs-fgl-manual-html/#fgl-topics/c_fgl_upgrade_guides.html
If you are skipping a version, make sure you read the upgrade notes for the intermediate versions.
If you are reading this part of the preparation for an upgrade, make sure you also use the Issue Tracker https://4js.com/support/issue/? To see what else was included in a release.
Error Numbers
This page has a short summary of each error number. https://4js.com/online_documentation/fjs-fgl-manual-html/#fgl-topics/r_fgl_errors_001.html.
A handy tip is that there are anchors to each error number e.g. https://4js.com/online_documentation/fjs-fgl-manual-html/#fgl-topics/r_fgl_errors_001.html#r_fgl_errors_001__error-6313. I have one of these as a bookmark and to find a particular error I simply use this bookmark and edit the last number.
4st Reference
The page I probably visit most often is this one https://4js.com/online_documentation/fjs-fgl-manual-html/#fgl-topics/c_fgl_presentation_styles_019.html. From here I can get to the reference for each available presentation style.
The first entry “Common” applies to all widgets/containers https://4js.com/online_documentation/fjs-fgl-manual-html/#fgl-topics/r_fgl_presentation_styles_common_style_attributes.html. The other entries have the presentation styles that are unique to that particular widget/container as indicated in the name. So the styles that can be used for a particular widget/container are in two places, one for what is unique to that widget/container and one for what applies to all.
Each section has a table with 4 columns, one for each of the front-ends.
Containers, Widgets, Attributes
This page https://4js.com/online_documentation/fjs-fgl-manual-html/#fgl-topics/c_fgl_FormSpecFiles_elements.html lists the available containers and widgets.
For each container/widget, a high level description is offered, but what you really want is the detail description depending on whether you are using STACK or LAYOUT. For example EDIT has this link https://4js.com/online_documentation/fjs-fgl-manual-html/#fgl-topics/c_fgl_FormSpecFiles_EDIT.html and from there you go down to LAYOUT verison https://4js.com/online_documentation/fjs-fgl-manual-html/#fgl-topics/c_fgl_FormSpecFiles_EDIT_Item_Type.html or the STACK version https://4js.com/online_documentation/fjs-fgl-manual-html/#fgl-topics/c_fgl_FormSpecFiles_EDIT_stack_item.html.
The important thing to note for each of these is the ATTRIBUTES section. The list of attributes is different depending upon whether using Layout or Stack. This lists the ATTRIBUTES that are available, and if you click on one of the attributes values you can see the valid syntax.
It should also be noted that Genero Studio Form Designer does not necessarily use the same title for a property as the attribute name is in the .per syntax.
GAS Config Reference
The GAS configuration files have a reference section. These are the most common pages I use to get my GAS configuration files correct, as I can visually see the expected structure and can click on an entry to get the syntax for a particular value.
https://4js.com/online_documentation/fjs-gas-manual-html/#gas-topics/c_gas_xcf_hie_ovw.html
Wrap-Up
Conventions
The BDL document has this section on conventions used by the documentation. .https://4js.com/online_documentation/fjs-fgl-manual-html/#fgl-topics/c_fgl_DocConv_001.html
Feedback
Both the online documentation and the Studio documentation have feedback buttons. If you spot any errors, typos, or if something is unclear, then please use this feature to pass feedback to the documentation team. This doesn’t have to be used for negative feedback, as well this can also be used for positive feedback.
In-product Documentation
As always there are exceptions and these can be found with the GBC documentation. This started out as in-product documentation being written by the GBC developers and shipped inside the GBC product. As such it is in a different format and doesn’t have search or feedback options when viewed online.
To search within this documentation, I have to remember to use the Studio version. When looking up theme variables, I find that I have to quote the value. Too see compare the search results of “$palette-text-primary-100” and $palette-text-primary-100.
You may also come across documentation such as $FGLDIR/doc, and $GGCDIR/doc which you can interpret as developer documentation.
Final Point
When answering a support question, I will always try and include a documentation link in my answer. I do this for two reasons. One is that I am fond of the saying “Give a man a fish you have fed him for a day, teach a man to fish, you have fed him for a lifetime”. So if you do get a documentation link in a support answer, ask yourself why didn’t I find that page myself? Did I look in the wrong documentation? Did I search on the wrong term?
The second reason is that if I can’t give a documentation link, then it probably says the documentation is deficient in this area. Typically it means that we need to add a warning, note, or tip https://4js.com/online_documentation/fjs-fgl-manual-html/#fgl-topics/c_fgl_DocConv_003.html so that we don’t get asked the same question multiple times.
You can also help yourself in this area when raising a support question by providing the documentation link you are looking at. You will get more sympathy if you say “ I am trying to do XYZ and am looking at this documentation page link, but it is not …” as opposed to asking the question “ how do I do this?”