 |
||||||
|
||||||
SCR/AL1 - TOME I. Les programmes
Le programme scr4_h lit un fichier de texte Ascii formatté selon certaines règles et construit un fichier .hlp qui pourra être utilisé dans une application SCR/AL1 pour afficher un texte d'aide "on-line".
Le fichier .hlp peut être exploité par les programmes suivants :
La syntaxe du fichier input est la suivante :
Une première partie est consacrée à la description de la fenêtre où apparaîtra le texte d'aide. Elle est optionnelle : des valeurs par défaut sont attribuées au départ à la position de la fenêtre et à sa taille.
La seconde partie contient le texte proprement dit divisé en sujets. Les noms des sujets permettront l'association entre l'application SCR et le fichier d'aide.
scr4_h -option args ... @responsefile
OPTION ARGUMENTS REQ DEFAULT DESCRIPTION
------ --------- --- ------- -----------
-e chars N skip line if first char in chars
-f chars N skip chars if first in line
-wm N suppress macro warning
-s N suppress escape sequences
-esc ch N defines escape character
-list N list topics read
-o filename N output file (.hlp)
-log filename N log file
-c file ... Y compile files
-h N display help
filename est le nom complet du fichier input (avec ou sans extension). Le fichier compilé portera le même nom, mais cette fois avec l'extension hlp.
scr4_h -c help.txt : crée le fichier help.hlp à partir
du fichier ascii help.txt
scr4_h -e . -f ; -c help : crée le fichier help.hlp en
éliminant toutes les lignes dont le
premier caractère est un point et en
supprimant le premier caractère des
lignes commençant par un
point-virgule. Le fichier input
s'appelle ici help et non help.txt.
Cette section contient la ligne et la colonne du coin supérieur droit de la fenêtre d'aide, ainsi que la taille de cette fenêtre. En plus, on peut déterminer le titre et la footnote de la fenêtre.
La section se termine par le mot clé START qui indique que les textes des différents sujets vont commencer. Elle doit toujours se trouver en tête du fichier d'aide.
Chaque sujet est organisé de la façon suivante : le nom est placé entre crochets (< >) et collé à la marge de gauche. Le texte commence à la ligne suivante et se termine par un crochet fermant collé à la marge (>).
A l'intérieur du texte, on pourra placer autant de références à d'autres sujets que l'on veut, en mettant chaque fois le nom du sujet entre crochets. Dans le help compilé, ces crochets n'apparaîtront pas. Les majuscules, minuscules et espaces ne sont pas signifiants dans les noms des sujets. Par exemple,
<Liste des fonctions>
est équivalent à
<LISTEdesfoncTIONS>
Lorsqu'un crochet doit apparaître dans le texte, on le doublera (< ou >).
Si le nom du sujet ne convient pas dans une phrase, on indiquera le texte souhaité entre crochets, suivit directement du nom du sujet, lui aussi entre crochets :
<Quitter l'application><Fin>
Les topics peuvent être référencés par <-topic> au lieu de <topic>. Dans ce cas, il ne sera pas automatiquement repris dans la table des matières au niveau inférieur.
Les noms des topics peuvent atteindre 255 caractères. Idem pour la longueur des lignes de texte.
L'exemple ci-dessous présente un cas de ce type avec le mot simulation qui doit être une fois au pluriel, une fois au singulier.
On pourra inclure des fichiers par la directive
#include "filename"
L'effet est le même que si le fichier est copié à cet endroit du help. Si le caractère # doit apparaître dans le texte, il faut le doubler.
Line 3 col 3 nc 74 nl 19
TITLE " MARIBEL - Help "
FOOTNOTE " ESC:Retour à l'application "
START
<Table des matières>
TABLE DES MATIERES
<Simulation>
<Impressions>
<Fin du Travail>
>
<SIMULATION>
SIMULATION
Pressez F5 pour effectuer une simulation.
Pour les <impressions> des résultats, pressez Alt-P.
>
<IMPRESSIONS>
IMPRESSIONS
Les impressions des tableaux résultats peuvent s'effectuer
soit en niveau, soit en taux de croissance. Ces possibilités
peuvent se combiner avec l'impression d'autres résultats
de <simulations><simulation>.
>
<FIN DU TRAVAIL>
FIN DU TRAVAIL
Pressez Alt-X pour terminer le travail.
>
Les macros sont de définitions qui permettent de réduire l'encodage, et d'être consistant dans les notations et les formats à travers tout le manuel d'aide.
Elles sont définies comme suit :
&&MACRONAME comment
.... macro
.... definition
&& comment
Les signes && doivent être collés à la marge. Elles doivent être définies en dehors des topics (textes des sujets). Pour les utiliser, on procédera comme suit :
&MACRONAME texte
A nouveau, le caractère & doit être collé à la marge.
Si le dernier caractère de la définition est un &, il n'y aura pas de caractère '\n' généré lors de l'utilisation de la macro.
Si un redéfinition d'une macro est détectée par le compilateur de Help, un message est produit, mais la seconde définition ne replace pas la première. Cette caractéristique est volontairement implémentée : elle permet d'éviter de remplacer les définitions de l'utilisateur par celles générées automatiquement par scr4_mkh, définition qui sont lues nécessairement en second lieu.
&&TI /* TITRE */
..par1 parb
;&
&&
&&CO /* COURRIER */
..par cmd_1
..lf_on
..bl_on
&&
&&TX /* TEXTE */
..lf_off
..bl_off
..par par_1
&&
&&EN /* ENUM */
..par1 enum_1
; - &
&&
&&SY /* SYNTAX */
&TI Syntaxe
-------
&CO
&&
&&REM /* REMARQUE */
&TI Remarque
--------
&&
&&RT /* RETURN VALUE */
&TI Valeur retournée
----------------
&&
&&NO /* Note */
..par1 note
;NOTE
;----
&&
&&SA /* SEE ALSO */
&TI Voir
----
&&
&&EX /* EXEMPLE */
&TI Exemple
------
&CO
&&
&&EEX /* FIN D'EXEMPLE */
&TX
&&
La compréhension de ces exemples nécessite la connaissance de la syntaxe des fichiers a2m. Signalons simplement que
La macro TI est découpée en deux parties : la première concerne le seul texte généré pour le manuel papier : le paragraphe suivant est du type parb (paragaphe en bold). La seconde partie concerne le help on-line : aucun caractère n'est généré, et le retour ligne lui-même est supprimé (la présence du & supprime le dernier '\n' de la macro).
La macro EN (enumération) est aussi découpée en deux parties : dans le cas du manuel, il s'agit comme pour TI d'un changement temporaire de paragraphe. Dans le cas du help on-line, les 4 caractères " - " sont générés et le '\n' est supprimé.
Par exemple :
&EN ligne 1
&EN ligne 2
&EN ligne 3
&EN ligne 4
donne dans le help on-line
- ligne 1
- ligne 2
- ligne 3
- ligne 4
et dans le manuel
. ligne 1
. ligne 2
. ligne 3
. ligne 4
On notera qu'une macro peut en appeler une autre.
Le texte peut contenir des enrichissements typographiques. Ceux-ci sont définis dans la partie consacrée au programme scr4_a2m.
Si on souhaite supprimer les caractères d'enrichissement dans le fichier help généré, il suffit d'utiliser le paramètre -s à l'appel de scr4_h. C'est notamment utile lors de la génération du fichier .hlp utilisé pour un help on-line.
Copyright © 1998-2015 Jean-Marc Paul and Bernard PAUL - Envoyez vos remarques ou commentaires à bernard@xon.be