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 :

  1. Arguments :
    1. -files "Liste de fichier" : Permet de specifier une liste de fichier+un pattern
      Exemple : "-files ./*.tcl ./*.tk"
    2. -f : force l'effacement des fichiers
    3. -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.
    4. -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.
    5. -h : Affiche l'aide concernant l'utilisation de pistMkDoc
  2. 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 :

  1. 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 * *)"

    1. Arguments
      1. dirlist Répertoire de base où va s'effectuer la recherche
      2. globlist Pattern permettant de selectionner les fichiers
    2. Exemple
      recursive_glob . * retourne {./rep1 ./fich1 ./fich2 ./rep1/fic11 ./rep1/fic12 ....}
    3. Remarque
      Attention si globlist contient ".*" alors les répertoires de la forme ".../." et .../.." font partie du résultat !!
    4. 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
    5. 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 :
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)