Documentation
This function is used to update the user documentations stored in the database of the current folder in the form of standardized paragraphs to which can be linked additional files such as pictures or schemas.
Each documentation is defined by a type and a code linking it to the documented software. The code is not the same depending on the documentation. An annex describes in detail the possible documentation types and the way the code is defined.
Prerequisites
Refer to documentation Implementation
Screen management
Each record corresponds to a paragraph of the documentation. The key of a record is made up of the language code, the documentation and code type, as well as a level and sub-level which make it possible to have intermediary tables of content in the documentation.
The left list contains the 4 following panes:
- The normal list and the last read are the usual lists.
- The prioritized list makes it possible to view the documentations linked to the type of current documentation and language. When unfolded for a given documentation, this list displays first the documentation levels (which correspond to the table of contents located in the document header), and second the sub-levels attached to each documentation (sub-tables of contents).
- The list named Current documentation is used to display all paragraphs of the documentation corresponding to the current record.
Entry screen
Presentation
Each paragraph of the documentation is entered is the only tab of the function. There are key elements (language, type, code and overlapping of paragraphs), information defining the style and the way the paragraph is generated, as well as the text of the paragraph, if necessary.
The entry of a paragraph is carried out using an HTML editor, whose use is described in detail in an annex documentation.
Close
Fields
The following fields are present on this tab :
Block number 1
| This field makes reference to the languages table and defines the language in which the documentation is written. |
| This field defines the type for the documentation. Each type is associated with a type of documented element (functional documentation, describing a record in the dictionary or the parameterization values, describing the structure of the dictionary, miscellaneous). When a documentation type corresponds to an object code, a Documentation entry is automatically created in the menu bars for the object in question. It is then possible to document the records entered in the object in question. It is for this reason the functional help is codes AFC (code for the Functions object), the help on the general parameters is coded ADP (code for the Parameters object)... The rules for naming the documentation are defined in a documentation appendix. |
| This field defines the code for the documentation. It corresponds in principal to the code for the record (function, parameter...) that is being documented. The rules for naming the documentation are defined in a documentation appendix. |
| This level establishes a hierarchy in the paragraphs. Each first paragraph for a level is present in the principal materials table (except if it is of the type MIN). |
| This sub-level establishes a sub-hierarchy in the paragraphs. Once there is more than one sub-level by documentation, a secondary material table is established in the first sub-paragraph, displaying the links to the next sub-levels (except if the sub-paragraph is of the type MIN). |
Characteristics
| The paragraph code determines the fashion in which the paragraph is generated in the final document. This can be a simple recopy of the text or a more sophisticated generation depending on the dictionary. An annex documentation details the paragraph codes used as a function of documentation type. |
| When a screen code is entered in this field, a pictogram present in the paragraph title in the generated documentation is used to open a section containing the list of the fields in the screen and field associated helps. It is advisable to use a paragraph style equal to 4 (most readable size for the unfolded pictogram). |
| This field is the title for the paragraph. If it is empty, a default title is assigned as a function of the paragraph type (whether in creation or in modification mode). In the case of miscellaneous paragraphs that do not appear in the materials tables (of the type MIN), the fact of entering the title with the character " ! " deactivates the insertion of a title. |
| This activity code, inherited from the dictionary during the regeneration, is notably used to make the distinction between the standard and custom/specific records and also to create adapted documentation in the given folders by only generating the paragraphs and documentation corresponding to the activity codes active in the folder. It should be noted that the activity code FAL (always false) is taken into account specifically : a paragraph marked with this code is never taken into account by the generation process, even if a complete regeneration is requested. This is used to de-activate the generated paragraphs that are not required in a documentation. |
| Module to which the documentation parameterization belongs. |
| The style makes reference to a numeric value corresponding to a "H1","H2,"H3" ... marker according to the number chosen. If this field is empty, by default it takes the value 3. For sub-paragraphs, it is advisable to use 4, 5 or 6 according to the level. The title 4 is presented in a band : a pictogram gives access to the field helps on a visible field if a screen is associated with the paragraph. |
|
|
| This field is used to display the Group creating the given documentation. It is only available in the environments in which this notion has been implemented. This applies to the environments in which the user parameter GRPDEV exists. NOTE: The group is displayed in Red when the user group is different from the creating group found in table AOBJGRPDEV |
| Corresponds to the date on which the record has been validated. |
| This indicator signifies that he record has been considered as valid. |
Text
| This field is used to enter the text for the paragraph as it will appear in the final documentation. The following particular cases need mentioning :
|
Close
Specific Buttons
Gives access to the generation of the final documentation (htm extension file in the directory defined by the DIRDOC setup), but also to the generation of the current documentation paragraph dictionary. |
The following fields are included on the window opened through this button : Block number 1
Block number 2
Close Gives access to the copy function of all the paragraphs of the current documentation to another folder. |
- Option / Paragraphs / Paragraph renumbering
- Option / Paragraphs / Deletion of paragraphs
- Option / Paragraphs / Paragraph where-used
- Links / Option / Linked file documentation
- Option / Links / Documentation links
- Option / Actions / Copy documentation
- Option / Actions / Extract documentation
- Option / Actions / Assign translation priority
- Option / Verifications / Checking documentation
- Option / Verifications / Purging documentation
- Option/Validation
Menu Bar
Option / Paragraphs / Paragraph renumbering
Is used to renumber the paragraphs of a documentation by specifying the renumbering range, the target level and the renumbering increment. A simulation can be carried out beforehand.
Option / Paragraphs / Deletion of paragraphs
Is used to delete all the paragraphs of a documentation. A confirmation window opens to ask for confirmation. It displays the number of paragraphs to be deleted When answering Yes, the operation cannot be cancelled.
Option / Paragraphs / Paragraph where-used
Is used to open a window to enter linked documents (notably pictures) which are extracted at the same time as the principal documentation upon generation.
Links / Option / Linked file documentation
Is used to copy documentations in bulk. See technical annex for the possible syntaxes of folders.
Option / Links / Documentation links
Is used to extract the current documentation as a whole (or a set of current documentation) in the form of a standardized XML file to the XML sub-directory of the generation directory. This XML file contains the structure and texts of the documentation. It can be used by translation tools.
Option / Actions / Copy documentation
Is used to update the Validation indicator (and the validation date if the box is ticked) for all the documents of the base.
Option / Actions / Extract documentation
Is used to tunnel to the function defining the documentation links for the current documentation.
Option / Actions / Assign translation priority
Is used to launch a consistency check between the documentation and the dictionary (checking modules for instances)/ An error log file is displayed upon execution end of the function.
Option / Verifications / Checking documentation
Option / Verifications / Purging documentation
Option/Validation
Is used to update the Validation indicator (and the validation date if the box is ticked) for all the documents of the base.