Mkd (Extracteur de documents)
Introduction.
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.
Disponibilité.
Les paquets Debian peuvent être convertis pour d'autres systèmes linux avec Alien
Syntaxe.
mkd [-ABCFPSafjlnpstvw] codes chemin_source [chemin_cible]
Description.
codice_1
codice_2
codice_3
codice_4
Options.
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.
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:
 grep -n -e --[Code] <Fichier_source> [> Fichier cible]
Ici, l'option -p permet d'extraire toutes les chaînes de caractères avec les codes '**'
Exemples.
Exemple de fichiers sources pour générer la documentation.
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.
 // cpp.c:
 extern int cpp_ (FILE * pfdoc, FILE * pnfile);
(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".
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)"Note: Ceci est un exemple; Voir aussi: Installation du manuel
clear # or cls on windows
echo "install or update mkd manual mkd (1)"
chmod 666 mkd_en.1 mkd_en.1.gz
mkd -Ctw 1 Update_mkd_en.1.txt mkd_en.1
gzip -f mkd_en.1
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
cp -f mkd_en.1.gz /usr/share/man/man1/mkd.1.gz ;
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.
Toutes les chemins des fichiers de l'application sont regroupés dans un fichier de projet dans l'ordre alphabétique. 
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 = MyProgram
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.
mkd retourne la valeur 0 (zéro) en cas de succès, une valeur non nulle en cas d'erreur, et affiche:
Ressources.
Compilations avec:
Fichiers.
Traductions.
Il existe des traductions sous unix / linux: Voir la page Traductions Internationales
Droits de copie.
© EELL, Éditeurs Européens de Logiciels Libres, EUPL 2007.
 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.
Mise à jour des bugs.
Voir aussi.
 Comparison of documentation generators
mkdcppw, mkdcpp en mode graphique.
Histoire.
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)."
Notes et références.
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)