Mkd (Extracteur de documents)/La commande mkd

Générer la documentation logicielle

Ce livre doit être rangé sur l'étagère Wikilivres Informatique
Systèmes d'exploitation, langages informatiques, logiciels CDU/6/68/681/681.3/681.3.0

Introduction

modifier

mkd est une commande destinée à extraire la documentation pour la maintenance et l'exploitation des logiciels en même temps que la compilation, selon les normes ISO^[1]^[2].

Disponibilité

modifier

Les paquets Debian peuvent être convertis pour d'autres systèmes linux avec Alien

Lien : Site officiel du convertisseur de paquets Alien

Packages debian - ubuntu amd64 et i386.
Télécharger mkd_140315.tar.gz archive source sur launchpad.
Sources et paquets RPM pour systèmes bâtis sur le projet Fedora.
Sources et distributions pour systèmes Windows et dérivés (Cygwin, Mingw).

Syntaxe

modifier

mkd [-ABCFPSafjlnpstvw] codes chemin_source [chemin_cible]

Description

modifier

mkd

Les commentaires sélectionnés, dans le pseudo-code, ou tout commentaire, d'un fichier informatisé sont extraits et copiés dans un fichier cible « document » afin de produire la documentation désirée.

On peut extraire en standard tout document texte de n'importe quelle langue enregistrée au format UTF-8.

Habituellement les fichiers documents sont:

Cycle de développement (logiciel)

Pour les fichiers de programmation ( Assembleur, Basic, C, etc. );

Les fichiers documents sont des Organigrammes, des Structures de blocs de codes, des commentaires pour Programmeurs (parfois nombreux), des points de Tests (ou blocs de tests) et 'warnings' avec les numéros de lignes .... Les codes de sélection peuvent être respectivement 'O', 'S', 'P', 'T' et "www" juste après le caractère début de commentaire.

Des fichiers spéciaux. Les options de compilation standards permettent de nombreuses possibilités. Elles permettent d'extraire des documents balisés avec des caractères spéciaux (" texte ") (% texte Fin de ligne) etc. Voir les options « -l ligne » et « -p page ».

Fichiers inhabituels:

Ajouter un fichier de décodage spécifique à un balisage ( html, xml, etc ).

codes

Ce sont des caractères alphanumériques. Les commentaires commençant par ces caractères sont extraits du fichier source et sont ajoutés au fichier « document ». Tous les caractères ASCII peuvent servir a coder les commentaires; toutefois on utilise ordinairement des caractères en majuscule, sauf w pour 'warning'. Avec deux étoiles “**”, mkd extrait tous les commentaires. (Voir aussi option t et les exemples).

chemin_source

C'est le hemin du fichier source (ou fichier de projet: avec option -j)

[chemin_cible]

C'est le chemin du fichier cible « document ». Par défaut chemin_cible est une copie du chemin_source auquel on remplace le suffixe par le suffixe ´.doc´ jusqu'à la version mkd_120508.

Options

modifier

Voir Shell Interface système.
Voir aussi les Notes pour les styles de langages.

