Le 13 mai 2008

Zdoc: version 1.1

Zdoc est un générateur de documentation pour des projets TCL.

Zdoc analyse un ensemble de programmes source TCL et produit la documentation
des procédures en format HTML.

Ecrit en TCL pur, zdoc.tcl ne demande aucune extension;
Il ne demande pas non plus des tags documentaires spécifiques.

Cet outil est dédié à toutes les personnes utilisant le langage TCL.

Copyright Vincent Wartelle © 2001-2004 Oklin.com ®
Ce logiciel est livré sous licence BSD: libre pour tout usage, sans garantie aucune.
Voir le texte de licence (anglais) license.html

Entrées et Sorties

Zdoc analyse un ensemble de programmes TCL, et il écrit:

• un fichier index.html, index de tous les programmes et des procédures qu'ils contiennent;
• et un fichier nomProgramme.html correspondant à chaque fichier source.

Le fichier index.html comporte un tableau HTML par fichier source, lequel comprend une ligne par procédure.

• Dans ce fichier d'index, cliquer sur le nom d'une procédure conduit à la procédure correspondante dans le fichier détaillé.
  Cliquer sur le nom de procédure dans le fichier détaillé retourne au fichier d'index...
  On passe ainsi facilement de la vue d'ensemble à la vue détaillée.
• Chaque ligne de l'index décrit: nom de la proc, nombre de lignes, commentaires d'entête, liste des arguments.

Chaque fichier détaillé nomProgramme.html comporte un tableau HTML par procédure (proc);

• ce tableau montre les commentaire d'entête de la proc, ses arguments, les références croisées :
  procédures utilisées par la proc , procédures utilisant la proc; puis le code source de la procédure.

La documentation des références croisées constitue un atout majeur de Zdoc.
Ces références croisées sont des liens HTML, qui permettent une navigation rapide à travers la logique du projet documenté.
( voir les exemples dans les liens ci-dessous )

Mode d'emploi

Zdoc est facile à utiliser. Dans votre environnement TCL,

• "Sourcer" le programme zdoc.tcl;
• Exécuter la procédure zdoc::init pour initialiser Zdoc;
• Indiquez les options nécessaires (voir tableau)
• Lancez la procédure zdoc::run pour analyser les programmes TCL et produire la documentation.

Par exemple, en utilisant tclsh, analyser les programmes TCL tcl/bin.tcl et tcl/grun.tcl, et créer la documentation HTML dans le répertoire doc/ :

unix> tclsh
% source ../public/tcl/zdoc.tcl
% zdoc::init
% zdoc::set_filelist {tcl/blin.tcl tcl/grun.tcl}
% zdoc::set_outdir doc
% zdoc::run
% exit
unix> ls doc
blin.tcl.html grun.tcl.html index.html


Les tableaux ci-dessous détaillent les procédures qui permettent de contrôler et d'exécuter Zdoc, ainsi que ses limites.

Télécharger

Télécharger ! zdoc.tcl (23ko)
La version précédente 1.0 : zdoc_10.tcl

Historique

1.0 - 2001/09/27 première version
1.01 - 2001/10/31 - non publiée - contributions de Patrick Fradin

• ne pas prendre en compte les fichiers pkgIndex
• expressions entre accolades (optimisation)
• ajout de l'option -nocomplain dans le glob de ::init
• outdir initialisé en tant que [file join [pwd]], et non [file join .] dans ::init

1.1 - 2003/03/05

• avec corrections 2003/2/28 de John McGehee, Voom, Inc. www.voom.net :
•    correction des noms de fichiers et liens pour supporter
  filelist dir != working dir != outdir
• aide sur la documentation anglaise
• changement de format de date et de position du message "generated by zdoc"
• ajout de l'option _omitlines
• admettre un caractère blanc avant le mot clé proc et son accolade de fin

Liens

