Description de la structure des documentations

Description générale de la structure

L'ensemble des documentations des produits en technologie SAFE X3 est stocké dans la base de données.

• table ADOCUMENT pour la structure des paragraphes,
• table ADOCCLB pour les textes,
• table ADOCBLB pour les fichiers divers,
• table ADOCFNC pour les liens.
• table ADOCFLD pour les aides sur champs.

La façon dont les données sont stockées dans les tables est défini dans l'annexe ci-dessous.

Génération de la documentation

• Une première fonction de génération, permet de créer, pour chaque entité à documenter, le squelette, sous la forme de plusieurs paragraphes normés, de la documentation.
• Une seconde fonction de génération part de ces données et du texte saisi pour générer une documentation finale, au format HTML. Chaque fiche correspond à un paragraphe, puisque les documentations sont organisées sous la forme d'une liste de paragraphes.

Structure d'un paragraphe

• un code langue,
• un type de document : 
• La documentation fonctionnelle (l'explication de la façon dont une fonction est utilisable) est identifiée par le type AFC.
• Les documentations qui décrivent le paramétrage (paramètres, codes activité, pièces automatiques...) sont identifiées par le code de l'objet qui les gère (ADP, ACV, GAU dans les exemples précédents).
• Les documentations diverses (annexes, par exemple, telle que celle-ci) sont identifiées par le code DI. Les menus et sous-menus sont définis par le code APM.
• un code qui correspond à ce qui est documenté et qui permettra d'identifier la documentation : par exemple le code de la fonction, le code du paramètre, le code activité, le code de la pièce automatique...
• Un niveau et un sous-niveau, qui décrivent les imbrications de paragraphes.
  Le titre du premier paragraphe de chaque niveau est repris dans une table des matières qui permet de pointer directement sur des sections de documentation. Lorsque plus d'un paragraphe existe dans un sous-niveau donné, une sous-table des matières est créée pour les niveaux correspondants.
• Un code paragraphe qui détermine la façon dont le texte HTML va être généré.
• Un code écran, qui définit si on doit insérer, dans le bandeau du paragraphe correspondant, une icône permettant de déplier l'aide sur champ relative à l'écran donné.
• Un code activité, hérité du dictionnaire lors de la régénération, qui permet de faire notamment la distinction entre fiches standard et spécifiques, mais aussi de créer des documentations adaptées à des dossiers donnés en ne générant que les paragraphes et les documentations correspondant aux codes activité activés sur le dossier.

 Il est à noter qu'un paragraphe de code activité FAL (toujours faux)  n'est jamais pris en compte par le traitement de génération, même si on demande une génération complète. Ceci permet de désactiver des paragraphes générés que l'on ne désire pas trouver dans une documentation.

Une fois la phase de génération à partir du dictionnaire faite, il est possible de compléter les fiches créées dans la table ADOCUMENT, et d'en rajouter d'autres (notamment de type diverses). La suppression d'une fiche dans la table ADOCUMENT signifiera la suppression du paragraphe dans la documentation finale (mais si ce paragraphe est généré à partir du dictionnaire, une régénération à partir du dictionnaire le recréera).

 Il est important de noter que les paragraphes sont listés dans l'ordre dans lequel ils doivent apparaître (le paragraphe TIT étant le premier, par exemple). Sauf cas particulier et paragraphes génériques (MIS, MIN notamment), il est conseillé de respecter l'ordre.

Les paragraphes qui existent se rattachent à plusieurs catégories.

Les paragraphes générés automatiquement

Certains paragraphes reprennent automatiquement, avec une mise en page donnée, des éléments issus du dictionnaire et ou de la table des liens.
On appelle cela des paragraphes générés. Dans ce cas, à la génération de la table ADOCUMENT, le paragraphe est créé si des éléments du dictionnaire ou de la table des liens le justifient, avec un texte vide. Il n'est pas nécessaire de remplir le texte, puisque les éléments du dictionnaire seront automatiquement présentés dans le paragraphe. 
Si un texte est saisi dans la fiche, il sera automatiquement rajouté à la fin du paragraph. Dans ce cas, la régénération ne supprimera pas le paragraphe, même si, à la suite de l'évolution du dictionnaire, ce paragraphe ne se justifie plus.

Les paragraphes créés vides ou paragraphes classiques

Certains paragraphes sont créés automatiquement à la génération depuis le dictionnaire, mais sans aucun texte, car il s'agit de paragraphes libres habituellement présents dans un type de documentation donné. Le texte saisi dans la table ADOCUMENT est alors repris dans la documentation finale, sans aucune mise en page particulière. Certains paragraphes ne sont pas créés automatiquement lors de la phase de génération du dictionnaire, mais ils peuvent être créés par la suite. On les appelles des paragraphes libres dans la suite de ce document.

Liens hypertextes

Sauf cas particulier déclaré ci-dessous, la création d'un paragraphe créée une ancre de même nom dans le texte. Il est ainsi possible de créer un lien hyper-texte vers le paragraphe en question (le chemin du lien étant document.htm#ancreau lieu d'être document.htm dans ce cas). Ainsi, pour aller directement sur la documentation du 3ème onglet de la fonction de gestion des utilisateurs (GESAUS), on utilisera un lien vers GESAUS.htm#ON3.

Les codes de paragraphes qui peuvent exister en plusieurs exemplaires dans une documentation doivent disposer d'un lien par paragraphe. Dans ce cas, le lien s'exprime sous la forme PARAG_LEV_SLEV, où PARAG est le code du paragraphe, LEV le niveau, et SLEV le sous-niveau. Ainsi, pour un paragraphe de type MIS situé au niveau 140, sous-niveau 40 de la documentation ADO_FCT, le lien sera ADO_FCT#MIS_140_40.

Les différents types de documentation

Le champ Type de documentation définit ce qui va être documenté.

Le tableau ci-dessous décrit les types de documentation possibles :

 Précisions sur certaines documentations

Documentations de type AFC

