docMaker
docMaker est un script en Perl qui explore des fichiers source
à la recherche d'en-têtes, dans le but de générer
de la doc à partir de leur contenu.
1) USAGE
docMaker.pl [-d dir] [-t type] <liste de fichiers sources>
NOTE : docMaker générera un fichier Truc.txt à
partir de Truc.cxx. Attention si vous avez des fichiers qui portent le
meme nom...
2) ARGUMENTS
2.1) DESTINATION
-
-d directory : mettre les fichiers générés dans
ce répertoire (sinon, c'est le répertoire courant par défaut),
2.2) TYPE
-
-t ascii : (par "défaut") générer au format ASCII
(épuré),
-
-t tws : générer les pseudo-tag TWS pour améliorer
la conversion ASCII --> HTML de tws,
-
-t rtf : générer un fichier RTF, avec trois niveaux de
chapitres, ce qui facilite l'insertion propre dans un document Word.
Les fichiers ASCII et TWS sont générés avec une
extension .txt, et les fichiers RTF avec une extension .rtf.
Les fichiers générés avec l'option -t tws peuvent
être convertis en fichiers .html avec tws (Trivial
Web Site). Les fichiers .txt et .rtf qui ont été générés
par docMaker peuvent également être convertis par tws, mais
le résultat sera moins adapté, et il manquera le sommaire
en début de document.
3) DESCRIPTION
Il n'y a pas de contrainte forte sur la forme de l'en-tête, du
type "utilisation obligatoire de mots-clé" pour que ça marche
bien.
Toutefois, pour être prise en compte par docMaker, les en-têtes
doivent respecter les deux règles ci-dessous :
-
le marquage du début d'en-tete doit être plus long
qu'un simple /*,
-
le commentaire doit avoir au moins deux lignes,
-
les mots clé sont EN MAJUSCULE, avec au plus UN mot clé
par ligne.
'docMaker' analyse chaque contenu (entre deux mots-clé) afin
de deviner si il s'agit :
-
de code informatique (qui sera traité "préformaté"),
-
d'une liste énumérative,
-
de texte simple (qui fera des paragraphes).
4) GENERATION
Le document est généré selon le modèle ci-dessous
:
titre (nom du fichier source)
Table des Matières (liste des chapîtres) (liens sur des
anchors HTML si le type est tws) [chapître 1) le fichier (optionnel,
si l'en-tête existe) ]
chapître N ) nom de la fonction [(static)]
chapître N . sous-chapitre M ) mot clé de l'en-tête
contenu associé au mot clé (entre deux mots-clé)
5) TIPS
Si ce @#&%#$% de machin refuse de faire ce que vous voulez, voici
quelques trucs.
Si vous voulez forcer docMaker à interpréter
certaines de vos lignes comme des éléments de listes :
-
commencez les lignes en question par un - ou un 1- ou un 1.,
-
terminez la ligne qui précède votre liste par un
:, et il regardera de plus près si les lignes suivantes commencent
par un -
Si des lignes qui se suivent sont transformées en magma
(en paragraphe), pas de panique :
-
insérez un return supplémentaire pour bien les isoler,
-
puisque ça ressemble à une liste, faîtes-en une
!
-
encadrez le tout avec un <<<'....'>>>, comme si vous vouliez
insérer un exemple, et tws le traitera "tel-quel' .
exemple encapsulé par <<< et >>>
(Ce texte est preformaté) c'est FOU comme on peut s'amuser avec
des TAB, non ?
Vous pouvez aussi consulter :
Et si le résultat ne correspond pas à vos attentes, venez
me voir.
6) TODO
-
ne plus faire n'importe quoi avec les méta-caractères,
ce qui permettrait (entre autres) de révéler les destructeurs
des classes C++ mais aussi les surcharges d'opérateurs...,
-
traiter l'extension du fichier .c, .cc, .f, ... pour adapter les stratégies
de reconnaissance et de filtrage d'en-tête,
-
être encore plus intrusif pour la conversion en RTF, et insérer
plein de <par> pour séparer les lignes (la version actuelle a
tendance à faire des paragraphes là ou il n'y en a pas)
-
parser le code source pour generer la liste des fonctions, puis
brancher les en-têtes sur cette liste pour faire apparaître
les en-têtes manquantes,
-
accepter d'autres langages (et pourquoi pas du BASIC ?)
7) AUTEURS