Development > Data and parameters > Documentation > 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

    SEEREFERTTO 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.

    • Code (field COD)

    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.

    • Level (field LEV)

    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).

    • Sub-level (field SUBLEV)

    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).

    • Description (field TIT)

    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 (field MODULE)

    Module to which the documentation parameterization belongs.

    • Style (field STY)

    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.

    • Translation priority (field PRIO)

     

    • Owning group (field CREGRP)

     

    • Validation (field VLDDAT)

    Corresponds to the date on which the record has been validated.

    • field VLDFLG

    This indicator signifies that he record has been considered as valid.

    Text

    • field TEXTE

    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 :

    • certain paragraphs are not inserted as they are. This is notably the case for title paragraphs, which contain a list of keywords inserted in the HTML code of the documentation (section Keywords).
    • certain paragraphs are generated from the dictionary. The text entered heres becomes an addition (before or after the text generated according to the case) and in general is not mandatory.
    • in the documentation of the type APM (documentation summaries corresponding to the menu levels), the text entered is interpreted as a list of additional links to the corresponding documentation (automatic links being generated ).

    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

    • field OBJET

     

    • field CLES

     

    Block number 2

    • From folder (field DOSORG)

    Indicate the folder from which the record is going be copied. The possible syntaxes are described in the dedicated appendix.

    • All folders (field TOUDOS)

    This option is used to copy the record to all the folders defined in the dictionary (ADOSSIER table from the current solution).

    • To folder (field DOSDES)

    Indicate the folder in which the record is going be copied. The possible syntaxes are described in the dedicated appendix.

    Close

    Gives access to the copy function of all the paragraphs of the current documentation to another folder.

    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.

    Error messages

    The only error messages are the generic ones.

    Tables used

    SEEREFERTTO Refer to documentation Implementation