oklin.com
Accueil Gestion de
documents		 Services Gestion de
comptes		 Open
Source		 English english
Lipsumcolor Zdoc

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.