La documentation de type AFC est la plus complète. Elle permet de décrire en détail la fonction, ses pré-requis de paramétrage (un ensemble de sous-paragraphes automatisés), son interface utilisateur (onglets avec intégration de l'aide sur champ, boutons, items de menus), et des annexes (états, liste des erreurs et tables gérées).
Une partie des paragraphes qui la compose est totalement générée depuis le dictionnaire, mais la plus grande partie des paragraphes doit être saisie. Le code associé à cette documentation est le code de la fonction (tel qu'il est défini dans le dictionnaire des fonctions). Le nom du fichier html correspondant sera généré dans le sous-répertoire FCT du répertoire de documentation.
Elle peut être appelée depuis tout écran de la fonction via la touche F1.

Concernant le fichier de documentation HTML généré et pour les documentations de type AFC uniquement, l'ensemble des paragraphes considérés comme faisant partie de la mise en oeuvre de la fonction sont regroupés dans un autre fichier HTML afin de séparer la partie fonctionnelle de la partie technique. Un lien est créé dans le fichier HTML originel vers le fichier HTML de mise en oeuvre pour chaque type de paragraphe impliqué.
Les paragraphes inpliqués sont :

• Tous les paragraphes de niveau 30 (les Pré-requis)
• Tous les paragraphes de niveau 100 (les Tables mises en oeuvre)

Documentations de type DI

Les documentations de type DI ne sont pas reliées à un élément du dictionnaire. Elles permettent de créer des annexes techniques, des documentations générales. Par exemple, dans les documentations standards, GESAWA.htm est la documentation associée aux événements de Workflow. GES_AWA.htm, documentation de type DI, est l'annexe technique associée.
Les documentations de type DI sont générées dans le répertoire FCT.
Pour éviter une collision avec des documentations fonctionnelles, la norme consiste à insérer au moins un caractère '_' dans le code.

Documentations de type ACV, ADM, ADP, AHI, AOE, ARP, AWA, CDA, CDE, GAU, PS1, ADC

Les documentations de type ACV, ADM, ADP, AHI, AOE, ARP, AWA, CDA, CDE, GAU, PS1, ADC sont des documentations de type objet, qui sont accessibles par Alt + F1 depuis une fonction de paramétrage. Elles permettent de décrire la fiche courante du point de vue de sa logique de paramétrage. On saisit peu de texte en général dans ce type de documentation (essentiellement l'utilisation ou la description du code en question, éventuellement quelques remarques). 
Quelques codes de paragraphes sont spécifiquement dédiés à ce type de documentation. Le code associé à cette documentation est le code de la fiche correspondante. Le fichier de documentation est généré dans le sous-répertoire OBJ. Il est composé du code de l'objet, suivi de la clé de la fiche.

Exemples
- Le code activité BPA est généré sous le nom ACV_BPA.htm.
- Le modèle d'import export BPR est généré sous le nom AOE_BPR.htm. 

 Il est à noter que la clé des paramètres est une clé en deux parties intégrant le chapitre correspondant. Par exemple, l'aide sur le paramètre ADMUSR (chapitre SUP) est donc généré sous le nom ADP_SUP_ADMUSR.htm.

Documentations de type AML, ATB, ATY

Les documentations de type AML, ATB, ATY sont des documentations décrivant la structure des données.
Elles sont accessibles depuis le sommaire de l'aide.
Un seul paragraphe existe dans ce type de documentation (c'est le paragraphe de titre, qui permet de faire précéder la documentation générée par ailleurs d'un commentaire éventuel). Elles sont générées dans le répertoire MCD, et reprennent le code de la table (non préfixé), le code du type de données préfixé par ATY_, et le numéro du menu local sous la forme MEN####.htm (#### étant le numéro du menu sur 4 chiffres, complété à gauche par des zéros).

Les documentations de type APM

Les documentations de type APM sont les menus de l'aide.
Ces documentations sont générées à partir du dictionnaire et un seul paragraphe existe pour ce type de documentation. Il est possible d'en créer d'autres pour décrire des menus supplémentaires organisant la documentation (dans ce cas, le paragraphe contient la liste des documentations appelées). Il est aussi possible d'ajouter des liens de documentations supplémentaires dans des documentations générées de ce type.

Les documentations de type FI

Les documentations de type FI permettent simplement d'extraire des documentations. La norme de nommage de ces documentations détermine l'endroit où les fichiers sont créés. On trouvera le détail dans le paragraphe correspondant.

Les menus de documentation

Toute fonction gère des fiches qui peuvent être documentées par la fonction de gestion de documentation, aux conditions suivantes :

• Définir, dans la table diverse 910, un code de doc correspondant au code de l'objet dont on désire gérer la documentation sur fiche.
• Le type de documentation correspond au type de l'objet, la clé à la clé principale de la fiche que l'on documente (s'il s'agit d'une clé en plusieurs parties, elles sont séparées par le caractère de soulignement "_").
• Générer les documentations au format HTML (par défaut, elles sont créées dans le répertoire OBJ, répertoire des aides sur objet).
• l'appel de l'aide se fait, sur une fiche donnée, par Alt + F1 .

Exemples
AFC (aide fonctionnelle) correspond à l'aide sur les fonctions, or l'objet AFC gère les fonctions. Il en est de même pour les documentations ADP (paramètres), ACT (actions), ACV (codes activité...).

Dès que le code d'un objet est présent dans la table diverse 910, un menu Documentation apparaît automatiquement dans la barre de menus de l'objet correspondant.
Les fonctions accessibles par le menu sont décrites ci-dessous.

Documentation / Paragraphes

Cette fonction permet d'accéder à la gestion de la documentation, sur le premier paragraphe de la documentation (si elle existe) associé à la fiche courante.

Documentation / Liens

Cette fonction permet d'accéder à la gestion des liens. Elle permet de définir des liens entre la fiche courante et d'autres fiches (par exemple des liens entre fonctions et paramètres). Ces liens, purement documentaires, permettent d'alimenter la mécanique de génération des squelettes de documentation.

Documentation / Génération

Ce menu permet de lancer une génération de documentation. La génération peut se lancer également à partir du bouton [Génération] dans le bas de la fenêtre.

Trois types de génération peuvent être lancées, séparément ou simultanément :

• la génération du squelette de documentation à partir du dictionnaire (tables ADOCUMENT, ADOCBLB, ADOCCLB).
• la génération de la documentation à partir des tables précédentes.
• la génération de la documentation sur champ.

Les bornes proposées par défaut tiennent compte de la fiche en cours, mais elles peuvent être modifiées au lancement.

Paragraphes préliminaires

Ces paragraphes introduisent la documentation fonctionnelle.

Code TIT (titre)

Ce chapitre définit le titre de la documentation dans son intitulé.

Lorsque la documentation fonctionnelle est générée à partir du dictionnaire, ce chapitre est automatiquement créé au niveau (10,10).

Pour les documentations du dictionnaire (tables, menus locaux, types de données), dont c'est le seul paragraphe, le texte saisi est un texte préliminaire qui sera inséré avant les tableaux décrivant la structure technique du dictionnaire.

Pour les documentations décrivant un menu (type APM), il est possible de rajouter des liens vers d'autres aides, en les identifiant par leur code. La codification d'une ligne est alors la suivante :

• soit le code de la fonction (aide fonctionnelle). Exemple : GESAUS
• soit le code de l'aide précédé par son type, le tout séparé par le caractère "/". Exemple : DI/ADO_FCT
• soit l'une des deux syntaxes précédentes suivie du caractère "#" et d'un nom de balise, pour se positionner directement au milieu du document. Exemple : GESAUS#ON3

Pour tous les autres types de documentation, il n'est possible de mettre dans le texte qu'une série de mots séparés par des virgules, qui seront insérés dans le fichier HTML, dans la rubrique keyword (mots-clés pour les recherches, n'apparaissant pas dans le texte par ailleurs). Ainsi, dans ce cas, il n'existe pas réellement de paragraphe associé dans le document HTML produit (ni d'aillleurs d'ancre).

On gère ce type de paragraphe pour tous les types de documentation. Si ce paragraphe porte un code activité et si on génère la doc pour un dossier sur lequel ce code activité n'est pas activé, la documentation n'est pas générée.

En particulier, si ce paragraphe porte le code activité FAL:

• la documentation finale n'est jamais générée.
• une régénération d'un squelette de documentation ne génère rien non plus (elle s'arrête si le paragraphe TIT existe avec le code activité FAL).

Par ailleurs, si l'intitulé du titre n'est pas renseigné dans la fiche, il est recherché dans le dictionnaire en fonction du contexte. Ceci permet notamment de gérer des cas particuliers, tels que les aides sur les fonction RPT*, où le nom du groupe doit être celui du dictionnaire.

Code PRE (présentation)

Ce paragraphe définit la présentation de l'entité documentée (fonction, code activité, paramètre de dimensionnement, paramètre... toutes les documentations sont concernées). C'est un paragraphe créé vide automatiquement au niveau (10,20).

C'est le premier paragraphe apparaissant dans la documentation fonctionnelle finale.

 Il n'est pas nécessaire de mettre un texte pour la présentation des codes activité dépendant d'un autre code (un texte automatique est utilisé si le texte est vide).

Paragraphes de pré-requis fonctionnels

Ces paragraphes décrivent les pré-requis nécessaires à l'exécution de la fonction. Ils peuvent donc être présents dans toute documentation fonctionnelle, même si certains peuvent aussi être présents dans d'autres documentations (les documentations sur codes activité, sur états, sur événements de Workflow...).

NOTE pour les Documentations de type AFC (et uniquement AFC) : Dans le fichier de documentation HTML généré, l'ensemble de ces paragraphes de "Pré-requis" sont dorénavant écrits dans un fichier HTML annexe de mise en oeuvre afin de séparer la partie fonctionnelle de la partie technique. Un lien est créé dans le fichier HTML originel vers le fichier HTML de mise en oeuvre.

Liste des paragraphes :

Code PRQ (pré-requis)

Ce paragraphe définissant des pré-requis est présent dans les documentations sur fonction, sur états, sur modèles d'import/export.

Il s'agit d'un paragraphe introductif créé vide au niveau (30,10). Dans la documentation sur fonction, il n'est créé que si un autre paragraphe de pré-requis est créé (alors qu'il est toujours créé dans les documentations sur import/export et sur état).

Le texte n'est pas obligatoire (s'il n'y a pas de texte, le paragraphe existera simplement comme un inter-titre).

Code ACV (codes activité)

Présent dans la documentation des fonctions, ainsi que dans la documentation des paramètres et des codes activité, il s'agit d'un paragraphe généréau niveau (30,20) avec le style 4 :

• dans la documentation des fonctions, il est généré à partir du dictionnaire, dès lors qu'au moins un code activité y est détecté (on les recherche dans la fonction, dans la fenêtre associée à la fonction, dans l'objet, la consultation, les tables associées). On peut également associer un code activité à une fonction par la table des liens ADOCFNC. C'est alors un sous-paragraphe du paragraphe PRQ.
• dans la documentation des paramètres, il est généré à partir d'une recherche dans le dictionnaire et par les liens entre paramètre et code activité.
• Dans les documentations décrivant un code activité. Il est généréen tenant compte des codes activités dépendant du code activité documenté (cette dépendance est retrouvée dans le dictionnaire).

A la génération de la documentation finale, on recherche les codes activité avec le même algorithme dans le dictionnaire, on les présente sous forme de tableau avec des liens vers la documentation décrivant le code activité.

Il est à noter que la recherche systématique dans tout le dictionnaire peut, en cascade, ramener un nombre important de codes activités non désirés dans la liste. Afin de permettre de faire le tri, une fonctionnalité particulière existe : la présence du code activité FAL (toujours faux) dans les liens de documentation inhibe la recherche des codes activités dans le dictionnaire. Ne restent alors que les liens vers les codes activités (FAL exclu) strictement mentionnés dans les liens.

Code ADP (paramètres)

Présent dans la documentation des fonctions, ainsi que dans la documentation des paramètres et des modèle d'import/export, il s'agit d'un paragraphe généréau niveau (30,30) avec le style 4 :

• dans la documentation des fonctions, il définit la liste des paramètres associés à la fonction, et il est généré à partir des liens entre fonction et paramètre ou paramètre et fonction (les liens réciproques sont aussi analysés). C'est alors un sous-paragraphe du paragraphe PRQ.
• dans la documentation des paramètres, il est généré à partir d'une recherche dans le dictionnaire (les paramètres du même groupe et du même chapitre sont inclus), et par les associations entre paramètre et paramètre dans la table des liens.
• dans les documentations décrivant un modèle d'import/export, il décrit les paramètres liés (recherchés par exploration des liens entre modèles et paramètres ou réciproquement dans la table des liens).

A la génération de la documentation finale, les paramètres sont triés par famille, affichés dans des listes avec des liens sur la documentation décrivant le paramètre général.

Code ANM (compteurs)

Présent dans la documentation des fonctions, il s'agit d'un paragraphe généréau niveau (30,40) avec le style 4, qui donne la liste des compteurs utilisés par la fonction. Il est généré dès lors qu'au moins un compteur est détecté dans la table des liens (on peut associer un compteur à une fonction). C'est un sous-paragraphe du paragraphe PRQ.

A la génération de la documentation finale, les compteurs sont présentés en liste.

Code GAU (pièces auto)

Présent dans la documentation des fonctions, il s'agit d'un paragraphe généréau niveau (30,50) avec le style 5, qui donne la liste des pièces automatiques utilisés par la fonction. Il est généré dès lors qu'au moins une pièce automatique est détectée dans la table des liens (on peut associer une pièce automatique à une fonction). C'est un sous-paragraphe du paragraphe PRQ, qui est précédé d'un inter-titre complémentaire, de style juste inférieur au style du paragraphe (4 par défaut), nommé Interface comptable, qui introduit globalement les paragraphes GAU et CDE.

A la génération de la documentation finale, les pièces automatiques sont présentées en tableau avec un lien vers la documentation qui les décrit.

Code CDE (sections/défaut)

Présent dans la documentation des fonctions, il s'agit d'un paragraphe généréau niveau (30,60) avec le style 5, qui donne la liste des codes section utilisés par la fonction. Il est généré dès lors qu'au moins un code section est détecté dans la table des liens (on peut associer un code section à une fonction). C'est un sous-paragraphe du paragraphe PRQ, qui est précédé d'un inter-titre complémentaire, de style juste inférieur au style du paragraphe (4 par défaut), nommé Interface comptable, qui introduit globalement les paragraphes GAU et CDE.

A la génération de la documentation finale, les codes section sont présentées en tableau avec un lien vers la documentation qui les décrit. 

Code HAB (habilitations)

Dans la documentation fonctionnelle, ce paragraphe optionnel est normalement un sous-paragraphe du paragraphe PRQ.

C'est un paragraphe générépar défaut au niveau (30,70), avec le style 4, dès lors qu'une des conditions suivantes est réalisée :

• la fonction dispose de droits d'accès gérés en fonction du site.
• des options d'habilitation existent dans le dictionnaire pour la fonction.
• la fonction est de type objet (de ce fait des options création/suppression modification existent par défaut).
• un code d'accès est déclaré au niveau de l'objet si la fonction est de ce type.

A la génération de la documentation finale, un ensemble de textes automatiques est créé en fonction du contexte (gestion par codes d'accès, options d'habilitation présentes dans le dictionnaire...).

Code TRS (transactions)

Dans la documentation fonctionnelle, ce paragraphe optionnel est normalement un sous-paragraphe du paragraphe PRQ. Il est généré à partir de liens entre fonctions et transactions (le lien de type TRS associant une fonction à la fonction permettant de paramétrer les transactions). La génération se fait au niveau (30,80), avec le style 4.

A la génération de la documentation finale, ces transactions sont remises en page, et des liens vers la documentation fonctionnelle correspondante sont insérés.

Code ECC (écrans consultation)

Dans la documentation fonctionnelle, ce paragraphe optionnel est normalement un sous-paragraphe du paragraphe PRQ. Il est généré à partir du dictionnaire, en recherchant a liste des codes de consultation trouvés dans le dossier où la documentation est générée.

On remarque que ce paragraphe est généré au même rang que le paragraphe TRS, ce qui est logique, puisque les deux ne peuvent pas cohabiter (l'un concerne les consultation, l'autres les objets), et qu'en outre ils correspondent tous les deux à des variantes d'écrans. La génération se fait au niveau (30,80), avec le style 4.

A la génération de la documentation finale, ces code écran sont présentés en tableau.

Code PRD (autres pré-requis)

Présent dans la documentation des fonctions, il s'agit d'un paragraphe généréau niveau (30,90) avec le style 4, qui donne une série de pré-requis autres présentés sous la forme de sous-paragraphes avec des inter-titres de style 5 :

• le premier d'entre eux donne la liste des tables diverses à mettre à jour. Il est alimenté par les liens entre fonction et tables diverses.
• le second donne la liste des tables de la base à mettre à jour. Il est alimenté par les liens entre fonction et tables (par le code AT2, le code ATB alimentant les tables mises à jour).
• le troisième donne la liste des menus locaux qu'il est nécessaire de renseigner. Il est alimenté par les liens entre fonction et menus locaux.
• le dernier sous-paragraphe, nommé Pré-requis divers, est présent si un texte a été ajouté dans la documentation. Si le texte commence par un titre (avec une balise de type Hn, n étant un nombre), l'inter-titre Pré-requis divers n'est pas inséré.

Description de l'interface

Ces paragraphes générésdécrivent l'organisation de la fenêtre de saisie associée à la fonction. Ils ne sont générés automatiquement que s'il existe une fenêtre associée à la fonction. La génération finale inclura l'aide fonctionnelle si le champ Ecran présent dans la fiche est renseigné.

Ces paragraphes sont les suivants :

Code ECR (description écran)

Ce paragraphe constitue une introduction qui permet notamment de définir le nombre d'onglets, de décrire les particularités de la liste gauche s'il y en a.

Lorsque la documentation fonctionnelle est générée à partir du dictionnaire, ce chapitre est automatiquement créé au niveau (40,50), avec le style 3.

Code ENT (en-tête écran)

Ce paragraphe décrit les champs de l'en-tête de la fenêtre (s'il y en a). Le texte qui y est saisi est inséré tel quel dans la documentation finale. Dès lors que le code de l'écran est renseigné dans le paramètre, la barre de titre inclut une petite icône en forme de flèche descendante, qui déplie automatiquement la liste des champs de l'en-tête (et les aides correspondantes). Le texte est en principe utilisé pour donner le détail des champs composant la clé de l'objet, ou les critères de la consultation.

Lorsque la documentation fonctionnelle est générée à partir du dictionnaire, ce chapitre est automatiquement créé au niveau (40,100), avec le style 3, dès lors que la fenêtre correspondant à la fonction utilise effectivement un masque en tête.

Codes ON1 à ONF (onglets)

Ces paragraphes décrivent chacun des onglets de la fenêtre associée à la fonction. La barre de titre inclut une petite icône en forme de flèche descendante, qui déplie automatiquement la liste des champs de l'onglet (et les aides correspondantes) si le champ écran est renseigné dans la fiche, ce qui est le cas en génération automatique.

Ce texte est en principe utilisé pour donner des informations sur les champs présents dans l'onglet (sans forcément donner le détail de l'aide sur chaque champ, puisque l'aide en ligne par champ est aussi disponible par dépliage). En absence de texte saisi, un texte générique invite l'utilisateur à déplier l'aide sur champ.

Lorsque la documentation fonctionnelle est générée à partir du dictionnaire, ce type de chapitre est automatiquement créé au niveau 40, à partir de la description de la fenêtre associée à la fonction. Les sous-niveaux de génération sont calculés à partir du rang de l'onglet (champ ROWMSK), afin de respecter l'ordre de présentation des onglets de la fonction lorsqu'on ajoute des onglets spécifiques qui doivent s'insérer entre deux onglets existants. Le sous-niveau est égal au rang multiplié par 200. Ainsi, si les rangs sont numérotés de 10 en 10, on obtient les rangs 2000, 4000, 6000. Le rang maximum possible est 19800, et le minimum est 200.

Lors de la génération de la documentation, les paragraphes décrivant les actions Bouton sur tableaux (clic droit)sont créés automatiquement à la suite du paragraphe lié à chaque onglet, en étant numérotés de 5 en 5 (afin de laisser la possibilité d'intercaler des paragraphes divers).

Codes BOT (clics sur tableaux)

Ces paragraphes décrivent chacune des fonctions accessibles par clic droit sur un tableau. Il peut y en avoir plusieurs (avec le même code : l'ancre correspondante est donc BOT_LEV_SLEV, où LEV est le niveau, et SLEV le sous-niveau). Chacun de ces boutons doit être inséré, dans l'ordre des paragraphes, juste après le paragraphe décrivant l'onglet sur lequel il est placé.

Lorsque la documentation fonctionnelle est générée à partir du dictionnaire, ces paragraphes sont automatiquement créés au niveau 40, avec un pas de numérotation allant de 5 en 5 à partir du numéro de l'onglet (2005, 2010, 2015... après l'onglet de rang 10, par exemple). Le style par défaut utilisé est le numéro 6, et un inter-titre nommé Fonctions accessibles par clic droit sur tableau, de style 5, est mis en tête des paragraphes consécutifs de ce type.

Codes BOU (boutons)

Ces paragraphes décrivent chacun des boutons accessibles en bas d'écran. Il peut y en avoir plusieurs (avec le même code : l'ancre correspondante est donc BOU_LEV_SLEV, où LEV est le niveau, et SLEV le sous-niveau). Ces boutons sont normalement placés, après les paragraphes associés aux onglets. Le premier d'entre eux est un paragraphe introductif, dont le titre utilise un style standard (3 par défaut). Le titre des chapitres consécutifs BOU suivants est présenté dans un cadre de bouton (ce qui signifie que le texte doit correspondre au texte du bouton). Le texte correspondant est alors mis à droite de chaque bouton.

Lorsque la documentation fonctionnelle est générée à partir du dictionnaire, ces paragraphes sont automatiquement créés au niveau 70, avec un sous-niveau commençant à 10 (titre du chapitre consacré aux boutons) et allant de 10 en 10 (20 pour le premier bouton, 30 pour le suivant, etc.).

Codes BME (Barre de menus)

Ces paragraphes décrivent chacun des fonctions accessibles par la barre de menus. Il peut y en avoir plusieurs (avec le même code : l'ancre correspondante est donc BME_LEV_SLEV, où LEV est le niveau, et SLEV le sous-niveau). Ces paragraphes sont placés après les paragraphes. Le premier d'entre eux est un paragraphe introductif, dont le titre utilise un style standard (3 par défaut). Le titre des chapitres consécutifs est en style standard 4.

Lorsque la documentation fonctionnelle est générée à partir du dictionnaire, ces paragraphes sont automatiquement créés au niveau 80, avec un sous-niveau commençant à 10 (titre du chapitre consacré aux menus) et allant de 10 en 10 (20 pour le premier bouton, 30 pour le suivant, etc.).

Paragraphes annexes

Ces paragraphes de conclusion donnent des informations annexes (liste des erreurs, états, tâches batch...). Ce sont les suivants :

Code RPT (Etats)

Présent dans la documentation des fonctions, il s'agit d'un paragraphe généréau niveau (50,10) avec le style 4, qui donne la états utilisés par la fonction. Il est généré à partir du dictionnaire (recherche à partir des codes d'impression définis dans le dictionnaire des fonctions pour Impression et Liste, en recherchant si des états leurs sont associés dans la table des codes impressions). On complète cette liste d'états par ceux éventuellement trouvés en recherchant des liens entre la fonction et des états dans la table des liens.

A la génération de la documentation finale, un tableau est généré, contenant les états lançables depuis la fonction, avec des liens hyper-textes vers les documentations correspondantes.

Code ABT (tâches batch)

Présent dans la documentation des fonctions, il s'agit d'un paragraphe généréau niveau (60,10) avec le style 4, qui donne la liste des tâches batch utilisables pour lancer la fonction en arrière-plan. Il est généré à partir du dictionnaire (recherche dans la table des tâches batch). On complète cette liste de tâches par celles éventuellement trouvées en recherchant des liens entre la fonction et des tâches batch dans la table des liens.

A la génération de la documentation finale, un tableau est généré, contenant la liste des tâches existantes.

Code ERR (Erreurs)

Ce paragraphe, dont le texte saisi est directement inséré dans le document, est dédié à la liste des erreurs qui peuvent être affichées lors de l'utilisation de la fonction. On n'insère ici que les erreurs très particulières à la fonction. En effet, un ensemble d'erreurs génériques sont listées dans un document dédié, et un lien vers ce document est automatiquement inséré dans ce paragraphe. Ce paragraphe est par ailleurs créé vide.

Ce type de paragraphe peut être également utilisé dans la documentation sur modèles d'import/export, avec les mêmes caractéristiques.

Lorsque la documentation fonctionnelle est générée à partir du dictionnaire, ce chapitre est automatiquement créé au niveau (80,10), avec le style 3. S'il n'y a pas de texte associé au paragraphe, un texte signalant que les seules erreurs connues sont des erreurs génériques (accessibles via le lien). Sinon, le texte donne les erreurs et le texte explicatif correspondant. Il est recommandé d'utiliser le style H5 pour le texte de l'erreur, et le style de paragraphe par défaut pour l'explication, ce qui donne le résultat suivant :

 Il est possible d'utiliser la syntaxe L4G mess() pour donner le texte de l'erreur. Ceci permet d'avoir exactement le texte de l'erreur et d'avoir la même traduction.

On aura donc par exemple:

qui donnera lors de la génération

Code ATB (tables gérées)

Présent dans la documentation des fonctions, ainsi que dans la documentation des paramètres de dimensionnement, des modèles d'import/export, des états,dles règles de Workflow, et des événements déclenchant des statistiques, il s'agit d'un paragraphe généréau niveau (100,10) avec le style 3 :

• dans la documentation des fonctions, il est généré à partir du dictionnaire, dès lors qu'au moins une table y est détectée (on les recherche dans l'objet, dans la consultation). On peut également associer une table à une fonction par la table des liens.
  NOTE pour ces Documentations de type AFC (et uniquement AFC) : Dans le fichier de documentation HTML généré, ce paragraphe de "Tables mises en oeuvre" est dorénavant écrit dans un fichier HTML annexe de mise en oeuvre afin de séparer la partie fonctionnelle de la partie technique. Un lien est créé dans le fichier HTML originel vers le fichier HTML de mise en oeuvre.
• dans les autres documentations, le principe est le même : si le dictionnaire permet de retrouver des tables, ou si des liens sont trouvés, le paragraphe est généré.
• dans le cas de la documentation des paramètres de dimensionnement, les tables listées sont celles dont ledimensionnement dépend du paramètre.

A la génération de la documentation finale, on présente les tables dans un tableau, en incluant un lien vers le dictionnaire des tables et aussi vers l'objet, quand il existe, qui permet de gérer la table en question. Les tables globales à tous les dossiers, s'il en existe, sont isolées dans un paragraphe dédié.

Paragraphes particuliers

Ces paragraphes peuvent être insérés partout dans la documentation, pour gérer les exceptions ou les paragraphes supplémentaires non prévus. Ils permettent aussi de segmenter un paragraphe trop long (la longueur du texte saisi sans un paragraphe étant limité par construction). Comme le code utilisé pour ces paragraphes peut être répété, il n'y a pas d'ancre du même nom placée dessus (des ancres techniques, numérotées avec le code du paragraphe, suivi du niveau et du sous-niveau, séparés par le caractère "_", sont quand même créées). Ces paragraphes sont les suivants :

Codes MIS (Divers)

Il s'agit ici d'un paragraphe divers présent dans la table des matières liée au niveau dans lequel il se trouve. On donne un titre, un style, et un texte à insérer.

Dans la mesure où plusieurs paragraphes de ce type peuvent exister dans une doc, l'ancre correspondant à ces paragraphes est MIS_LEV_SLEV, où LEV est le niveau, et SLEV le sous-niveau.

Codes MIN (Divers)

Il s'agit ici d'un paragraphe divers non présent dans la table des matières liée au niveau dans lequel il se trouve. On donne un titre, un style, et un texte à insérer.

Dans la mesure où plusieurs paragraphes de ce type peuvent exister dans une doc, l'ancre correspondant à ces paragraphes est MIN_LEV_SLEV, où LEV est le niveau, et SLEV le sous-niveau.

Codes LNK (Liens)

Ce type de paragraphe permet d'insérer des tables des matières sous la forme :

• soit de la liste des liens d'en-tête (située dans la barre de titre de la documentation). Ceci suppose que le paragraphe de type LNK se trouve au même niveau que le paragraphe TIT de la documentation correspondante. Le titre du paragraphe donne alors le titre du document courant tel qu'il est défini dans la liste de liens.
• soit d'une liste de liens (comme une table des matières) dans le cas général. Ce type de paragraphe permet d'insérer des liens vers des documentations non directement accessibles dans la hiérarchie dans laquelle le document se trouve.

Dans le cas où le lien définit un paragraphe séparé, le titre et le style sont ignorés, et aucune entrée n'apparaît dans la table des matières. Mais si on désire ajouter un titre à ce paragraphe de liens, il suffit de le faire précéder d'un paragraphe de type MIS ou MIN.

Les liens sont définis dans le texte du paragraphe sous l'une des formes suivantes :

• CODE_FONCTION
• CODE_FONCTION#ancre
• TYPE/CODE
• TYPE/CODE#ancre

La signification des éléments est la suivante :

• CODE_FONCTION est le code d'une documentation fonctionnelle (de type AFC ou DI) : le lien pointera sur le sous-répertoire FCT, où se trouve ce type de documentation.
• TYPE correspond aux différents types de documentation : ADC, AD, ACV par exemple... Le code qui suit est le code de la documentation.
• ancre correspond à une ancre de paragraphe, si on désire se positionner directement sur un paragraphe donné. L'ancre est ignorée s'il s'agit d'un lien d'en-tête.

A la génération, chaque lien est exploré : la documentation correspondante est recherchée dans la table ADOCUMENT (si elle n'existe pas, le lien n'est pas inséré) et le titre de la documentation est inséré texte supportant le lien.

Codes INC (Inclusion)

Ce paragraphe permet d'inclure tel quel un paragraphe déjà écrit dans une autre documentation.

Tout paragraphe peut être inclus, à l'exception du paragraphe de type TIT. Si on veut reprendre un paragraphe de présentation associé à une autre documentation, le paragraphe INC qui le remplace doit être le premier de ce type de la documentation, et doit chaîner sur un paragraphe de type PRE.

Comme plusieurs paragraphes INC sont possibles dans une telle documentation, l'ancre correspondant à ces paragraphes est INC_LEV_SLEV, où LEV est le niveau, et SLEV le sous-niveau.

Le paragraphe à reprendre doit alors être identifié dans le texte du paragraphe d'inclusion, sous l'une des deux formes suivantes :

• TYPE/CODE
• TYPE/CODE/NIVEAU/SOUS-NIVEAU

Le niveau et sous-niveau ne sont pas obligatoires (le paragraphe de même niveau et de même sous-niveau étant repris par défaut dans la documentation liée).

Par exemple, si on veut insérer le paragraphe relatif au premier onglet de la fiche utilisateur, qui est défini au niveau 40 et au sous-niveau 200, on mettra dans le paragraphe d'inclusion le texte suivant :

AFC/GESAUS/40/200

Il est à noter que tout est repris du paragraphe d'origine (titre, style, texte, mise en forme, aide sur champs), sauf le niveau et le sous-niveau qui restent ceux d'origine (les ruptures de tables des matières restent ainsi respectées). Le titre de la table des matières correspond au titre du paragraphe INC d'origine, l'ancre créée et utilisable pour les liens correspond à une ancre générique INC_rang_sous-rang.

Paragraphes réservés aux autres documentations

Ces paragraphes sont spécifiques à des types de documentations autres que les documentations sur fonction. Ce sont les suivants :

Code LEV (niveau)

Ce paragraphe est spécifique aux documentations sur paramètres. Il est généré à partir du dictionnaire au niveau (30,10).

A la génération finale, un texte est généré, précisant le niveau de définition du paramètre, ainsi que le nom de la variable globale associée si elle existe. Si aucune variable globale n'est trouvée, un texte précisant qu'il n'en existe pas est inséré, sauf si le texte de la fiche a été renseigné (on suppose dans ce cas qu'il peut être amené à citer une variable non déclarée dans le dictionnaire).

Code REM (remarques)

Ce paragraphe est spécifique aux documentations sur paramètres, sur pièces automatiques, et sur codes sections par défaut. Il est créé vide à partir du dictionnaire au niveau (70,10).

Le texte saisi dans la fiche est censé permettre de faire des remarques diverses.

Code PAR (paramètre des actions)

Ce paragraphe est spécifique aux documentations sur actions. Il est généréà partir du dictionnaire au niveau (30,10), pour permettre de donner la liste des paramètres de l'action.

A la génération de la documentation finale, une phrase introductive est créée, suivie d'un tableau présentant les paramètres, leur intitulé, et le type de données. En l'absence de paramètres, une phrase négative est insérée.

Code UTI (utilisations de l'action)

Ce paragraphe est spécifique aux documentations sur action. Il est créé vide à partir du dictionnaire au niveau (40,10).

Le texte saisi dans la fiche est censé décrire les utilisations de l'action.

Si ce paragraphe est resté vide au moment de la génération de la documentation finale, on ne le génère pas.

Code ACT (actions associées aux actions)

Ce paragraphe est spécifique aux documentations sur actions. Il est généréau niveau (50,10), pour permettre de donner la liste des actions liées à l'action documentée. La génération se fait à partir des liens (et des liens réciproques) trouvés entre action et action.

A la génération de la documentation finale, une phrase introductive est créée, suivie d'un tableau présentant les actions, avec un lien vers la documentation correspondante.

Code REC (valeurs recommandées)

Ce paragraphe est spécifique aux documentations sur paramètres, et sur paramètres de dimensionnement. Il est créé vide dans le cas des paramètres, et généré dans le cas des variables de dimensionnement (une ligne par défaut est créée si le paragraphe est vide, donnant la valeur trouvée dans le dossier de référence). La création de fait au niveau (30,10).

Le texte saisi dans la fiche est censé décrire les valeurs recommandées pour le paramètre en question.

Code AFC (fonctions concernées)

Ce paragraphe est spécifique aux documentations sur codes activité, sur paramètres généraux et sur états. Il est généréau niveau (40,10) pour les codes activités et les états, et au niveau (50,10) pour les paramètres généraux,  pour permettre de donner :

• la liste des fonctions concernées par le code activité. La génération se fait à partir des liens réciproques aux liens entre fonctions et codes activité, ainsi que par les codes activités trouvés lors d'une exploration sommaire du dictionnaire (seules les fonctions dépendant directement du code activité sont repris). A la génération de la documentation finale, une phrase introductive est créée, suivie d'une liste de fonctions avec un lien sur la documentation correspondante.
• le moyen d'accéder à l'état (groupes d'impression, et liste des fonctions susceptibles de lancer l'état). La génération se fait alors par analyse du dictionnaire et par lecture à partir des liens réciproques aux liens entre fonctions et états. A la génération de la documentation finale, une phrase introductive est créée, suivie d'un texte automatique précisant si l'état est ou n'est pas directement exécutable, à quel groupe d'impression il appartient, et enfin une liste de fonctions susceptibles de lancer l'état avec un lien sur la documentation correspondante.
• les fonctions particulièrement impactées par le paramètre.

Code AT2 (tables à renseigner)

Ce paragraphe est spécifique aux documentations sur modèles d'import/export. Il est généréau niveau (30,30), avec le style 4, pour permettre de donner la liste des tables qui sont censées être renseignées pour pouvoir utiliser le modèle correspondant, et est un sous-paragraphe du chapitre PRQ. La génération se fait à partir des liens entre modèles d'import/export et table (de type AT2).

A la génération de la documentation finale, on présente les tables dans un tableau, précédées d'une phrase introductive, en incluant un lien vers le dictionnaire des tables et aussi vers l'objet, quand il existe, qui permet de gérer la table en question. Les tables globales à tous les dossiers, s'il en existe, sont isolées dans un paragraphe dédié.

Code CHO (champs obligatoires)

Ce paragraphe est spécifique aux documentations sur modèles d'import/export. Il est créé videau niveau (40,10), pour permettre de donner la liste des champs supposés être obligatoires pour que le modèle puisse fonctionner.

Code CRI (critères de lancement)

Ce paragraphe est spécifique aux documentations sur états, et aux documentations sur sous-programmes.

Dans le cas des états, c'est un paragraphe générépar défaut au niveau (30,30), avec le style 4, à partir des données du dictionnaire des états, afin de permettre de générer les textes automatiques suivants :

• une phrase introductive, suivi de la liste des paramètres de l'état (une phrase négative s'il n'y a pas de paramètres).
• une phrase précisant le comportement particulier des paramètres début / fin s'il y en a.
• une phrase précisant, si c'est le cas, qu'un des paramètres peut être saisi avec plusieurs valeurs (segmentation de l'état).
• une phrase précisant, si c'est le cas, qu'un filtrage des données est fait en fonction du site selon les habilitations de l'utilisateur.
• une phrase précisant, si c'est le cas, que l'état ne peut être imprimé que sur une imprimante de type particulier.

Dans le cas des sous-programmes, c'est un paragraphe générépar défaut au niveau (20,30), avec le style 4, à partir des données du dictionnaire des sous-programmes, afin de permettre de lister les paramètres à passer au sous-programme.

Code DES (description de l'état)

Ce paragraphe est spécifique aux documentations sur états. Il est créé videau niveau (40,10), pour permettre de décrire le contenu de l'état.

Code CTX (contexte)

Ce paragraphe est spécifique aux documentations sur Workflow, sur événements déclenchant les statistiques, et sur points d'entrée.

Pour les événements déclenchant les statistiques et le Workflow, ce paragraphe est créé videau niveau (30,10), pour permettre de décrire le contexte déclenchant.

Pour les points d'entrée, il peut y avoir plusieurs paragraphes de ce type. En effet, une documentation sur point d'entrée peut intégrer plusieurs points d'entrée, et à chaque fois, un paragraphe APE défini à partir du niveau 20, sous-niveau 10,  avec un incrément de 10 sur les niveaux, est créé. Un paragraphe CTX associé est créé au même niveau que le paragraphe APE correspondant, au sous-niveau 20. L'ancre correspondant à ces paragraphes est donc CTX_LEV_SLEV, où LEV est le niveau, et SLEV le sous-niveau.

A la génération de la documentation finale, ce paragraphe intègre des phrases automatiques signalant :

• qu'une transaction est en cours ou pas (lien de type TRS du dictionnaire des traitements, la valeur 1 associée signifiant qu'il n'y a pas de transaction, la valeur 2 signifiant qu'il y en a une).
• qu'un fichier trace est ouvert ou pas (lien de type TRA du dictionnaire des traitements, la valeur 1 associée signifiant qu'il n'y a pas de fichier trace ouvert, la valeur 2 signifiant qu'il y en a un).

Ce paragraphe intègre aussi, sous forme de tableau, une liste des tables en ligne. Cette liste est obtenue par des liens du dictionnaire de traitement vers des tables, un lien de type ATB signifiant que la table est ouverte en étant renseignée dans le contexte, un lien de type AT2signalant simplement que la table est ouverte. Il est à noter que ces liens peuvent se saisir sous la forme CODE_TABLE [ABREVIATION], lorsque la table n'est pas ouverte sous son abréviation principale.

Code APE (point d'entrée)

Ce paragraphe est spécifique aux documentations sur points d'entrée.

Pour les points d'entrée, il peut y avoir plusieurs paragraphes de ce type. En effet, une documentation sur point d'entrée peut intégrer plusieurs points d'entrée, et à chaque fois, un paragraphe APE défini à partir du niveau 20, sous-niveau 10,  avec un incrément de 10 sur les niveaux, est créé. L'ancre correspondant à ces paragraphes est donc APE_LEV_SLEV, où LEV est le niveau, et SLEV le sous-niveau. Un paragraphe CTX associé est créé au même niveau que le paragraphe APE correspondant, au sous-niveau 20.

Lorsque la documentation fonctionnelle est générée à partir du dictionnaire, le premier de ces paragraphes est automatiquement créé au niveau 20, sous-niveau 10. Les suivants sont créés en espaçant les niveaux de 10 en 10. Le code des points d'entrée est retrouvé par un lien de type APE, la désignation associée donnant le code du point d'entrée. On fait éventuellement suivre ce lien de liens de type ATB, AT2, TRA, TRS, l'ordre de déclaration étant important (comme on peut avoir plusieurs liens APE, les autres liens sont censés faire référence au dernier lien déclaré).

Ce code de point d'entrée se retrouve ensuite dans l'intitulé du paragraphe. Il faut impérativement que ce code reste en tête du titre (on peut le compléter par un texte explicatif, séparé du code par un espace ou une parenthèse ouvrante). Si cette précaution n'est pas prise, on ne sait plus générer correctement la documentation finale.

A la génération de la documentation finale, ces paragraphes intègrent des phrases automatiques signalant :

• qu'une transaction est en cours ou pas (lien de type TRS du dictionnaire des traitements, la valeur 1 associée signifiant qu'il n'y a pas de transaction, la valeur 2 signifiant qu'il y en a une).
• qu'un fichier trace est ouvert ou pas (lien de type TRA du dictionnaire des traitements, la valeur 1 associée signifiant qu'il n'y a pas de fichier trace ouvert, la valeur 2 signifiant qu'il y en a un).

Ils intègrent aussi, sous forme de tableau, une liste des tables en ligne. Cette liste est obtenue par des liens du dictionnaire de traitement vers des tables, un lien de type ATB signifiant que la table est ouverte en étant renseignée dans le contexte, un lien de type AT2signalant simplement que la table est ouverte. Il est à noter que ces liens peuvent se saisir sous la forme CODE_TABLE [ABREVIATION], lorsque la table n'est pas ouverte sous son abréviation principale.

Code OPM (mode opératoire)

Ce paragraphe est spécifique aux documentations sur pièces automatiques et sur sections par défaut. Il est créé videau niveau (30,10), pour permettre de décrire le mode opératoire.

Code FLW (Description du flux)

Ce paragraphe est spécifique aux documentations sur workflow. Il n'est jamais créé automatiquement, mais on suggère de le placer en (40,10). Son utilité est de décrire les enchaînements de Workflow dans lequel cet événement prend place.

Résumé des structures de paragraphe

Pour chaque type de documentation, on retrouvera, ci-dessous, les paragraphes générés et leur structure par défaut (étant entendu que des paragraphes INC, LNK, MIS, et MIN peuvent être insérés librement).

AFC (doc sur fonction)

Cette documentation, créée dans le répertoire fct, peut contenir les paragraphes suivants :

ADP (doc sur paramètres)

Cette documentation, créée dans le répertoire obj, peut contenir les paragraphes suivants :

ACT (doc sur actions)

Cette documentation, créée dans le répertoire obj, peut contenir les paragraphes suivants :

Concernant le paragraphe PRE, il faut noter :

• que son contenu est directement visualisé dans le dictionnaire des actions, et qu'il est modifiable directement depuis ce dictionnaire.
• qu'un texte par défaut (précisant qu'il s'agit d'une action interne non utilisable en développement spécifique) est généré dans le paragraphe s'il est vide.

