Description of the documentation structure

General description of the structure

Sage X3 documentation is stored in the database.

• ADOCUMENT table for paragraph structure
• ADOCCLB table for texts
• ADOCBLB table for miscellaneous files
• ADOCFNC table for links
• ADOCFLD table for field help

The storage process for data is defined in the annex below.

Documentation generation

• A first generation function makes it possible to create, for each entity to be documented, the structure of the documentation composed of several standardized paragraphs.
• A second generation function uses this data and the entered text to generate the final documentation in the HTML format. Each record corresponds to a paragraph since the documentation is organized in a list of paragraphs.

Structure of a paragraph

• A language code.
• A document type:
• The functional documentation (explanations on how to use the function) is identified by the AFC type.
• The documentation describing the parameters (parameters, activity codes, automatic journals) is identified by the code of the object managing them (ADP, ACV, GAU).
• The miscellaneous documentation is identified by the DI code.
• Menus and sub-menus are defined by the APM code.
• A code to identify the documentation, which corresponds to what is documented. For example, the function code, the setup code, the activity code, or the automatic journal code.
• A level and a sub-level that describe the overlapping of paragraphs.
  The title of the first paragraph of each level is reused in a table of contents making it possible to access directly the documentation sections. When more than one paragraph exists in a given sub-level, a sub-table of contents is created for the corresponding levels.
• A paragraph code determines the way the HTML text is to be generated.
• A screen code defines if it is necessary to insert in the corresponding paragraph an icon that makes it possible to unfold the field help related to the given screen.
• An activity code inherited from the dictionary upon regeneration makes it possible to distinguish the standard records from the specific records. You can also create documentation adapted to given folders by generating only the paragraphs and documentation corresponding to the activity codes activated on this folder.

Note that a paragraph with a FAL activity code (always false) is never taken into account by the generation processing, even when a complete generation is requested. FAL makes it possible to deactivate generated paragraphs that should not be found in a document.

Once the generation process from the dictionary is coming to an end, it is possible to complete the created records in the ADOCUMENT table and add others. Deleting a record in the ADOCUMENT table means deleting the paragraph in the final documentation. However, if this paragraph is generated from the dictionary, launching a regeneration from the dictionary recreates the paragraph.

It is important to note that the paragraphs are listed in the order according to which they must be displayed (the TIT paragraph being the first). Sage advises you to comply with the order, except in particular cases and for generic paragraphs.

The existing paragraphs are linked to several categories.

Paragraphs generated automatically

Some paragraphs automatically recover elements from the dictionary or the link table with a given layout.

These are called generated paragraphs. In this case, upon generation of the ADOCUMENT table, the paragraph is created without text if the elements of the dictionary or the table justify it. It is not necessary to enter text since the dictionary elements are automatically displayed in the paragraph.

If a text is entered into the record, it is automatically added at the end of the paragraph. In this case, the regeneration does not delete the paragraph, even if this paragraph is not justified anymore following the dictionary evolution.

Paragraphs created empty or usual paragraphs

Some paragraphs are created automatically upon generation from the dictionary, but without text, because these are free paragraphs usually present in a given documentation type. The text entered in the ADOCUMENT table is then recovered in the final documentation without a specific layout. Some paragraphs are not created automatically upon dictionary generation, but they can be created afterward. They are called free paragraphs later in this document.

Hypertext links

