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

SCR/AL1 - TOME I. Les programmes

6. SCR4_MKH : analyse de sources C et création de help

Introduction

Une des premières règles que l'on demande de respecter à tout programmeur participant à un projet de développement est de documenter ses sources. A partir du moment où cette documentation est introduite au sein des programmes, il semble naturel de mettre au point des outils permettant une impression automatique ou mieux, la constitution d'un manuel "on-line".

Les éditeurs mt et mmt permettent quant à eux d'intégrer des manuels au format SCR/AL1 créés par l'utilisateur et compilés à l'aide de la commande scr4_h : le programme scr4_mkh se charge de générer automatiquement un fichier reprenant les commentaires et la syntaxe de toutes les fonctions C d'un projet donné.

On peut donc obtenir sans peine un manuel de toutes les fonctions d'un projet, accessible à tout moment dans l'éditeur mt ou mmt, et ce à l'aide des deux programmes scr4_mkh et scr4_h.

D'autres formats peuvent également être générés, comme les fichiers .hlp et chm de Windows, les formats .rtf pour MSWord, .html pour le Web ou encore mif pour Frame Maker.

Syntaxe

scr4_mkh -option args ... @responsefile


OPTION ARGUMENTS REQ DEFAULT DESCRIPTION
------ --------- --- ------- -----------
-o filename N mkh.mkh output file
-l N suppress first comment line
-nf N suppress file references
-nh N suppress header
-nl N suppress list of functions
-ns N suppress syntax of functions
-nt N suppress functions description
-s N include sources
-t topic N replace TOC by topic
-c file .. Y input C files
-h N display help

L'ordre des paramètres n'a pas d'importance.

Fichier d'aide produit par scr4_mkh

Le programme scr4_mkh produit un sujet pour chaque fonction C trouvée dans les sources, sauf pour celles dont le commentaire commence par les caractères "/*NH". Ceci est donc un moyen simple d'éliminer les petites fonctions dont l'importance ne justifie pas de les placer dans le fichier d'aide.

Pour chaque fonction, le fichier d'aide reprend tous les commentaires qui précèdent directement la fonction et la syntaxe de la fonction jusqu'à l'accollade ouvrante indiquant le début du code de la fonction.

Les textes extraits sont modifiés pour éviter les erreurs de syntaxe dans la compilation: les <, > et # sont doublés. Une exception : les topics repris sous forme <-topic> sont conservés dans l'extraction des aides.

Le fichier est composé de la façon suivante :

Macros

Le résultat du traitement de scr4_mkh est un fichier d'aide. Ce fichier est destiné à être compilé par scr4_h de façon à obtenir un fichier d'aide. Au sein des fichiers d'aides, il est possible de définir des macros (voir scr4_h). Ces macros sont définies comme suit :

    &&MACRONAME comment
.... macro
.... definition
&& comment

Elles permettent de travailler plus facilement lors de l'encodage du texte, mais - et c'est ce qui nous intéresse ici - surtout de définir des textes qui seront les mêmes à travers tous le manuel. Par exemple, le text "Syntax of functions" est défini par une macro, le formattage des titres de même, etc.

Ces macros ont la caractéristiques de ne pouvoir être redéfinies. Ceci permet à l'utilisateur de définir en entête de son fichier de help ses propres macros et de les rendre ainsi valables à travers tout le help.

scr4_mkh utilise les macros suivantes :

Les macros peuvent donc être redéfinies par l'utilisateur et replaceront celles par défaut qui se présentent comme suit :

    &&SY
..par1 parb
Syntax

..par cmd_2
..lf_on
..bl_on
&&
&&ESY
..par par_1
..lf_off
..bl_off
&&
&&DE
..par1 parb
Description

&&

Exemple

    scr4_mkh -o scra.fns -l -nf -t "scra" -c s*.c

scr4_mkh -o scra.syn -l -nf -nh -nl -nt -t "scra" -c s*.c

Le premier exemple analyse les fichiers s*.c (-c). Le résultat est placé dans le fichier "scra.fns" (-o). Les premières et dernières lignes des commentaires de fonctions sont sautées (-l). Les références aux fichiers sont supprimées (-nf). Le sujet "table des matières" est remplacé par "scr" (-t).

Le second exemple analyse les mêmes sources mais crée le fichier scra.syn au lieu de scra.fns. Les sujets "List of functions", le header, et le descriptif des fonctions sont supprimés. Il ne reste donc que la syntaxe des fonctions dans le fichier résultat.

Copyright © 1998-2015 Jean-Marc Paul and Bernard PAUL - Envoyez vos remarques ou commentaires à bernard@xon.be