Utilisation
Le programme pistMkDoc.tcl permet de parser un ou plusieurs fichiers
TCL en vue de générer automatiquement une documentation HTML sur
ces fichiers.
Utilisation de la procédure :
- Arguments :
- -files "Liste de fichier" :
Permet de specifier une liste de fichier+un pattern
Exemple : "-files ./*.tcl ./*.tk"
- -f : force l'effacement des fichiers
- -out FileName : Nom du fichier HTML de sortie, si cette
option n'est pas spécifiée le nom du fichier de sortie est a.html.
- -tmp Directory : Emplacement des fichiers temporaires
Si cette option n'est pas précisée, les fichiers temporaires seront
placés dans les répertoire courant, ou bien dans le même répertoire
que le fichier HTML de sortie si l'option -out est précisée.
- -h : Affiche l'aide concernant l'utilisation de pistMkDoc
- Exemples :
Pour générer une documentation à partir de fichiers Tcl situés dans le
répertoire Lib/Canvas/, il faut utiliser la ligne de commande
suivante :
pistMkDoc.tcl -f -files "Lib/Canvas/*.tcl REPERTOIRE/TOTO/*.tk" -out ../../DocAuto/Canvas.html
Si le fichier ../../DocAuto/Canvas.html existe, il sera alors écrasé
dans la mesure où l'option -f a été spécifiée.
Les fichiers temporaires utiles pendant l'exécution du programme seront
placés dans le répertoire ../../DocAuto/. Si l'option
-tmp Dir est spécifiée, le répertoire Dir est utilisée
pour les fichiers temporaires.
Exemple de Commentaire
Le commentaire suivant :
########################################################################
# recursive_glob -- Retourne une liste récursive d'éléments d'un répertoire
# Retourne une liste récursive de fichiers ou répertoires
# sous la forme <i>dir</i>/<i>relativeFilePath</i>.
# Attention la liste optenue peut contenir des répertoires ou des
# doublons (de la meme façon que la commande UNIX "ls * *)"<p>
#
# Arguments:
# dirlist - Commentaire rapide sur le paramètre
# Ceci est un commentaire plus long sur le paramètre <I>dirlist</I> de
# de la procédure.
# globlist - Pattern permettant de selectionner les fichiers
# Exemple:
# recursive_glob . *
# retourne {./rep1 ./fich1 ./fich2 ./rep1/fic11 ./rep1/fic12 ....}
# Remarque:
# Attention si globlist contient ".*" alors les répertoires
# de la forme ".../." et .../.." font partie du résultat !!
# Exemple d'utilisation:
# <CODE>set ABS [recursive_glob [pwd] $listOfPatterns]</CODE> : liste
# de noms absolus<br>
# <CODE>set REL [lcutleft $ABS [expr [string length [pwd]] + 1]]</CODE>
# : liste de noms relatifs
# Modif 10/06/96:
# compatibilité Mac et Windows (utilisation de la commande file join...).<BR>
# Problemes potentiels
# avec les fichiers invisibles pour unix (* et .*)
########################################################################
donnera le résultat suivant :
recursive_glob
Retourne une liste récursive d'éléments d'un répertoire
Retourne une liste récursive de fichiers ou répertoires
sous la forme dir/relativeFilePath.
Attention la liste optenue peut contenir des répertoires ou des
doublons (de la meme façon que la commande UNIX "ls * *)"
- Arguments
- dirlist Répertoire de base où va s'effectuer la recherche
- globlist Pattern permettant de selectionner les fichiers
- Exemple
recursive_glob . *
retourne {./rep1 ./fich1 ./fich2 ./rep1/fic11 ./rep1/fic12 ....}
- Remarque
Attention si globlist contient ".*" alors les répertoires
de la forme ".../." et .../.." font partie du résultat !!
- Exemple d'utilisation
set ABS [recursive_glob [pwd] $listOfPatterns]
: liste
de noms absolus
set REL [lcutleft $ABS [expr [string length [pwd]] + 1]]
: liste de noms relatifs
- Modif 10/06/96
compatibilité Mac et Windows (utilisation de la commande file join...).
Problemes potentiels
avec les fichiers invisibles pour unix (* et .*)
Principe
Le principe est simple, on parse les fichiers spécifiés sur la ligne de
commande grâce à l'option -files un par un. Pour chaque fichier,
on crée 2 fichiers temporaires permettant de stocher les informations
HTML issues des commentaires du fichier parsé. Puis, une fois que l'on a
terminé de parser le fichier, les informations sont recollées dans 2
autres fichiers temporaires (ces derniers existent pendant toutes la
durée d'exécution du programme pistMkDoc.tcl). Ces fichiers sont :
- $pistMkDoc(tmpDir)/lof.tmp et
- $pistMkDoc(tmpDir)/ldop.tmp
Enfin, les 2 fichiers temporaires sont concaténés pour former le fichier
HTML de sortie spécifié grâce à l'option -out.
- Description des fichiers temporaires :
- $pistMkDoc(tmpDir)/lof.tmp : Contient la liste des fichiers
dont on veut genérer une documentation. Ce channel est mémorisé dans
pistMkDoc(lof) (lof comme Liste Of File)
- La procédure parseTCLFile utilise 2 fichiers temporaires :
- $pistMkDoc(tmpDir)/lop.tmp : Contiendra la liste des
procédures dans fichier TCL parsées par parseTCLFile (lop comme
Liste Of Proc)
- $pistMkDoc(tmpDir)/dop.tmp : Contient la description HTML
des procédures du fichier TCL parsées par parseTCLFile
(dop comme Description Of Proc)
- Enfin un dernier fichier est nécessaire comme accumulateur :
- $pistMkDoc(tmpDir)/ldop.tmp : Contient la description
des fichiers TCL déjà parsée par la procédure parseTCLFile. Ce
channel est mémorisé dans pistMkDoc(ldop) (ldop comme Liste and
Description Of Proc)