Except for the specific case described below, creating a paragraph creates an anchor with the same name in the text. It is possible to create a hypertext link to the paragraph in question (the link path being document.htm#anchor instead of document.htm in this case). To access directly the documentation of the third section of the User management function (GESAUS), it is necessary to use a link to GESAUS.htm#ON3.

The codes of the paragraphs that can be found in a document in several examples must have a link per paragraph. In that case, the link is displayed in the following form: PARAG_LEV_SLEV. PARAG is the paragraph's code, LEV is the level's code, and SLEV is the sub-level's code. For an MIS paragraph located at level 140 and sub-level 40 of the ADO_FCT documentation, the link will be ADO_FCT#MIS_140_40.

Documentation types

The Documentation type field defines what you are going to document.

The following grid describes the possible documentation types:

Details on some documentation types

Documentation of AFC type

Documentation of the AFC type is the most extensive. It is used to describe in detail the function, its setup prerequisites (a set of automated sub-paragraphs), its user interface (tabs with field help, buttons, menu items), and appendixes (reports, error, and managed table list).

Part of the paragraphs building it is generated from the dictionary, but you must enter most paragraphs. The code associated with this documentation is the code of the function (as defined in the function dictionary). The name of the corresponding HTML file is generated in the FCT sub-directory of the documentation directory.

You can call it from any screen of the function via the F1 key.

For the generated HTML documentation file and AFC documentation only, all paragraphs considered as part of the function's operation are grouped in another HTML file to separate the functional part from the technical one. A link is created within the original HTML file to the operational HTML file for each type of paragraph.

Here are the paragraphs involved:

• All paragraphs of level 30 (prerequisites)
• All paragraphs of level 100 (tables used)

Documentation of DI type

DI documentation is not linked to a dictionary element. It is used to create technical appendixes and general documentation. For example, in standard documentation, GESAWA.htm is the documentation associated with workflow events. GES_AWA.htm DI documentation is the corresponding technical annex.

DI documentation is generated in the FCT directory.

To prevent functional documentation from being mixed up with DI documentation, it is necessary to insert the _ character in the code.

ACV, ADM, ADP, AOE, ARP, AWA, CDA, CDE, GAU, PS1, and ADC documentation

ACV, ADM, ADP, AHI, AOE, ARP, AWA, CDA, CDE, GAU, PS1, and ADC documentation is object-type documentation. You can access it via Alt + F1 from a setup function. They are used to describe the setup conditions of the current record. Usually, this type of documentation does not contain much text (mainly about the use or description of the code, with potential notes).

Some paragraph codes are specific to thes types of documentation. The code associated with this documentation is the code of the corresponding record. The documentation file is generated in the OBJ sub-directory. It is formed of the object code followed by the record key.

Examples:

• The BPA activity code is generated with the name ACV_BPA.htm.
• The BPR import/export template is generated with the name AOE_BPR.htm.

Note that the setup key is a key in two parts including the corresponding chapter. For example, the help on the ADMUSR setup (SUP chapter) is then generated under the name ADP_SUP_ADMUSR.htm.

Documentation of AML, ATB, and ATY type

Documentation of AML, ATB, and ATY type describes the data structure.

You can access it from the table of contents of the help.

These documentation types contain only one paragraph. You can use a title paragraph to add a comment before the generated documentation. They are generated in the MCD directory and reuse the non-prefixed table code, the code of the data type with the ATY_ prefix, and the local menu number in the MEN####.htm form (#### being the menu number with four numbers, with zeros added before if necessary).

Documentation of APM type

Documentation of APM type is help menus.

This type of documentation is generated from the dictionary. There is only one paragraph in this type of documentation. It is possible to create other documentation to describe the additional menus organizing the documentation. In this case, the paragraph contains the list of called documentation. It is also possible to add additional documentation links in generated documentation of this type.

Documentation of FI type

FI documentation is used to extract documentation. The rule to name this documentation determines the place where the files are created. The details are in the corresponding paragraph.

Documentation menus

All functions manage records that you can document with the documentation function under the following conditions:

• Define in the miscellaneous table 910 the documentation code corresponding to the code of the object for which the record documentation is to be managed.
• The type of documentation corresponds to the object type and the key corresponds to the main key of the documented record. If the key is in several parts, these are divided by the _ character.
• Generate the documentation in HTML format. It is created by default in the OBJ directory, the directory for the object help.
• The help is called on a given record via Alt + F1.

Examples:

AFC corresponds to the function help, and the AFC object manages functions. It is the same for ADP (parameters), ACT (actions), and ACV (activity codes) documentation.

As soon as the code of an object is in the miscellaneous table 910, a Documentation menu is automatically displayed in the menu bar of the corresponding object.

The functions that you can access via the menu are described below.

Documentation / Paragraphs

This menu item allows access to the documentation management on the first paragraph of the documentation (if there is one) associated with the current record.

Documentation / Links

This menu item allows access to link management. It is used to define the links between the current record and other records (for example, the links between functions and parameters). These links are specific to the documentation and are used to load the generation of documentation structures.

Documentation / Generation

This menu item launches a documentation generation. You can also launch it from the Generation button at the bottom of the screen.

You can launch three types of generation one by one or simultaneously

• The generation of the documentation structure from the dictionary (ADOCUMENT, ADOCBLB, and ADOCCLB tables)
• The generation of the documentation from the previous tables
• The generation of the field documentation

The range suggested by default takes into account the current record, but you can modify it at launch time.

Preliminary paragraphs

These paragraphs introduce the functional documentation.

TIT code (title)

This chapter defines the title of the documentation.

When the functional documentation is generated from the dictionary, this chapter is automatically created at level 10 10.

For dictionary documentation (tables, local menus, data types) for which it is the only paragraph, the entered text is a text to insert before the grids describing the technical structure of the dictionary.

For documentation describing a menu (APM type), it is possible to add links to other help pages by identifying them with their codes. A line is then codified in one of the following ways:

• The function code (functional help). Example: GESAUS
• The code of the help with its type as prefix and the / character as separation. Example: DI/ADO_FCT
• Either one of the previous syntaxes followed by the # character and a name tag to position itself in the middle of the document. Example: GESAUS#ON3

For all other types of documentation, it is possible to put in the text only a series of words divided by commas that are inserted in the keyword field (keywords for searches that are not displayed in the text). In this case, there is no associated paragraph and anchor in the final HTML document.

This paragraph type is managed for all documentation types. If this paragraph has an activity code when generating the documentation for a folder on which this activity code is not activated, the documentation is not generated.

Especially if this paragraph has the FAL activity code:

• The final documentation is never generated.
• Regenerating the documentation structure does not result in a generation. The generation stops if the TIT paragraph has the FAL activity code.

If the title is not entered in the record, it is searched in the dictionary according to the context. This makes it possible to manage specific cases such as the field help on RPT* functions where the group name must be the dictionary name.

PRE code (presentation)

This paragraph defines the presentation of the documented entity (function, activity code, sizing setup, setup). All documentation is concerned. This paragraph is automatically created empty at level 10 20.

This is the first paragraph displayed in the final functional documentation.

It is not necessary to enter a text for the presentation of activity codes depending on another code. An automatic text is used if the text field is empty.

Paragraphs for the functional prerequisites

These paragraphs describe the prerequisites necessary to execute the function. They can be present in any functional documentation, even if some can also be present in other documentation such as documentation on activity codes, reports, or workflow events.

For AFC documentation only:

In the generated HTML documentation file, all prerequisite paragraphs are written into an operational annex HTML file. This separates the functional part from the technical one. A link to the operational annex HTML file is created in the original functional HTML file.

PRQ code (prerequisites)

This paragraph defining the prerequisites is present in functional documentation, reports, and import/export templates.

This introduction paragraph is created empty at level 30 10. In functional documentation, this paragraph is only created if another prerequisite paragraph is created. It is always created for import/export and report documentation.

The text is not mandatory. If there is no text, the paragraph exists as an inter-title.

ACV code (activity codes)

This paragraph is present in the function, parameter, and activity codes documentation. This paragraph is generated at level 30 20 with the style 4:

• In functional documentation, it is generated from the dictionary as soon as at least one activity code can be found. Activity codes are searched in the function, the window associated with the function, the object, the inquiry, and the associated tables. It is also possible to associate an activity code with a function via the ADOCFNC link table. It is then a sub-paragraph of the PRQ paragraph.
• In parameter documentation, it is generated via a search in the dictionary and via links between setup and activity code.
• In the documentation describing an activity code, it is generated by taking into account the activity codes depending on the documented activity code. This link is also present in the dictionary.

Upon generation of the final documentation, a search is carried out to find the activity codes with the same algorithm in the dictionary. They are displayed in a grid with links to the documentation describing the activity code.

The system automatically searches the whole dictionary and this can return an important number of unrequested activity codes in the list. There is a specific functionality used to sort the list: The FAL (always false) activity code in the documentation links blocks the search for activity codes in the dictionary. Only the activity codes (FAL excluded) mentioned in the links remain.

ADP code (parameters)

This paragraph is present in functional documentation and documentation on parameters and import/export templates. It is a paragraph generated at level 30 30 with the style 4:

• In functional documentation, this paragraph defines the list of parameters associated with the function. It is generated using the links between function and setup or setup and function. It is then a sub-paragraph of the PRQ paragraph.
• In parameter documentation, the paragraph is generated using a search in the dictionary and associations between setup and link table setup. Parameters from the same group and the same chapter are included.
• In the documentation describing an import/export template, the paragraph describes linked parameters. These linked parameters are searched by going through links between templates and parameters or reciprocally in the link table.

Upon generation of the final documentation, the parameters are sorted by group and displayed in lists with links to the documentation describing the general setup.

ANM code (sequence number counters)

This is a paragraph generated at level 30 40 with the style 4, which is present in the functional documentation and gives the list of sequence number counters used by the function. It is generated as soon as at least one counter is found in the link table. It is possible to associate a counter with a function. This is a sub-paragraph of the PRQ paragraph.

Upon generation of the final documentation, the counters are displayed in a list.

GAU code (auto journals)

This is a paragraph generated at level 30 50 with the style 5, which is present in the documentation on functions and gives the list of automatic journals used by the function. It is generated as soon as at least one automatic journal is found in the link table. It is possible to associate an automatic journal with a function. A sub-paragraph of the PRQ paragraph introduces the GAU and CDE paragraphs. It is preceded by an additional inter-title with a style inferior to the paragraph style (4 by default) named accounting interface.

Upon generation of the final documentation, the automatic journals are displayed in a grid with a link to the documentation describing them.

CDE code (dimensions/default)

This is a paragraph generated at level 30 60 with the style 5. It is present in functional documentation and gives the list of dimension codes used by the function. It is generated as soon as at least one dimension code is found in the link table. It is possible to associate a dimension code with a function. A sub-paragraph of the PRQ paragraph introduces the GAU and CDE paragraphs. It is preceded by an additional inter-title with a style inferior to the paragraph style (4 by default) named accounting interface.

Upon generation of the final documentation, the dimension codes are displayed in a grid with a link to the documentation describing them.

HAB code (authorizations)

In the functional documentation, this optional paragraph is usually a sub-paragraph of the PRQ paragraph.

This is a paragraph generated by default at level 30 70 with the style 4 as soon as one of the following conditions is verified:

• The function has access rights managed according to the site.
• There are authorization options in the dictionary for the function.
• The function is of object type. As such, there are default creation/deletion/modification options.
• An access code is declared at object level if the function is of object type.

Upon generation of the final documentation, a set of automatic texts is created depending on the context (management via access codes, authorization options for the dictionary).

TRS code (transactions)

In the functional documentation, this optional paragraph is usually a sub-paragraph of the PRQ paragraph. It is generated from links between functions and transactions. The TRS-type link associates a function to the function used to set up transactions. The generation is made at level 30 80 with the style 4.

Upon generation of the final documentation, the layout of the transactions is updated, and links to the corresponding functional documentation are inserted.

ECC codes (inquiry screens)

In the functional documentation, this optional paragraph is usually a sub-paragraph of the PRQ paragraph. It is generated from the dictionary by searching a list of inquiry codes found in the folder where the documentation is generated.

This paragraph is generated with the same row as the TRS paragraph. This is logical since both can't coexist (one of them is about inquiries, the other about objects), and both correspond to screen variants. The generation is made at level 30 80 with the style 4.

PRD code (other prerequisites)

This paragraph generated at level 30 90 with the style 4 is present in functional documentation. This paragraph gives a series of other prerequisites displayed in the form of sub-paragraphs with inter-titles of style 5:

• The first of them gives the list of miscellaneous tables to update. It is loaded by the links between the function and miscellaneous tables.
• The second gives the list of database tables to update. It is loaded by the links between the function and the tables (by the AT2 code, the ATB code loading the update tables).
• The third gives the list of local menus that are necessary to enter. It is loaded by the links between the function and local menus.
• The last sub-paragraph, named Miscellaneous prerequisites, is present if a text was added to the documentation. If the text begins with a title (with a Hn tag, n being a number), the Miscellaneous prerequisites inter-title is not inserted.

Description of the interface

These generated paragraphs describe the organization of the entry window associated with the function. They are generated automatically only if there is a window associated with the function. The final generation includes the functional help if the Screen field present in the record is entered.

The paragraphs are the following:

ECR code (screen description)

This paragraph is an introduction that defines the number of tabs and describes the specificities of the selection panel.

When the functional documentation is generated from the dictionary, this chapter is automatically created at level 40 50 with the style 3.

ENT code (screen header)

This paragraph describes the header fields of the window. The text entered here is inserted as is in the final documentation. As soon as the screen code is entered in the setup, the title bar includes a small icon in the form of a bottom arrow. This icon automatically unfolds the list of header fields and their corresponding field help. As a general rule, the text is used to give the detail of the fields forming the object key or the inquiry criteria.

When the functional documentation is generated from the dictionary, this chapter is automatically created at level 40 100 with the style 3 as soon as the window corresponding to the function uses a header mask.

ON1 to ONF codes (tabs)

These paragraphs describe each of the tabs of the window associated with the function. The title bar includes a small icon in the form of a bottom arrow, which automatically unfolds the list of header fields (and their corresponding field help) if the screen field is entered in the record, which is not the case for an automatic generation.

As a general rule, this text gives information on the fields present in the tab (without necessarily giving the detail of the help for each field, since the online field help is also available via unfolding). If no text is assigned, a generic text proposes to unfold the field help.

When the functional documentation is generated from the dictionary, this type of chapter is automatically created at level 40 from the description of the window associated with the function. The generation sub-levels are calculated from the row of the tab (ROWMSK field) to comply with the presentation order of the function tabs when adding specific tabs which have to be inserted between two existing tabs. The sub-level equals the rank multiplied by 200. So if the ranks are numbered in tens, the resulting ranks are 2000, 4000, 6000. The minimum rank is 200 and the maximum is 19800.

When generating the documentation, the paragraphs describing the Button on grids (right-click) actions are automatically created following the paragraph linked to each tab. They are numbered by 5 to give the possibility to insert miscellaneous paragraphs.

BOT codes (clicks on grids)

These paragraphs describe each of the functions available via a right-click on a grid. There can be several of them with the same code. The corresponding anchor is BOT_LEV_SLEV, where LEV is the level and SLEV the sub-level. Each of these buttons must be inserted in the order of the paragraphs, just after the paragraph describing the tab on which it is placed.

When the functional documentation is generated from the dictionary, these paragraphs are automatically created at level 40 with a numbering range from 5 to 5 beginning with the tab number (2,005, 2,010, 2,015, etc. after the tab of row 10 for example). Style 6 is used by default, and an inter-title named Functions available via a right-click on the grid, of style 5, is used in the consecutive paragraphs of this type.

BOU codes (buttons)

These paragraphs describe each of the buttons that are available at the bottom of the screen. There can be several of them with the same code. The corresponding anchor is BOT_LEV_SLEV, where LEV is the level and SLEV the sub-level. These buttons are usually positioned after the paragraphs associated with the tabs. The first of them is an introduction paragraph which title uses a standard style (3 by default). The title of the following consecutive BOU chapters is displayed in a button framework, which means that the text must correspond to the button text. The corresponding text is then put on the right of each button.

When the functional documentation is generated from the dictionary, these paragraphs are automatically created at level 70 with a sub-level beginning with 19 (title of the chapter about buttons) and then going 10 by 10 (20 for the first button, 30 for the second, etc.).

BME codes (menu bars)

These paragraphs describe each of the functions available via the menu bar. There can be several of them with the same code. The corresponding anchor is BME_LEV_SLEV, where LEV is the level and SLEV the sub-level. These paragraphs are positioned after the paragraphs. The first of them is an introduction paragraph which title uses a standard style (3 by default). The title of the consecutive chapters has the standard style 4.

When the functional documentation is generated from the dictionary, these paragraphs are automatically created at level 80 with a sub-level beginning with 19 (title of the chapter about menus) and then going 10 by 10 (20 for the first button, 30 for the second, etc.)

Annex paragraphs

These conclusion paragraphs give annex information (list of errors, reports, batch tasks, etc.). These are the following:

RPT code (reports)

This paragraph generated at level 50 10 with the style 4 is present in the functional documentation and gives the reports used by the function. It is generated from the dictionary. The search from the print codes is defined in the dictionary of functions for Print and List, by searching if reports are associated with them in the print code table. This report list is completed by the reports found by searching for links between the function and the reports in the link table.

Upon generation of the final documentation, a grid is generated. This grid contains the reports launched from the function with hypertext links pointing to the corresponding documentation.

ABT code (batch tasks)

This paragraph generated at level 60 10 with the style 4 is present in the functional documentation and gives the list of batch tasks used to launch the function in batch mode. It is generated from the dictionary via a search in the batch task table. This task list is completed by the tasks found by searching for links between the function and the batch tasks in the link table.

Upon generation of the final documentation, a grid containing the list of existing tasks is generated.

ERR code (errors)

This paragraph is dedicated to the list of errors that can be displayed when using the function. Its entered text is directly inserted in the document. Only errors specific to the function are inserted here. Indeed, generic errors are listed in a dedicated document and a link to this document is automatically inserted in this paragraph. Moreover, the paragraph is created empty.

This type of paragraph is also used in the documentation on import/export templates, with the same characteristics.

When the functional documentation is generated from the dictionary, this chapter is automatically created at level 80 10 with the style 3. If no text is associated with the paragraph, a message indicates that the only known errors are generic errors (which can be accessed using the link). Otherwise, the text lists the errors and the corresponding explanation. Use the H5 style for the error text and the default paragraph style for the explanation. This gives the following result:

 It is possible to use the mess() 4GL syntax for the error text. This makes it possible to have a fixed translation for the error text.

For example:

Which results in the following upon generation:

ATB code (managed tables)

This paragraph is present in the functional documentation and on the documentation on sizing parameters, on import/export templates, reports, workflow rules, and events triggering statistics. It is a paragraph generated at level 100 10 with the style 3:

• In the functional documentation, it is generated from the dictionary as soon as at least a table is found. Tables are searched in the object inquiry. It is also possible to associate a table with a function via the link table.
• In AFC documentation, in the generated HTML documentation file, this Tables used paragraph is written into an operational annex HTML file to clearly separate the functional part from the technical one. A link is created within the original HTML file to the operational HTML file.
• In other documentation, the same principle is applied. The paragraph is generated if the dictionary is used to find tables, or if links are found.
• In the case of the documentation on sizing parameters, the listed tables are those which size depends on the setup.

Upon generation of the final documentation, the tables are displayed in a grid including a link to the table dictionary and to the object, when it exists. This grid makes it possible to manage the table concerned. If there are tables common to all folders, they are isolated in a dedicated paragraph.

Specific paragraphs

These paragraphs can be inserted everywhere in the documentation to manage exceptions or unplanned additional paragraphs. They are also used to segment a paragraph when it is too long (the length of the text entered within a paragraph being limited).

Since the code used for these paragraphs can be repeated, no anchor has the same name. Technical anchors are created. They are numbered with the paragraph code, followed by the level and sub-level, and divided by the _ character.

The paragraphs are the following:

MIS codes (miscellaneous)

This is a miscellaneous paragraph present in the table of contents linked to the corresponding level. A title, a style, and a text to insert are entered.

Since several paragraphs of this type can exist in documentation, the anchor corresponding to these paragraphs is MIS_LEV_SLEV, where LEV represents the level and SLEV the sub-level.

MIN codes (miscellaneous)

This miscellaneous paragraph is not present in the table of contents linked with the corresponding level. A title, a style, and a text to insert are entered.

Since several paragraphs of this type can exist in documentation, the anchor corresponding to these paragraphs is MIN_LEV_SLEV, where LEV represents the level and SLEV the sub-level.

LNK codes (links)

This type of paragraph is used to insert tables of contents in the form of:

• A list of header links (located in the documentation title bar). This implies that the paragraph of LNK type is located at the same level as the TIT paragraph of the corresponding documentation. The title of the paragraph gives the title of the current document as defined in the link list.
• A list of links (like a table of contents) in the general case. This type of paragraph is used to insert links to documentation that cannot be directly accessed in the hierarchy of the document.

When the link defines a separated paragraph, the title and the style are not taken into account, and no entry is displayed in the table of contents. When it is requested to add a title to this paragraph of links, it is enough to have before it a paragraph of MIS or MIN type.

Links are defined in the paragraph text under one of the following forms:

• CODE_FONCTION
• CODE_FONCTION#anchor
• TYPE/CODE
• TYPE/CODE#anchor

Here is the meaning of these elements:

• CODE_FONCTION is the functional documentation code (of AFC or DI type): the link points to the FCT sub-directory, where this type of documentation can be found.
• TYPE corresponds to the different types of documentation. The code after it is the documentation code.
• anchor corresponds to a paragraph anchor when it is requested to be directly placed on a given paragraph. The anchor is not taken into account if this is a header link.

Each link is explored upon generation. The corresponding documentation is searched in the ADOCUMENT table. If it does not exist, the link is not inserted. The documentation title is inserted with the text carrying the link.

INC codes (inclusion)

This paragraph is used to include a paragraph already present in another documentation.

Any paragraph can be included, except for paragraphs of TIT type. When it is requested to reuse a presentation paragraph associated with another documentation, the INC paragraph replacing it must be the first of this type in the documentation and must link to another paragraph of PRE type.

Since several INC paragraphs can exist in such documentation, the anchor corresponding to these paragraphs is INC_LEV_SLEV, where LEV represents the level and SLEV the sub-level.

The paragraph to reuse must then be identified in the text of the inclusion paragraph in one of the following forms:

• TYPE/CODE
• TYPE/CODE/LEVEL/SUB-LEVEL

The level and the sub-level are not mandatory. The paragraph of the same level and same sub-level are recovered by default in the linked documentation.

For example, when it is requested to insert the paragraph relating to the first tab of the user record, which is defined at level 40 and sub-level 200, the text in the inclusion paragraph is the following: AFC/GESAUS/40/200

Everything is recovered from the source paragraph (title, text, layout, field helps), except for the level and sub-level which remain the same as in the original paragraph. The breaks in the tables of contents are respected. The title of the table of contents corresponds to the title of the original INC paragraph. The created anchor can be used for links and corresponds to a generic INC_row_sub-row anchor.

Paragraphs reserved for other documentation

These paragraphs are specific to documentation types other than functional documentation. These are the following:

LEV code (level)

This paragraph is specific to parameter documentation. It is generated from the dictionary at level 30 10.

Upon final generation, a text specifying the setup definition level is generated, as well as the name of the associated global variable if it exists. If no global variable can be found, a text saying that there is none is inserted, except if the text of the record is assigned. In this case, the text can refer to a variable not declared in the dictionary.

REM code (remarks)

This paragraph is specific to parameter documentation on automatic journals and default dimension codes. It is created empty from the dictionary at level 70 10.

The text in the record is made available to enter miscellaneous remarks.

PAR code (parameters for the actions)

This paragraph is specific to documentation on actions. It is generated from the dictionary at level 30 10 to make possible the display of a list of action parameters.

Upon generation of the final documentation, an introduction sentence is created, followed by a grid displaying the parameters, their title, and type of data. When there is no setup, a negative sentence is inserted.

UTI code (use of the action)

This paragraph is specific to documentation on actions. It is created empty from the dictionary at level 40 10.

The text entered in the record describes the use of the action.

If this paragraph remains empty at the moment of the final documentation generation, it is not generated.

ACT code (actions associated with the actions)

This paragraph is specific to documentations on actions. It is generated at level 50 10 to make possible the display of the list of actions linked to the documented action.

The generation is made from the links (and reciprocal links) found between action and action.

Upon generation of the final documentation, an introduction sentence is created, followed by a grid displaying the actions with a link to the corresponding documentation.

REC code (recommended values)

This paragraph is specific to documentation on parameters and sizing parameters. It is created empty for parameters and generated for sizing variables. A default line containing the value found in the reference folder is created if the paragraph is empty. The creation is done at level 30 10.

The text entered in the record describes the advised values for the setup in question.

AFC code (functions concerned)

This paragraph is specific to documentation on activity codes, general parameters, and reports. It is generated at level 40 10 for activity codes and reports, and at level 50 10 for general parameters. This paragraph displays:

• The list of functions concerned by the activity code. The generation is based on:
  • Links reciprocal to the links between functions and activity codes
  • Activity codes found during an exploration of the dictionary
  Only functions directly depending on the activity code are retrieved. Upon generation of the final documentation, an introduction sentence is created, followed by a function list with a link to the corresponding documentation.
• The way to access the report. These are generally print groups and a list of the functions that can launch the report. The generation is then made by analyzing the dictionary and reading the links common to the links between functions and reports. Upon generation of the final documentation, an introduction sentence is created. This sentence is followed by an automatic text specifying:
  • Whether the report can or cannot be directly run
  • To which print group it belongs
  • A list of functions that can launch the report with a link to the corresponding documentation
• The functions that are impacted by the setup.

AT2 code (tables to be entered)

This paragraph is specific to documentation on import/export templates. It is generated at level 30 30 with the style 4 to display the list of tables that are supposed to be entered. You are then able to use the corresponding template. It is a sub-paragraph of the PRQ chapter. The generation is done from the links between import/export templates and tables of AT2 type.

Upon generation of the final documentation, the tables are displayed in a grid and are preceded by an introduction sentence. A link pointing to the table dictionary and the object when it exists is included. This link makes it possible to manage the table in question. If there are tables common to all folders, they are isolated in a dedicated paragraph.

CHO code (mandatory fields)

This paragraph is specific to documentation on import/export templates. It is created empty at level 40 10 to display the list of fields that are mandatory for the template to work.

CRI code (launch criteria)

This paragraph is specific to documentation on reports and sub-programs.

In the case of reports, this paragraph is generated by default at level 30 30 with the style 4. It uses the data of the report dictionary to generate the following automatic texts:

• An introduction sentence followed by the list of report parameters (a negative sentence is displayed if there is no setup)
• A sentence specifying the specific behavior of start/end parameters
• A sentence specifying if one of the parameters can be entered with several values (segmentation of the report)
• A sentence specifying if data is filtered according to the site depending on the user authorizations
• A sentence specifying if a report can only be printed on a specific type of printer

In the case of sub-programs, this paragraph is generated by default at level 20 30 with the style 4. It uses the data of the sub-program dictionary to list the parameters to transmit to the sub-program.

DES code (description of the report)

This paragraph is specific to documentation on reports. It is created empty at level 40 10 to describe the report content.

CTX code (context)

This paragraph is specific to documentation on workflows, events triggering statistics, and entry points.

For events triggering statistics and workflows, this paragraph is created empty at level 30 10 to describe the triggering context.

For entry points, there can be several paragraphs of this type. One entry point documentation can integrate several entry points. Each time, an APE paragraph is created, defined at level 20 and sub-level 10, with an increment of 10 on all levels. An associated CTX paragraph is created at the same level as the corresponding APE paragraph, at sub-level 20. The anchor corresponding to these paragraphs is CTX_LEV_SLEV, where LEV represents the level, and SLEV the sub-level.

When generating the final documentation, this paragraph integrates automatic sentences saying:

• If there is or not a current transaction (TRS link from the processing dictionary; the associated value 1 means that there is no transaction, the value 2 that there is one)
• If there is or not an open log file (TRA link from the processing dictionary; the associated value 1 means that there is no open log file, the value 2 that there is one)

This paragraph also integrates a list of online tables in the form of a grid. This list is obtained using links from the processing dictionary to tables. A link of ATB type means that the table is open and entered in the context. A link of AT2 type means that the table is open. These links can be entered in the CODE_TABLE [ABBREVIATION] form when the table is not open under its main abbreviation.

APE code (entry point)

This paragraph is specific to documentation on entry points.

For entry points, there can be several paragraphs of this type. One entry point documentation can integrate several entry points. Each time, an APE paragraph is created, defined at level 20 and sub-level 10, with an increment of 10 on all levels. The corresponding anchor is APE_LEV_SLEV, where LEV represents the level, and SLEV the sub-level. An associated CTX paragraph is created at the same level as the corresponding APE paragraph, at sub-level 20.

When the functional documentation is generated from the dictionary, this chapter is automatically created at level 20 with the style 10. The next ones are created by counting levels by tens. The entry point code is retrieved through an APE link. The associated name gives the entry point code. This link can be followed by links of ATB, AT2, TRA, and TRS types. The declaration order is important: since there can be several APE links, the other links should refer to the last link declared.

The code of the entry point can also be found in the paragraph title. This code must remain in the title header. It can be completed by an explanation, separated from the code by a space or an opening bracket. If this precaution is not taken, the final documentation cannot be generated properly.

Upon generation of the final documentation, these paragraphs integrate automatic sentences saying:

• If there is or not a current transaction (link of TRS type from the processing dictionary; the associated value 1 means that there is no transaction, the value 2 that there is one)
• If there is or not an open log file (link of TRA type from the processing dictionary; the associated value 1 means that there is no open log file, the value 2 that there is one)

They also integrate a list of online tables in the form of a grid. This list is obtained using links from the processing dictionary to tables. A link of ATB type means that the table is open and entered in the context. A link of AT2 type means that the table is open. These links can be entered in the CODE_TABLE [ABBREVIATION] form when the table is not open under its main abbreviation.

OPM code (operation mode)

This paragraph is specific to documentation on automatic journals and default dimension codes. It is created empty at level 30 10 to describe the operating mode.

FLW code (description of the information flow)

This paragraph is specific to documentation on reports. It is never created automatically. Sage advises to place it on level 40 10. Use this paragraph to describe the workflow sequences in which this event takes place.

Summary of the paragraph structures

There are for each type of documentation the generated paragraphs and their default structure presented below. You can insert INC, LNK, MIS, and MIN paragraphs freely.

AFC (functional documentation)

This documentation, which is created in the FCT directory, can contain the following paragraphs:

ADP (documentation on setups)

This documentation, which is created in the OBJ directory, can contain the following paragraphs:

ACT (documentation on actions)

This documentation, which is created in the OBJ directory, can contain the following paragraphs:

Concerning the PRE paragraph:

• You can view its content directly viewed in the action dictionary and modify it directly from this dictionary.
• A default text is generated in the paragraph if it is empty. This text specifies that this is an internal action that should not be used in a specific development.

ACV (documentation on the activity codes)

This documentation, which is created in the OBJ directory, can contain the following paragraphs:

ADM (documentation on sizing variables)

This documentation, which is created in the OBJ directory, can contain the following paragraphs:

AOE (documentation on import/export templates)

This documentation, which is created in the OBJ directory, can contain the following paragraphs:

ARP (documentation on reports)

This documentation, which is created in the OBJ directory, can contain the following paragraphs:

AWA (documentation on workflows)

This documentation, which is created in the OBJ directory, can contain the following paragraphs:

CDE (documentation on dimension codes)

This documentation, which is created in the OBJ directory, can contain the following paragraphs:

CDA (documentation on destinations)

This documentation, which is created in the OBJ directory, can contain the following paragraphs:

GAU (documentation on automatic journals)

This documentation, which is created in the OBJ directory, can contain the following paragraphs:

PS1 (documentation on triggering statistics)

This documentation, which is created in the OBJ directory, can contain the following paragraphs:

ATB (dictionary for the tables)

There is only one paragraph for this type of documentation, which is created in the MCD directory:

AML (dictionary for local menus)

There is only one paragraph for this type of documentation, which is created in the MCD directory:

ATY (dictionary for data types)

There is only one paragraph for this type of documentation, which is created in the MCD directory:

ADC (dictionary for entry points)

This documentation, which is created in the OBJ directory, can contain the following paragraphs:

ASU (documentation on sub-programs)

This documentation, which is created in the OBJ directory, can contain the following paragraphs:

Concerning the PRE paragraph:

• You can view its content directly in the sub-program dictionary and modify it directly from this dictionary.
• A default text is generated in the paragraph if it is empty. This text specifies that this is an internal sub-program that should not be used in a specific development.

AGB (documentation on variables)

This documentation, which is created in the OBJ directory, can contain the following paragraphs:

Concerning the PRE paragraph:

• You can view its content directly in the sub-program dictionary and modify it directly from this dictionary.
• A default text is generated in the paragraph if it is empty. This text specifies that this is an internal sub-program that should not be used in a specific development.

AHI (documentation on purge rules)

This documentation, which is created in the OBJ directory, can contain the following paragraphs:

APM (intermediate menus)

This type of documentation is used in two cases:

• When a function of Menu type exists, the generation creates documentation of APM type, with only one paragraph of TIT type. The final generation searches the list of functions associated with the menu to list the corresponding functions. The links can be directly added in the paragraph in this specific case (same syntax as for LNK paragraphs) to add menu lines below the ones found elsewhere in the dictionary.
• All intermediary menus associated with miscellaneous documentation (activity codes, workflow event) are of APM type. The name begins with the code associated with the documentation type, followed by an _ character and a qualifier (module, group) if necessary to have available intermediary menus, the main menu having the code TYPE_0. For example:
  • The intermediary menus associated with activity codes are ACV_0 (root), ACV_1 (activity codes associated with the module number 1), ACV_2, and so on.
  • The intermediary menus associated with the parameters are ADP_0 (root), ADP_TC (parameters of the TC category), ADP_SUP (parameters of the SUP category), and so on.

Creating documentation enabling intermediary menus must be built as DI documentation including the following paragraphs:

• A TIT paragraph on 10 10
• A PRE paragraph on 10 20, which can be empty
• Possibly a first LNK paragraph on row 10 30 to enter navigation links in the title bar
• An LNK paragraph with a row superior or equal to 20 to list the menu item links

AD (online help for the language)

This type of documentation is created in the 4GL directory. This documentation has a free structure. The only mandatory paragraph is:

When this is the only paragraph, no file linked to the record can be generated. But, the linked file, if present, is extracted under the documentation name. This functionality was designed to allow a full recovery of the existing 4GL documentation, each document being seen as a file in the base.

As soon as there is more than one paragraph (when adding paragraphs of MIS or MIN type), the documentation is created according to the usual rules.

Documentation with a code ending with the characters _D is created with a file ending with the $ character. To prevent the creation of keys containing special characters, this renaming rule is applied. Thus, the seg$, chr$, and getenv$ functions are represented by the SEG_D, CHR_D, and GETENV_D records.

FI (files to be extracted)

This is a specific type. It is only a tag for files to extract. The naming principles are the following:

• Documentation of FI type and XXXXX_nnn code is a tag for files to extract in the XXXXX directory. Any standard directory can be defined. It is possible to create as many paragraphs as needed to define different file groups.
• _nnn documentation is a tag for files to extract in all XXXXX directories for which there is a documentation of FI type and with an XXXXX_nnn code. Upon generation of documentation of FI type and XXXXX_nnn code, there is a control to check if there are paragraphs of the same level and sub-level in the corresponding documentation of FI type and _nnn code (the number must be the same). If there are, these files are extracted first. The files linked to the documentation of XXXXX_nnn code can be extracted only after. It is possible to define in such documentation common files, some of which can be overwritten upon extraction of the corresponding documentation of XXXXX_nnn code.
• Documentation of FI type and _ code (only one underscore) is a tag for files which generation triggers the creation of files in the help root directory. When this documentation is generated, all the files attached to documentations of FI type and _nnn code are extracted if the first number of the code is 0 (and if the level and sub-level correspond).

Other types of documentation

The other types of documentation (DI, IN, CS, DL, AM) are documents with an undefined structure (but whose generation directories are defined for the type). The only mandatory paragraph is the TIT paragraph.

When this is the only paragraph, no file linked to the record can be generated. But the linked file, if present, is extracted under the documentation name.

As soon as there is more than one paragraph (when adding paragraphs of MIS or MIN type), the documentation is created according to the usual rules.

The generation directories are specified in the grid below:

Documentation tables of contents

The tables of contents forming the documentation are linked to the APM documentation type. There is usually only one paragraph in this case:

This paragraph can contain a list of documentation codes in the form of a text. In this case, each item of the list is added as a link to the documentation in question. The title of the linked documentation is reused in the documentation. This makes it possible to create tables of contents manually or add additional links to an existing table of contents.

Upon generation of the documentation from the dictionary, documentation of APM type is generated automatically with only the TIT paragraph. The grid below describes the codes of the created documentation and the tables of contents generated in the documents created upon the final generation:

For all types of documentation other than those listed above, it is possible to create a documentation which code is INDEX. If this documentation exists, a link is created directly from each documentation of this type in the title bar. For example, documentation of IN and DL type use an index of this type.

Management of documentation tables

The documentation structure is stored in the ADOCUMENT table. For each paragraph and sub-paragraph, this table stores their characteristics (level, sub-level, title, activity code).

The paragraph text is stored aside in the ADOCCLB table. This table only contains the elements of the paragraph keys and the text itself.

Here is the point of this structure:

• All standard paragraphs of the documentation are stored in the supervisor root folder.
• When a folder is created, the ADOCUMENT table folder is duplicated. This is never the case for document texts.
• Any specific paragraph addition is to be performed within the child folder, as the associated texts are stored in the same folder.
• Any modification to a standard paragraph triggers its copy to the ADOCCLB table from the root folder to the child one.

Only the specific texts are stored in the child folder.

This is the same thing for the texts linked to field help: the standard texts are stored in the ADOCFLD table of the root folder, the specific texts are stored in the folder itself.

When the documentation is generated, the stored structure is searched in the local folder and for each paragraph. The text of the local folder is retained. If the folder does not contain text, then the text from the root folder is retained.