Présentation	Documentation				L'équipe	Sérialisation
	Programmes	Objets	Libs Utilitaires	Libs Internes
	Editeur	Syntaxes	Windows	Versions

SCR/AL1 - TOME I. Les programmes

10. SCR4_HM : création d'un manuel à partir d'un help compilé

Ce programme crée un fichier qui servira à la constitution d'un manuel sur support papier à partir d'un fichier HELP compilé.

Le manuel généré aura un format "a2m", utilisable pour générer un document Frame via le programme scr4_a2m.

Syntaxe

scr4_hm -option args ... @response_file
 
 
OPTION   ARGUMENTS      REQ DEFAULT   DESCRIPTION
------   ---------      --- -------   -----------
-e       char            N            exclude first line char
-c       char            N  \         change escape char
-s                       N            sub-topics not dumped
-i       filename        Y            input .hlp file
-o       filename        N            output .a2m file if != input
-t       topic ..        N            topics (if not all)
-dup                     N            duplicate topics (if necessary)
-it                      N            suppress italic in topics
-h                       N            display help
 
 

• -e char : char est la liste des caractères qui doivent être supprimés s'ils se trouvent en début de ligne dans le texte du help
• -c char : caractère d'escape utilisé dans le format a2m pour mettre en italique les noms des sujets. Par défaut ce caractère est le backslash (\)
• -s : les sous-sujets des sujets à générer (voir -t) ne doivent pas être dumpés. Par défaut, tous les sous-sujets sont dumpés.
• -i help_file : nom d'un fichier HELP compilé.
• -o filename : nom du fichier output (par défaut, nom du fichier input, avec suffixe .a2m)
• -t topic ... : noms des sujets à générer. Par défaut, tous les sujets sont générés (y compris ceux qui ne sont pas référencés ailleurs)
• -h : affiche un message contenant les différents paramètres et leur signification.
• -dup : duplicie les sujets si nécessaire
• -it : supprime les italiques dans les références au sujets

Le fichier généré porte le même nom que le fichier help original, mais avec une extension .a2m, sauf si une extension est fournie dans le paramètre -o.

Algorithme de création du manuel

Par rapport au help on-line, qui se comporte comme un fichier de type hypertext, c'est-à-dire où il n'y a pas de hiérarchie des sujets, mais seulement des liens d'un sujet vers d'autres, le problème posé par la génération d'un manuel, nécessairement hiérarchisé n'est pas simple. Il faut trouver une façon de rendre hiérarchique les sujets qui en principe ne le sont pas.

Le créateur de manuel ne perdra jamais de vue cet aspect, sans quoi le manuel généré ne donnerait pas satisfaction sur le plan de la structure.

La seule façon raisonnable est de prendre le premier sujet, de lui donner le niveau 0, de prendre ensuite les sujets référencés au sein de ce premier sujet et de leur donner à chacun un niveau 1. En procédant de même dans les sous-sujets, on obtient finalement une manuel dont la table des matières est cohérente.

Une exception : si un sujet est référencé avec <-sujet> au lieu de <sujet>, il ne sera pas repris dans la table des matières au niveau inférieur.

Dès qu'un sujet est rencontré dans un texte, il est marqué pour être imprimé dans le niveau suivant et pour ne plus être imprimé plus tard.

Prenons un exemple. Les sources suivantes sont la description du help en ascii. Nous verrons ensuite comment scr4_hm se débrouille pour générer à partir de là un manuel hiérarchisé.

L'exemple est volontairement excent de texte de façon à clarifier l'exposé.

    <sujet0>
 
        <Sujet1>
        <Sujet2>
    >
 
    <sujet1>
 
 
        <sujet2>
        <sujet1.1>
        <sujet1.2>
    >
 
    <sujet2>
 
        <sujet1>
        <sujet1.1>
        <sujet2.1>
    >
 
    <sujet3>
 
        <sujet1>
        <sujet2>
    >
 
    <sujet1.1>
 
        <sujet1>
        <sujet1.2>
    >
 
    <sujet1.2>
 
        <sujet2>
        <sujet1.1>
    >
 
    <sujet2.1>
 
        <sujet2>
    >

La structure et les niveaux de titre du paragraphe résultat seront les suivants :

Sujet0                          tit_0
 
    sujet1                      tit_1
        sujet1.1                tit_2
        sujet1.2                tit_2
 
    sujet2                      tit_1
        sujet2.1                tit_2

On remarque à la lecture du résultat :

• que sujet2, bien que référencé dans sujet1, se trouve sur le même pied que sujet1. Ceci est dû au fait que sujet2 a été rencontré dans sujet0, donc marqué à ce niveau.
• que sujet1.1, présent dans sujet2, se trouve cependant dans sujet1. A nouveau, il a été rencontré plus tôt (dans sujet1) et est donc déjà marqué au moment d'analyser sujet2.
• que si sujet1.1 n'était pas référencé dans sujet1, il se trouverait par conséquent sous sujet2.
• que les sujets non accessibles à partir du sujet0 ne sont pas repris dans la table des matières (comme sujet3). Ces sujets sont simplement ajouté en fin de manuel pour une utilisation éventuelle.
• que le sujet2 n'a qu'un sous-sujet, ce qui n'est pas précisément élégant dans le manuel.

Distinction entre fichier on-line et manuel-papier

Il est facile de construire une table des matières différente pour le manuel on-line et pour le manuel papier : il suffit de préfixer les lignes du manuel on-line par un caractère (; est le standard) et les lignes du manuel papier par un autre caractère (. est le standard).

De cette façon, le compilateur scr4_h, selon les caractères spécifiés dans ses paramètres -e et -f générera des manuels structurés différemment.

Enrichissement du texte

scr4_hm enrichit automatiquement le texte généré en utilisant les règles suivantes :

• scr4_hm met tous les noms de sujets rencontrés dans le texte en italique. Si le caractère \, qui est celui par défaut, ne convient pas, il est possible de le remplacer par un autre spécifié à la suite du paramètre -c.
• le premier paragraphe de chaque sujet est considéré comme un titre de niveau égal au niveau dans la hiérarchie. Ces paragraphes sont tit_1, tit_2, ...
• après le titre, les paragraphes d'un sujet sont également différenciés suivant le niveau de hiérarchie : par_1, par_2, ...