Utilisateur:Goelette Cardabela/Bac à sable/mkd (Extracteur de documents)

[[Fichier:|250px|center|middle]]

Goelette Cardabela

Paragraphe court d'introduction au livre.

Avancement

Ébauche

Classement CDU

[[Wikilivres:CDU/|]]

Une version imprimable du livre « Goelette Cardabela/Bac à sable » est disponible. (voir/modifier)

Une version PDF de ce livre est demandée.

Pour lire ce livre, commencez par ... Courte introduction sur page de garde.

Sommaire

Utilisateur:Goelette Cardabela/Bac à sable/mkd (Extracteur de documents)/Sommaire

Voir aussi

...liens vers d'autres livres...

En travaux

Cette page est en travaux. Tant que cet avis n'aura pas disparu, veuillez en considérer le plan et le contenu encore incomplets, temporaires et sujets à caution. Si vous souhaitez participer, il vous est recommandé de consulter sa page de discussion au préalable, où des informations peuvent être données sur l'avancement des travaux.

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

mkd est une commande très simple destinée à extraire les documents pour la maintenance et l'exploitation des logiciels.

L'exécutable mkd est utilisé en lignes de commandes et dans les fichiers de compilation de logiciels, les Makefile, qui permettent de mettre à jour la documentation en même temps que la compilation ^[1]^[2]. Les documents sont ainsi normalement toujours à jour.

Très simple et très pratique d'utilisation mkd peut être proposé dans les travaux pratiques de l'informatique pour l'étude du cycle en V.

Cette application a été développée pour UNIX et MS-DOS

Une application indirecte mkdcppw^[3], fenêtrée, a été réalisée sous linux pour les langages de style C (C++, php, etc). On pourrait trouver cette application moins pratique à utiliser; les arguments positifs sont qu'il n'est pas nécessaire d'utiliser la ligne de commandes et les documents sont directement imprimables avec les balises de formatage comme <b>_</b> pour le texte gras, <u>_</u> pour souligner etc.

Syntaxe

mkd [-ABCFPSafjlnpstvw] codes chemin_source [chemin_cible]

Disponibilité

Les sources compilables sont disponibles pour Windows, Unix, Linux.

Les binaires sont disponibles pour:

Windows équipés de processeurs 32 et 64 bits.

Unix/Linux équipés de processeurs 32 bits x86 (i386), et 64 bits (amd64).

Les paquets d'installation sont disponibles pour les sytèmes à base Debian, Ubuntu^[4].

Description

mkd

Des commentaires sélectionnés (ou tous les commentaires) 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 codes (Programmation en 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 quasiment toutes les 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.

codes

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

Options

Voir Shell Interface système

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                    (  / *    ->      * /    )
 
       -F     style Fortran              (c,C ou * -> fin de ligne)
 
       -P     style Pascal               (   {     ->       }     )
 
       -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.
 
       -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.
 
       -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 votre version à 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 ? qu'on extrait avec plutôt avec cat et grep

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

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

Exemples

Fichiers sources

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

Dans le fichier de la fonction on précise sa syntaxe d'utilisation dans 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 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++

       /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

Fichiers cibles

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 !

Fichiers de commandes Shell

#!/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 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.c++ 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.c++ 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

Makefiles

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

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

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

Fichiers

Traductions

Il existe des traductions sous unix / linux: Voir Traductions

Pour l'application anglais français et sont prévus pour espagnol allemand italien [[Mkd_(Extracteur_de_documents)/traductions|( Les fichiers .pot et .po sont à votre disposition )]] sur le site des mainteneurs avec un aperçu sur la page des traductions.
Les manuels formatés nroff existent pour anglais allemand français et sont prévus pour espagnol italien

Bugs

Laisser une ligne vide à la fin des documents afin qu'une ligne de commentaire ne se termine pas par le caractère 'EOF'.

Pas de bug connu depuis la version 12.05 sous unix / linux.

Les bugs précédents, dans les messages, étaient dûs aux traductions et au passage du format ISO au format UTF-8.

Pas de bug connu dans la version 10 sous windows.

Droits de copie

Vous êtes libre de copier reproduire et distribuer l'applications 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^[5] European Union Public Licence totalement compatible avec GNU

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 :

Article encyclopédique sur Wikipédia.

Notes et références

[1] ISO/IEC 26514:2008

[2] ISO/IEC 26514:2008 prévisualisation

[3] [1]

[4] quets pour ubuntu

[5] Licence Publique de l'Union Européenne (fichier pdf)

[1]

[2]

[3]

[4]

[5]