# 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

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
    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

mkd [-ABCFPSafjlnpstvw] codes chemin_source [chemin_cible]

## Description

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:
   * 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

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

### 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.
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)
    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
### 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

### Exemple de fichiers cibles obtenus

* Exemple de fichier d'entête obtenu par la commande: mkd -Ctw H cpp.c cpp.h
    Fichier cpp.h:
* 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

### 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 français

### 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.
    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.

## 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:
* 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 )

## Fichiers
### Traductions

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 pour les traductions.

## Notes

* 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

© EELL, Éditeurs Européens de Logiciels Libres, EUPL 2007.
    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 European Union Public Licence totalement compatible avec GNU

## Bugs

Mise à jour des bugs.

## Voir aussi

anglais 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).
Consultez également ces pages dans d’autres projets Wikimedia :

## Notes et références

* Notes Style de langage:
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
* ↑ ISO/IEC 26514:2008
* ↑ ISO/IEC 26514:2008 prévisualisation
* ↑ GmanEdit (Gnome manpage editor)
* ↑ Package redistribuable Visual C++ 2010 (x86)
* ↑ gettext
* ↑ Licence Publique de l'Union Européenne (fichier pdf)
* ↑ https://fr.wikipedia.org/wiki/Commentaire_(informatique)