A titre d'exemple, la documentation que Zdoc génère pour lui même
Un exemple plus conséquent, la doc du toolkit graphique BWidget-1.5 et zdocbw.tcl le programme qui l'a généré (il y a des pièges techniques).
Le domicile de Tcl chez ActiveState
Le portail TCL/tk francophone
Autodoc, le générateur de documentation de A.Kupries.
Le livre de recettes TCL d'ActiveState, où l'on peut trouver tcl2html, un convertisseur de tcl en html colorisé, écrit par J. Hobbs

Fonctions	Description	Valeur par défaut
zdoc::init	initialise le générateur et pose ses options par défaut
zdoc::set_filelist { liste de procédures TCL }	définit les fichiers source à analyser	tous les fichiers *.tcl du répertoire courant
zdoc::set_outdir répertoire	définit le répertoire où Zdoc placera les documentations	sous-répertoire "zdoc" du répertoire courant
zdoc::set_procsort alpha | asintext	définit dans quel ordre les procédures seront triées asintext signifie : dans le même ordre que celui des programmes source	alpha
zdoc::set_codeprint yes | no	décide si le code source est inclus dans la documentation	yes
zdoc::set_source yes | no	décide si les programmes sont "sourcés" ou non. Pour faire fonctionner l'information concernant la liste des arguments et les références croisées, Zdoc a besoin de sourcer les fichiers à analyser. Mais certains d'entre eux peuvent avoir besoin d'un contexte particulier pour être sourcés. Le choix "no" signifie que l'utilisateur prendra à sa charge cette tâche avant de lancer l'analyse.	yes
zdoc::set_tabsize valeur	définit la taille des tabulations, en nombre de blancs; c'est utile pour l'impression du code en html: les tabulations sont traduites en blancs.	4
zdoc::set_omitlines 1 | 0	definit si les commentaires de type "#---------------" doivent être affichés (ils ont peu d'intérêt à l'intérieur de tables html).	1
zdoc::run	lance l'analyse et crée la documentation
zdoc::reset	remet à zéro toutes les structures de stockage de Zdoc, pour se préparer à une nouvelle éxécution.
zdoc::analyze	fait fonctionner l'analyse des sources seule
zdoc::create_doc	fait fonctionner la génération de documentation seule

Limites

Zdoc est fait pour documenter du code TCL standard réparti en procédures. Il ne fonctionnera peut-être pas sur des constructions sophistiquées, où par exemple le mot-clé "proc" a été remplacé.

Zdoc ne documente que les procédures, pas le code situé en dehors.

L'analyse a besoin de "sourcer" chaque procédure, parce qu'elle utilise les fonctions "info proc", "info args" et "info body"; ainsi tout code situé en dehors des procédures sera éxécuté. Et si un contexte particulier est nécessaire au "sourçage" (!) des procédures, ,Zdoc ne l'aura pas. Pour résoudre ceci, utiliser l'option zdoc::set_source "no" , et sourcez les fichiers par vos propres moyens.

Le mot-clé "proc" et son accolade de fin "}" doivent commencer la ligne, et peuvent être précédés d'un seul blanc.

Les références croisées ne seront correctes que si les procédures sont appelées par un nom identique à celui de leur déclaration. Autrement dit, Zdoc n'active pas les mécanismes de résolution des namespaces;

Dans la présentation du code, il y a une mise en couleur syntaxique très limitée: seules les lignes de commentaires (pleine ligne) sont colorées en vert. Les mots-clés, variables, noms de procédures ... ne sont pas colorés. Cette limite permet à Zdoc d'être très rapide.

Dans la présentation du code, l'indentation ne sera correcte que si l'emploi des tabulations est correcte et l'option set_tabsize bien employée. Une autre méthode consiste à sauvegarder les sources avec des espaces seulement, sans tabulation.

Les expressions régulières un peu complexes comme {(^|[^\\])(\$\{[^\}]*\}|\$[a-z0-9_]+(\([^\)]*\))?)} (chères à Jeff), pourraient ne pas être traduites correctement en HTML.

Remarque concernant les tags

Si un jour Zdoc supporte les tags, ces tags seront les mêmes que dans Autodoc Voir la liste ici.