Options [-ABCFPSafjlnpstvw]

       Les options en majuscules restreignent l'extraction des commentaires à
       un style de langage:
 
       -A     extrait le style Assembleur (   ;    -> fin de ligne)
 
       -B     style Basic                (REM ou ' -> fin de ligne)
 
       -C     style C++                  (   //  et  /*  ->  */   )
 
       -F     style Fortran              (c,C ou * -> fin de ligne)
 
       -P     style Pascal               (   { ... } et (* -> *)  )
 
       -S     style Shell ou Ratfor      (   #     -> fin de ligne)
 
       Les options en  minuscules  agissent  sur  la  manière  d'effectuer  le
       décodage:
 
       -a     (append)   Ajoute   à   la   suite   du   fichier   documentaire
              ´chemin_cible´.
 
       -f     (find)  Trouve  le  langage  du  fichier  source  par analyse du
              suffixe. (s´utilise généralement avec un fichier projet)
 
       -j     (project) S´utilise avec un fichier projet composé de sources en
              langages différents.
 
       -l     (lignes) Extrait les lignes commençant par les caractères CD1 ou
              CD2 ou CD3 et suivis par un des caractères codes, le commentaire
              se  termine  par  la lecture du caractère ´New Line´. CD1 et CD2
              doivent être placés en 1ère colonne, alors  que  CD3  peut  être
              placé  en  milieu  de  ligne. CD1, CD2, CD3, sont des options de
              compilation dans le fichier version.h de la distribution  source
              de mkd. On peut connaître ces options compilées par la  commande
              mkd \? sous Unix/Linux ou mkd ? sous DOS ou Terminal Widows.
 
       -n     insère un numéro de ligne
 
       -p     (page) Extrait le texte débutant par le caractère CD4 suivi d´un
              des caractères codes, l'extraction  du  commentaire  se  termine
              avec la lecture du caractère CD5. CD4 et CD5 sont des options de
              compilation dans le fichier version.h de la distribution  source
              de mkd. On peut connaître ces options compilées par la  commande
              mkd \? sous Unix/Linux ou mkd ? sous DOS ou Terminal Widows.
 
       -s     (screen : add to)  Duplique  les  commentaires  extraits  sur la
              sortie standard. Permet les redirection shell et  les  filtrages
              >, >> , || grep , etc
 
       -t     (text) Ne copie que le commentaire.

       -v     (verbose) Bavard. Ajoute des détails de décodage dans le fichier
              cible
 
       -w     (overwrite) Crée ou écrase le fichier cible « document ».

Options compilées et de compilation

modifier

Pour visualiser les options compilées il faut interroger la commande mkd:

mkd \? sous Linux ou mkd ? sous Windows.
On obtient les options qui ont été compilée avec la version courante de mkd, à la ligne -l et -p.

      -l et -p:   ligne;  (compil.: % ou - en première colonne ou # dans la ligne)
                  page:  (compil.: commence avec " et se termine avec ")

Ici, l'option -l permet:

avec # (typé shell) : d'extraire les conditions de compilation (#define, #ifdef, etc)

Cette option permet de se substituer à l'option impérative -S et d'utiliser l'option -f

avec % : typé PostScript

avec - : peut-être ADA ? commentaire ligne que l'on extrait aussi avec avec cat et grep (Voir aussi le manuel de grep)

grep -n -e --[Code] <Fichier_source> [> Fichier cible]

Autres options possibles avec -l : \' typé Basic, ; typé Assembleur, etc.

Ici, l'option -p permet d'extraire toutes les chaînes de caractères avec les codes '**'

Exemples

modifier

Exemple de fichiers sources pour générer la documentation

modifier

Quand c'est possible on écrit chaque fonction d'une application dans un fichier séparé, afin de produire une documentation dans un ordre alphabétique.
Quand les fonctions sont regroupées dans un même fichier, la documentation des fonctions apparaîtra dans le même ordre que dans le fichier.

Dans le fichier de la fonction on précise sa syntaxe d'utilisation, le fichier d'entête (header), ainsi que son usage.

Exemple pour la fonction cpp_ : du fichier cpp.c copié du manuel Linux "man 3 cpp"
Notez que les logiciels destinés à la traduction doivent être écrits en anglais

/*P
     File cpp.c
     Programmers directives (in V cycle)
     Last Date and Programmer name
*/

/*D 
	function cpp_
 -----------------------------------------------------------------------------
NAME
       cpp_ - Extract coded informations from C, c++, php source files.

SYNOPSIS
       #include  "/usr/include/mkd/version.h" // IMPORTANT: Compilation
          directives

       #include "/usr/include/mkd/cpp.h"

       int cpp_(FILE * pfdoc, FILE * pnfile);

DESCRIPTION
       The cpp_ function reads the source file (pnfile) transmitted 
       from  the calling  function,  and  decodes  the  comments
       pre-encoded in lines or blocks of style C, c++ or php files, and
       writing  this  comments  in  a target file (pfdoc).

       Pre-coded characters are defined in a external global table
       'Codes':

              The golbal external variables are 'Codes' and 'Options':

       extern char codes[];
              They  must  be  défined in the calling function; char
              codes[5] =
              {0,0,0,0,0}; table of 5 ASCII characters on 8 bits.
              The comment are  extracted  if the comment begin with
              one of these characters.

       extern unsigned char n,s,t;
              They must be defined in  the  calling  function;  
              unsigned char n=0,s=0,t=0;

       -n     The transcript is preceded by line number. This allows to
              easily reach the commented line.

       -s     Add the comment to the terminal or Konsole to  use  shell
              redirections > , >> , or || etc.

       -t     With  the  t  option  only  the commented text is copied.
              Without the t option the entire line or block is  copied.
              The  t option permit to generate directly exploitable and
              publishable documents.

RETURN VALUE
       Return 0 in case of success in  konsole  version,  nothing  with
       gtkmm.

CONFORMING TO
       All UNIX / LINUX systems with gcc

AUTHORS
       Contact : ..................

RESOURCES
       If  your product is designed to work with any graphical applica‐
       tion, then the file cpp.c++ is ready to  use  gtkmm.  (See  also
       mkdcppw)

FILES
       cpp.c, cpp.h, version.h

       /usr/include/mkd/ : mkd header files

       /usr/src/mkd/ : mkd source files

NOTES
       Not ready for read and decode files including sources files

BUGS
       Bugs Report: http://edeulo.free.fr/phpBB3/index.php

SEE ALSO
       Documents generator mkd(1) “man mkd”

COPYRIGHT: (Specified in version.h) :
*/

/*H  
	// cpp.c:
	extern int cpp_ (FILE *pfdoc, FILE *pnfile);
*/

     int cpp_ (FILE * pfdoc, FILE * pnfile)
     { //S Function Begin
       ... // Code
     } //S Function End

Exemple de fichiers cibles obtenus

modifier

Exemple de fichier d'entête obtenu par la commande:
mkd -Ctw H cpp.c cpp.h

Fichier cpp.h:

        // cpp.c:
        extern int cpp_ (FILE * pfdoc, FILE * pnfile);

Exemple de fichier pseudo code obtenu par la commande:
mkd -Ctnv O cpp.c cpp.txt

Ci-Dessous: Notez que la première ligne est dûe à l'option -v, les lignes sont numérotée (option -n), seul le texte est copié (option -t)
Le « code » d'extration est O comme Organigramme.

Fichier cpp.txt

(fichier cpp.c :)Options a=0 f=0 j=0 l=0 n=1 p=0 s=0 t=1 w=1
  138    While next character is not End Of File 
  142      If it is the first char then  c1=LF 
  144      Else c1 is the next char 
  146      If the char is New Line 
  147 	     then mark the followed position in memory (long int 'nl') 
  156        If the char is '\t' tabulation, then tab++ 
  158        Else if the char is '/' 
  160        Then: 
  164          If the char is followed by c2 = '*' or '/' and if options[0]=0 
  165 	       -- or if it is followed by user char 'code[]' 
  174          Then: 
  176            If c2 = '/' set the Boolean 'ligne' to true (=1) 
  178            Recognise the comment position 
  182            If option n is true then insert the line number 
  188            If option t is not true, 
  189            Then: 
  192              Positioning at the beginning line 
  195              Copy the line to comment in the doc file 
  203            Else: (option t) 
  206              Copy the tabulations as much as there is in the source file 
  212              Copy spaces up to comment and:
  219                If the line boolean 'ligne' is true (=1) 
  221                Then: 
  222 	               Copy the comment to End Of Line (EOL) or (EOF) 
  231                Else while does not find the char * followed by / : 
  232 	               Copy the comment 
  244                    If option n is true and char c1=NL 
  245 	                 Then: insert the line number following NL 
  271                BEGIN FULL_LINE *** Compil. option  
  272                If t option is false, 
  273 	             Then: 
  276                  Copy the comment to End Of Line or EOF
  277 	               -- including '\r' (CR/LF) under DOS 
  284                Else (option t true) 
  287                END FULL_LINE *** Compil. option  
  289                t is true by default if FULL_LINE is not denined at the 
  290 	             -- compilation 
  292                  Go to EOL without copying, except the carriage return 
  302                And next copy New Lines under this form: \n 
  307                And backward to NL 
  311              Else: (it is not a comment) 
  314                Back behind two characters 
  321    Return of a character back to avoid the End Of File EOF !

Exemple de fichiers de commandes Shell. Exemple pour générer les manuels et les mettre à jour

modifier

Le fichier Update_mkd_en.1.txt doit être imposé au format UTF-8 avec un éditeur comme gedit ou BlueFish, pour être traduisibles dans toutes les langues. Vérifiez votre syntaxe avec GmanEdit (Éditeur Gnome)^[3]
Note: Ceci est un exemple; Voir aussi: Installation du manuel français

#!/bin/bash
# File: install_manuals, 
# command syntax: sudo install_manuals
# only for update see install
clear # or cls on windows
echo "install or update mkd manual mkd (1)"

# Autoriser la lecture et l'écriture des fichiers « chmod 666 »:
# chmod: Attention crée une erreur si les fichiers n'existent pas.
chmod 666 mkd_en.1 mkd_en.1.gz
# Créer le fichier du manuel en anglais (mkd_en.1):
mkd -Ctw 1 Update_mkd_en.1.txt mkd_en.1
# Compresser le fichier au format du manuel unix:
gzip -f mkd_en.1
# Autoriser le fichier en lecture seule:
chmod 444 mkd_en.1.gz

chmod 666 mkd_fr.1 mkd_fr.1.gz
mkd -Ctw 1 Update_mkd_fr.1.txt mkd_fr.1
gzip -f mkd_fr.1
chmod 444 mkd_fr.1.gz

# Installer le manuel standard en anglais:
cp -f mkd_en.1.gz /usr/share/man/man1/mkd.1.gz ;

# Si le répertoire fr.UTF-8/man1 existe dans le répertoire des manuels, 
# Alors: copier le manuel français dans ce répertoire (UTF-8),
# Sinon: le copier dans le répertoire standard des manuels en français (ISO).
if [ -d "/usr/share/man/fr.UTF-8/man1" ]; \
	then sudo cp -f mkd_fr.1.gz /usr/share/man/fr.UTF-8/man1/mkd.1.gz ; \
	elif [ -d "/usr/share/man/fr/" ]; \
		then sudo cp -f mkd_fr.1.gz /usr/share/man/fr/man1/mkd.1.gz ; \
fi

Exemple de Makefile pour générer la documentation

modifier

Toutes les chemins des fichiers de l'application sont regroupés dans un fichier de projet dans l'ordre alphabétique.

Exemple : "ls -1 *.c > app.prj" qui va contenir le nom de tous les fichiers à examiner pour générer la documentation. Attention, ls -1 (chiffre un) et non -l (lettre 'l')

La ligne de commande "mkd -Cjt H app.prj app.h" génère le fichier d'entête de toutes les fonctions de l'application.

La ligne de commande "mkd -Cjt D app.prj app_functions.documentation" génère le fichier de la documentation des fonctions de l'application. Si le fichier est composé de sources en langages différents il faut remplacer l'impératif -C par -f (find) trouver le langage.

Exemple de lignes dans un Makefile.
Dans cet exemple le Makefile se trouve dans le répertoire des fichiers sources du projet.

# APP is any "macro". Warning: no space after the macro and the char '\'
APP = MyProgram

# Unconditional directive:
Create_header_and_functions-doc:
     # Warning: the first char is a tabulation and not spaces
     if [ -e "/usr/bin/mkd" ]; \
     then \
          # first : create or overwrite new project file \
          ls -1 *.cpp > $(APP).prj; \
          # create or overwrite header file \
          mkd -Ctw H $(APP).prj $(APP).h: \
          # create or overwrite functions documentation \
          mkd -Ctw D $(APP).prj $(APP).txt: \
          # option w : create or overwrite warnings documentation \
          mkd -Cwn w $(APP).prj $(APP).wars; \
     else \
          @echo "The mkd command is not found in bin directory"; \
     fi

Valeurs retournées et messages

modifier

mkd retourne la valeur 0 (zéro) en cas de succès, une valeur non nulle en cas d'erreur, et affiche:

syntaxe: mkd [-ABCFPSafjlnpstvw] codes chemin_source [chemin_cible]
   ou: mkd \? .Voir aussi le manuel: 'man mkd'

Ressources

modifier

Compilations avec:

gcc sous unix / linux, et bibliothèques standards.
Microsoft visual studio sous MS-Windows ( Une version est prête à l'emploi, compilée avec Microsoft Visual Studio 2010^[4] )

Fichiers

modifier

Traductions

modifier

Il existe des traductions sous unix / linux: Voir la page Traductions Internationales

Les langues anglais français sont intégrées dans la distribution 2012 et sont prévues pour les langues espagnol allemand italien
( Les fichiers de traduction .pot et .po sont à votre disposition ) ainsi que sur le site des mainteneurs.

Les manuels formatés nroff existent pour anglais allemand français et sont prévus pour espagnol italien
Voir aussi la documentation de gettext^[5] pour les traductions.

Notes

modifier

Il appartient aux programmeurs de veiller à refermer les commentaires, blocs et lignes, par les codes de fermeture appropriés dans les fichiers sources.

Attention: La fermeture d'un commentaire ligne est un retour chariot (NL, LF, CR/LF) selon les cas. Cette remarque implique un retour chariot en fin de commentaire ligne. Dans ce cas vous devez avoir une ligne vide à la fin du fichier source.

Jusqu'à la version 2012, mkd ne lit et ne décode pas de façon récursive les fichier inclus par '#include' dans les fichiers sources.

Droits de copie

modifier

Vous êtes libre de copier reproduire et distribuer le livre selon les termes de la Licence Wikipédia Creative Commons Paternité-Partage des Conditions Initiales à l'Identique 3.0 non transposé (CC-BY-SA 3.0) et licence de documentation libre européenne EUPL^[6] European Union Public Licence totalement compatible avec GNU

Droit de copie des fichiers sources

 DROIT DE COPIE DES FICHIERS SOURCES:
  © EELL, Éditeurs Européens de Logiciels Libres, EUPL 2007.
  Association à but non lucratif selon l'Article 11 de la convention
  européenne des droits de l'homme.
  Concédée sous licence EUPL, version 1.1 ou – dès leur approbation par la 
  Commission européenne - versions ultérieures de l’EUPL (la «Licence»).
  Vous ne pouvez utiliser la présente œuvre que conformément à la Licence.
  Vous pouvez obtenir une copie de la Licence à l’adresse suivante:
    https://joinup.ec.europa.eu/system/files/FR/EUPL%20v.1.1%20-%20Licence.pdf
  Sauf obligation légale ou contractuelle écrite, le logiciel distribué sous la
  Licence est distribué «en l’état», SANS GARANTIES OU CONDITIONS QUELLES
  QU’ELLES SOIENT, expresses ou implicites.
  Consultez la Licence pour les autorisations et les restrictions linguistiques
  spécifiques relevant de la Licence.
  Concernant la documentation : la Licence est totalement compatible avec la 
  licence de documentation libre GNU.

Bugs

modifier

Mise à jour des bugs.

Voir aussi

modifier

anglais Comparison of documentation generators

mkdcppw, mkdcpp en mode graphique.

Histoire

modifier

La commande mkd pour MS-DOS et nommée mkdoc pour Unix, a été créée au Centre d'Electronique de Montpellier (CEM) en 1986 pour générer la documentation logicielle des interfaces logiciel-matériel.
Il n’existait alors pas de logiciel connu pour générer cette documentation aux multiples langages (Assembleur, C, Fortran, Pascal, etc.) Les bibliothèques au format COFF ( Common Object File Format ) permettaient d'obtenir des bibliothèques communes.

mkdoc a peu évolué jusqu'en 2007. Il a été compilé pour MS-DOS, Unix BSD Sun, Linux RedHat, Windows 98, Windows 2000. Les commentaires des fichiers de l'application ainsi que les messages sont restés au format ASCII.

En 2007 le nom mkdoc est abandonné et retrouve son premier nom mkd avec la version 10.01 compilée avec Visual C++ au format de texte ISO-8859-1

En 2012 mkd 12.03 s'adapte au format de texte international UTF-8 pour son internationalisation.
Dans la foulée mkdcppw est écrit pour générer la documentation des fichiers de langages style C, (c++, php, etc.) en mode graphique (fenêtres).

Consultez également ces pages dans d’autres projets Wikimedia :

Article encyclopédique sur Wikipédia.

Notes et références

modifier

Notes Style de langage^[7]:

Définition de NL: New Line, fin de ligne.

Les styles impératifs (ABCFPSlp) s'excluent les uns des autres et ne permet pas la recherche de style par l'option '-f' (trouver le style)

Style A (Commentaires style Assembleur)

; Commentaire NL

Style B (Commentaires style Basic)

REM (après un marqueur ' : ' dans QBasic) Commentaire NL

' Commentaire NL

Styles C

/* Commentaire */ : C, C++, C#, Java, Javascript, PHP, VHDL 2008, ...

// Commentaire NL : C, C++, C#, CSS, D, Delphi, Java, Javascript, PHP, Scilab ...

Style F (Commentaires style Fortran 77) voir Style l pour le Fortran 90 et plus récents.

C ou c ou * Commentaire NL ; C,c ou * en première colonne.

Style P (Commentaires style Pascal):

(* Commentaire *) : AppleScript, Caml, Modula-2, Modula-3, Oberon, Pascal, ...

{ Commentaire } Delphi (Pascal objet)

Style S (Commentaires style Shell): Csh, Bash, sh, et autres shells, Makefile, Perl, PHP, Python, Ratfor, Ruby, Tcl, ...

# Commentaire NL

Option l (selon option compilée) ; décodage des lignes. Remplace une commande impérative (ABCFPS) et les trois extractions peuvent être associée simultanément. CD₁ et CD₂ en première colonne, CD₃ n'importe où dans la ligne.

avec CD₃ = ' ! ' Fortran 90

avec CD₁₂₃ = ' % ' Latex, Matlab, Postscript, Tex

avec CD₁₂₃ = ' # ' comme style S

Option p (selon option compilée) ; décodage des blocs:

Avec CD₄ = ' ( ' et CD₅ = ' ) ' : ( Commentaire )

avec CD₄ = CD₅ = ' " ' Chaînes de caractères " Commentaire "

avec CD₄ = CD₅ = ' ' ' Chaînes de caractères ' Commentaire '

avec CD₄ = ' < ' et CD₅ = ' > ' tous les tags

Remarques: Il est toujours possible d'inclure un style de commentaire dans le commentaire d'un autre style !

Références