ACV (doc sur codes activité)

Cette documentation, créée dans le répertoire obj, peut contenir les paragraphes suivants :

ADM (doc sur variables de dimensionnement)

Cette documentation, créée dans le répertoire obj, peut contenir les paragraphes suivants :

AOE (doc sur modèles d'import/export)

Cette documentation, créée dans le répertoire obj, peut contenir les paragraphes suivants :

ARP (doc sur états)

Cette documentation, créée dans le répertoire obj, peut contenir les paragraphes suivants :

AWA (doc sur Workflow)

Cette documentation, créée dans le répertoire obj, peut contenir les paragraphes suivants :

CDE (doc sur codes section)

Cette documentation, créée dans le répertoire obj, peut contenir les paragraphes suivants :

CDA (doc sur destinations)

Cette documentation, créée dans le répertoire obj, peut contenir les paragraphes suivants :

GAU (doc sur pièces automatiques)

Cette documentation, créée dans le répertoire obj, peut contenir les paragraphes suivants :

PS1 (doc sur déclencheurs statistiques)

Cette documentation, créée dans le répertoire obj, peut contenir les paragraphes suivants :

ATB (dictionnaire des tables)

Il n'y a qu'un paragraphe dans ce type de documentation, qui est créée dans le répertoire mcd :

AML (dictionnaire des menus locaux)

Il n'y a qu'un paragraphe dans ce type de documentation, qui est créée dans le répertoire mcd :

ATY (dictionnaire des types de données)

Il n'y a qu'un paragraphe dans ce type de documentation, qui est créée dans le répertoire mcd :

ADC (dictionnaire des points d'entrée)

Cette documentation, créée dans le répertoire obj, peut contenir les paragraphes suivants :

ASU (doc sur sous-programmes)

Cette documentation, créée dans le répertoire obj, peut contenir les paragraphes suivants :

Concernant le paragraphe PRE, il faut noter :

• que son contenu est directement visualisé dans le dictionnaire des sous-programmes, et qu'il est modifiable directement depuis ce dictionnaire.
• qu'un texte par défaut (précisant qu'il s'agit d'un sous-programme interne non utilisable en développement spécifique) est généré dans le paragraphe s'il est vide.

AGB (doc sur variables)

Cette documentation, créée dans le répertoire obj, peut contenir les paragraphes suivants :

Concernant le paragraphe PRE, il faut noter :

• que son contenu est directement visualisé dans le dictionnaire des variables, et qu'il est modifiable directement depuis ce dictionnaire.
• qu'un texte par défaut (précisant qu'il s'agit d'une variable interne non utilisable en développement spécifique) est généré dans le paragraphe s'il est vide.

