AutoDoc 1.3
Jean-Noël Albert
albert@lal.in2p3.fr
Mai 1997
Introduction
L'objectif de la documentation automatique est de réduire la
contrainte que représente pour les développeurs la rédaction
des manuels d'utilisation des logiciels. Pour ce faire, les
commentaires présents dans les fichiers sources sont extraits
et mis en forme grâce à une série d'utilitaires constituant
AutoDoc.
Pour être exploitable, ces commentaires doivent respecter un
format particulier, décrit dans cette note. Les conventions
utilisées sont en nombre limité, et cherchent à être aussi
``intuitives'' que possible.
Une telle approche ne remplace certes pas la documentation
traditionnelle, mais elle peut la simplifier, et donc en
accélérer la production.
Présentation des outils
AutoDoc est constitué de plusieurs utilitaires réalisant
chacun une partie du travail de génération des documents. Les
outils disponibles sont les suivants :
- docextract : extrait les commentaires;
- docselect : sélectionne certaines parties des commentaires extraits;
- docgrep : filtre les commentaires selon différents critères;
- docsort : met en ordre alphabétique les commentaires sélectionnés;
- doc2ascii : convertit les caractères accentués en caractères ASCII;
- doc2html : construit un document au format HTML;
- doc2latex : construit un document au format \LaTeX{};
- doc2man : construit un document au format des \italic{man pages} UNIX;
- doc2rtf : construit un document Rtf, destiné au traitement de texte
Microsoft Word~{\footnotesize\copyright}~\footnote{Non
disponible dans cette version}.
Documentation
Des exemples et la description des différents outils de AutoDoc
est disponible dans la note AutoDoc.ps.gz.
Mise en oeuvre
Les outils AutoDoc sont des scripts écrits en langage Tcl.
Ils utilisent l'extension TclX.
L'ensemble des outils fonctionnent avec la version 7.6 de Tcl
et TclX. L'utilisation de la version 8.0 (encore
provisoire) est possible grâce à un script doc.tcl
mimant les quelques instructions TclX nécessaire.
Le logiciel s'installe à l'aide d'un script
d'auto-configuration \bold{Gnu}. Le fichier \term{INSTALL}
donne plus d'informations sur l'utilisation de ce script.
Pré-requis
- une version raisonnablement récente de Tcl -- Tcl 8.0 est
beaucoup plus rapide, Tcl 7.6 est plus stable;
- éventuellement, la version correspondante de Tcl Extension;
- une version récente de LaTeX2e (de préférence TeTeX);
pour pouvoir imprimer cette documentation.
Installation
Le script de configuration vérifie l'existence des
shells tclsh8.0, tcl,
tclsh7.6,
tclsh et choisit le premier qu'il rencontre.
Les étapes de l'installation sont les suivantes :
- exécuter le script ./configure;
- exécuter make install;
- construire la documentation par make doc.
Par défaut, les outils seront installés dans
/usr/local/bin. Il est possible de spécifier un autre
directory grâce à l'option -prefix de
./configure.
Les outils utilisent les services du script \term{doc.tcl} qui
est cherché par défaut :
- dans le directory courant;
- dans le sous-directory lib/AutoDoc du
directory
d'installation (éventuellement imposé par l'option -prefix);
- dans le directory désigné par la variable d'environnement
AUTODOC_LIBRARY, si celle-ci existe.
La recherche des drivers utilise la même stratégie.
Les fichiers de styles manual.cls et note.cls,
ainsi que le pilote styles.init, destiné à
latex2html et le logo Eros ErosLogo.eps sont
placés dans un sous-directory lib/tex du
directory d'installation.
La variable d'environnement TEXINPUTS doit être définie
de manière à ce que LaTeX accède automatiquement à ces styles.
Si, par exemple, le responsable a choisi d'installer le logiciel
avec les options par défaut, dans /usr/local, il faudra
redéfinir la variable TEXINPUTS par :
setenv TEXINPUTS .:/usr/local/lib/tex//:
ou bien déplacer les fichiers de styles dans l'arborescence
standard de LaTeX.
Historique
Liste des modifications
- version 1.2 --
- styles \term{manual} et \term{note} pour \LaTeXe;
- adpatation des conventions de définition des textes et
des mots-clés dans les articles grâce aux options
\term{-head} et \term{-separator} de \term{docextract};
- nom des fonctions comme titre implicite;
- introduction des séquences de code en tant qu'exemples;
- description et extension de la notion de \emph{driver}.
- version 1.3 --
amélioration de la conversion des conventions typographiques,
de manière à supporter des ``tags'' imbriqués.