Documentation
This function is used to update the user documentation stored in the database in the current folder, in the form of standardized paragraphs, to which it is possible to attach additional files such as images and diagrams.
Each document is defined by a type and a code that attaches it to the documented software. The code differs according to the documentation type. A detailed appendix for the possible documentation types and how their codes are defined is available.
Prerequisite
Refer to documentation Implementation
Screen management
Each record corresponds to a paragraph in the documentation. The key for a record is made up of the language code, the documentation type and the code, as well as the level and sub-level that is used to organize the tables for the intermediate material in the documentation.
The left list contains 4 windows as follows :
- The standard list, the last read list are the normal lists
- The hierarchy list is used to view the documents linked to the current documentation type and the current language. This hierarchy appears when it is opened up for a given document, firstly as the documentation levels (that correspond to the subject table located in the document header), then the sub-levels attached to each document (sub-tables for the subjects).
- The list named Current documentation is used to display all the paragraphs in the documentation corresponding to the current record.
Entry screen
Presentation
Each documentation paragraph is entered in a single tab in the function. Located here are the elements of the key (language, type, code and the overlapping of the paragraphs) as well as the information defining the style and the fashion in which the paragraph is generated plus the text in the paragraph.
The entry of a paragraph is made by means of an HTML editor, the use of which is detailed in an appendix.
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. |
|
|
|
|
| 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 (file with extension htm, in the directory defined by the parameter REPDOC), but also on the generation from dictionary of paragraphs or the current documentation. |
The following fields are present on the window opened through this button : Block number 1
Block number 2
Close Gives access to the copy function for all the paragraphs in the current documentation to another folder. |
- Option / Paragraph renumbering
- Option / Suppression of paragraphs
- Option / Linked file documentation
- Option / Copy documentation
- Option / Extract documentation
- Option / Validation
- Option / Document lines
- Option / Checking documentation
- Option / Purging documentation
- Option / Verifications / Purging documentation
- Option / Validation
Menu Bar
Option / Paragraph renumbering
Presentation
Used to renumber the paragraphs in a document by specifying the renumbering range, the target level and the renumbering step. A simulation can be carried out beforehand.
Close
Fields
The following fields are present on this tab :
Block number 1
| Define the type of the documentation to be taken into account. |
| Define the code of the documentation to be taken into account. |
Start - end range
| Define the minimum level for the paragraphs to be renumbered. |
| Define the maximum level for the paragraphs to be renumbered. |
| Define the minimum sub-level for the paragraphs to be renumbered. |
| Define the maximum sub-level for the paragraphs to be renumbered. |
Sequence change
| Define the first level in which the paragraphs will be renumbered. |
| Define the renumbering increment for the levels of paragraphs. If this increment is null, the original levels are not touched (only the sub-levels are renumbered). |
| Define the first sub-level in which the paragraphs will be renumbered. |
| Define the renumbering increment for the sub-levels of paragraphs. |
Block number 4
| When this box is checked, the renumbering is not actually carried out, but the display of a log lists the numbering of the paragraphs to be carried out. Once the log is displayed, the user is returned to the parameter entry screen. The user can then either abandon the action or un-check the box and validate to trigger the renumbering. |
| If this box is checked, the different levels concerned for the paragraphs involved in the renumbering remain different (either they are renumbered if renumbering step is given or they remain the same if none is given). If it is not checked, all the paragraphs are renumbered on a single level. |
Close
Option / Suppression of paragraphs
Used to delete all of the paragraphs in a document. A confirmation window, giving the number of paragraphs that will be deleted, opens for confirmation. If a positive response is given, the operation is irreversible.
Option / Linked file documentation
Presentation
Used to open the entry window for the linked documents (in principle the images) that will be extracted at the same time as the principal documentation during the generation.
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). |
|
|
| Corresponds to the name of the file to be extracted. If this name is empty, the file extracted takes as its name the code of the documentation, followed by the underline character '_' 3 and the line number over 3 characters (completed from the left with zeros), with an extension jpg (JPEG images). Thus for example, in a documentation named GESADO.htm, the files will be named by default with GESADO_001.jpg, GESADO_002.jpg, etc. It is important to note that this assumes that the attachments are set for a single paragraph in the documentation (those set for other paragraphs must be renamed). When a new file of the type Other is to be included, there is a right click available giving the possibility of Document Selection. This function opens a window that is used to load the document including those chosen from the local workstation. When the file to be included is an image, the right click is used to Select on the image section. |
|
|
Block number 3
| Display the image for the current line. |
Block number 4
| Display the size of the current attached file. |
Close
Option / Copy documentation
Presentation
Used to carry out a mass copy of the documentation. See the technical appendix for the syntax that is possible for the folders.
Close
Fields
The following fields are present on this tab :
Block number 1
| If this box is checked, all languages are taken into account by the operation. If this box is not checked, depending on the case:
|
| Define the language in which a text is expressed. |
| If this box is checked, all types are taken into account by the operation. Otherwise, the type to be taken into account must be entered. |
| It defines the type of documentation to be processed (if it is unique). |
| If this box is checked, all the codes are included in the operation (otherwise, only those codes corresponding to the entered ranges will be taken into account). |
| Definition of the code for the documentation that must be processed (when it is unique). |
Block number 2
| This field is used to define the folder from which the record is going be copied. The possible syntaxes are described in the dedicated appendix. |
| This field used to define the folder in which the record is going be copied. The possible syntaxes are described in the dedicated appendix. |
Close
Option / Extract documentation
Presentation
Used to extract all the current documentation (or a group of current documents) in the form of a standarized XML file, in the sub-directory XML of the generation directory. This XML file contains the structure and the texts in the documentation. It can be used by the translation tools.
Close
Fields
The following fields are present on this tab :
Extraction
|
|
| Defines the translation language. |
|
Extraction
|
| If this box is checked, all languages are taken into account by the operation. |
| It defines the language code to be processed (if it is unique). |
|
|
|
|
|
|
XML extraction
| It indicates the directory from which the documentation export will be carried out, not forgetting that the field helps will be extracted to the FLD sub-directory, and the linked files to the FILE sub-directory. |
|
|
|
Selections
| If this box is checked, all types are taken into account by the operation. Otherwise, the type to be taken into account must be entered. |
| It defines the type of documentation to be processed (if it is unique). |
|
|
| If this box is checked, all the codes are included in the operation (otherwise, only those codes corresponding to the entered ranges will be taken into account). |
| It is used to specify a start range for the criterion in order to be able to determine the data to be taken into account by the operation. |
| It is used to specify an end range for the criterion in order to be able to determine the data to be taken into account by the operation. |
|
|
|
|
|
|
|
|
|
|
|
|
Options
| If this box is checked, the files linked to the documentation are also processed. Usually, these files are images. |
| If this box is checked, the field helps relating to the function or object documentation that are also processed are included. To find out which field helps need to be processed, the screens associated with the corresponding documentation paragraphs can be explored. |
| If this box is checked, the field documentation is also processed. |
| It is used to give a range for the processing of the field help between two key words. |
|
|
|
|
Close
Option / Validation
Presentation
Used to update the Validation flag (and the validation date if the box is checked) for all the documents in the database.
Close
Fields
The following fields are present on this tab :
Selections
| If this box is checked, all languages are taken into account by the operation. If this box is not checked, depending on the case:
|
| Define the language to be used in the process. |
| If this box is checked, all the documentation types are involved. |
| Define the type of documentation to be taken into account in the operation. |
| If this box is checked, all the codes are included in the operation (otherwise, only those codes corresponding to the entered ranges will be taken into account). |
| Define the code of the documentation to be taken into account. |
Validation
| If this box is checked, all the paragraphs are validated and the validation date is updated. If this is not the case, the validation box is unchecked for all the paragraphs concerned. |
| Define the date on which the documentation was considered to be valid (by default, the date when the documentation paragraphs validation is launched). |
|
|
Close