AHI (doc sur règles d'épuration)

Cette documentation, créée dans le répertoire obj, peut contenir les paragraphes suivants :

APM (menus intermédiaires)

Ce type de documentation est utilisé dans deux cas :

• lorsqu'une fonction de type Menu existe, la génération crée une documentation de type APM, avec un seul paragraphe de type TIT. La génération finale recherche la liste des fonctions associées au menu pour lister les fonctions correspondantes. Des liens peuvent directement être ajoutés dans le paragraphe dans ce cas particulier (même syntaxe que les paragraphes LNK), afin d'ajouter des lignes de menu en dessous de celles qui sont trouvées par ailleurs dans le dictionnaire.
• tous les menus intermédiaires associés aux documentations diverses (codes activités, événement Workflow...) sont de type APM, avec un nom commençant par le code associé au type de documentation, suivi d'un caractère "_", et d'un qualifiant (module, famille) si nécessaire pour disposer de menus intermédiaires, le menu principal ayant le code TYPE_0. Par exemple :
• les menus intermédiaires associés aux codes activité sont : ACV_0 (racine), ACV_1 (codes activité associés au module numéro 1, ACV_2...
• les menus intermédiaires associés aux paramètres sont : ADP_0 (racine), ADP_TC (paramètres de la catégorie TC), ADP_SUP (paramètres de la catégorie SUP)...

Il est à noter que la création d'une documentation autre permettant de réaliser des menus intermédiaire doit être faite sous la forme d'une documentation de type DI, avec les paragraphes suivants : un paragraphe TIT en (10,10), un paragraphe PRE en (10,20), paragraphe qui peut être vide, éventuellement un premier paragraphe LNK au rang (10,30) pour permettre de remplir la barre de titre avec des liens de navigation, et un paragraphe LNK avec un rang supérieur ou égal à 20, pour établir la liste des items de liens du menu lui-même.

AD (Aide en ligne du langage)

Ce type de documentation est créée dans le répertoire l4G. Cette documentation a pour le moment une structure libre. Le seul paragraphe obligatoire est :

Lorsque ce seul paragraphe existe, aucune génération de fichier liée à la fiche n'est faite, mais le fichier lié, s'il existe, est extrait sous le nom de la documentation. Cette fonctionnalité a été faite pour permettre une reprise à l'identique de la doc L4G existante, chaque document étant vu comme un fichier dans la base.

Dès que plus d'un paragraphe existe (notamment si on ajoute des paragraphes de type MIS ou MIN), la documentation est créée selon les règles habituelles.

Il est à noter qu'une documentation dont le code se termine par les caractères _D se voit créée avec un fichier se terminant par le caractère $. En effet, pour éviter de créer des clés contenant des caractères spéciaux, on utilise cette règle de renommage. Ainsi, les fonctions seg$, chr$, getenv$ sont-elles représentées par les fiches SEG_D, CHR_D, GETENV_D.

FI (Fichiers à extraire)

Ce type est particulier : il s'agit uniquement d'un marqueur de fichiers à extraire. Les règles de nommage sont les suivantes :

• une documentation de type FI et de code XXXXX_nnn est un marqueur de fichiers à extraire dans le répertoire XXXXX (n'importe lequel des répertoires standard peut ainsi être défini). On peut créer autant de paragraphes que l'on veut pour définir par exemple des groupes de fichiers différents.
• une documentation _nnn est un marqueur de fichiers à extraire dans tous les répertoires XXXXX pour lesquels une documentation de type FI et de code XXXXX_nnn existe. Concrètement, à la génération de la doc de type FI et de code XXXXX_nnn, on vérifie s'il existe des paragraphes de même niveau et de même sous-niveau dans la documentation de type FI et de code _nnn correspondante (le numéro doit être identique). S'il en existe, ces fichiers sont extraits d'abord. Ensuite seulement, on extrait les fichiers liés à la doc de code XXXXX_nnn. Ainsi, on peut définir dans une telle documentation un tronc commun de fichiers dont certains peuvent être réécrasés par l'extraction de la doc de code XXXXX_nnn correspondante.
• la documentation de type FI et de code _ (un seul caractère "underscore") est un marqueur de fichiers dont la génération entraîne la création de fichiers spécifiquement dans le répertoire racine de l'aide. Lorsque cette documentation est générée, on extrait d'abord dans le répertoire racine tous les fichiers attachés aux documentations de type FI et de code _nnn si le premier chiffre est 0 (et si le niveau et le sous-niveau correspondent).

Autres types de documentation

Les autres types de documentation (DI, IN, CS, DL, AM) sont des documentations dont la structure n'est pas définie (mais dont les répertoires de génération sont définis par rapport au type). Le seul paragraphe obligatoire est le paragraphe TIT.

Lorsque ce seul paragraphe existe, aucune génération de fichier liée à la fiche n'est faite, mais le fichier lié, s'il existe, est extrait sous le nom de la documentation.

Dès que plus d'un paragraphe existe (notamment si on ajoute des paragraphes de type MIS ou MIN), la documentation est créée selon les règles habituelles.

Les répertoires de génération sont indiqués dans le tableau ci-dessous :

Les sommaires de la documentation

Les sommaires composant la documentation sont liés aux types de documentation APM. Normalement, seul un paragraphe existe dans ce cas :

Ce paragraphe peut contenir, sous forme de texte, une liste de codes de documentation. Dans ce cas, cette liste est ajoutée comme autant de liens vers les documentations en question (le titre de la documentation liée étant repris dans la documentation en question). Ceci permet à la fois de créer des sommaires manuellement, ou de rajouter à un sommaire existant des liens supplémentaires.

En effet, lors de la génération de la documentation à partir du dictionnaire, on génère automatiquement des documentations de type APM, avec ce seul paragraphe TIT. Les codifications des documentations créées, et les sommaires générés dans les documents créés en génération finale, est décrit dans le tableau ci-dessous :

Pour tous les types de documentation autres que ceux listés ci-dessus, il est possible de créer une documentation dont le code sera INDEX. Si cette documentation existe, un lien sera réalisé directement depuis chaque documentation de ce type dans la barre de titre. Les documentations de type IN, DL, par exemple, utilisent un index de ce type.

Gestion des tables de la documentation

La structure de la documentation est stockée dans la table ADOCUMENT. Cette table stocke, pour chaque paragraphe et sous-paragraphe, ses caractéristiques (niveau, sous-niveau, titre, code activité...).

Mais le texte du paragraphe est stocké à part, dans la table ADOCCLB. Cette table ne stocke que les éléments de clés du paragraphe, et le texte du paragraphe lui-même.

L'intérêt de cette structure est le suivant:

• l'ensemble des paragraphes standards de la documentation sont stockés dans le dossier racine du superviseur.
• A la création d'un dossier, on duplique dans le dossier la table ADOCUMENT, mais en aucun cas les textes des documents eux-mêmes.
• Tout ajout d'un paragraphe spécifique se fait dans le dossier enfant, les textes attachés étant stockés dans le même dossier.
• Toute modification d'un paragraphe standard provoque la copie de l'enregistrement correspondant de la table ADOCCLB du dossier racine vers le dossier enfant.

Ainsi, on ne stocke que les textes spécifiques dans le dossier enfant.

Il en est de même pour les textes liés à l'aide sur champ : les textes standards sont stockés dans la table ADOCFLD du dossier racine, les textes spécifiques sont stockés dans le dossier lui-même.

A la génération de la documentation, on parcourt la structure stockée dans le dossier local, et pour chaque paragraphe on prend en priorité le texte présent dans le dossier local. S'il n'existe pas, on reprend le texte présent dans le dossier racine.