Utilisateur:goelette.Cardabela/Bac à sable/Mkd (Commande UNIX)
mkd est une commande Unix permettant d'extraire des lignes de commentaires pré-codés afin de générer la documentation logicielle d'après le standard ISO[1]. mkd est l'abréviation de make documentation (termes anglais signifiant « faire la documentation »). Cette commande était, à son origine, connue sous le nom mkdoc
(make documentation).[2]
Cette commande n'est pas intégrée dans les distributions standard d'UNIX / LINUX
Syntaxe de la ligne de commande
[modifier | modifier le code]La commande suivante dans un terminal ou la konsole :
- nadine@Ordinateur-de-nadine-linux:~$ mkd \?
affiche la syntaxe :
syntaxe: mkd [-ABCFPSafjlnpstvw] codes chemin_source [chemin_cible]
ou: mkd \? .Voir aussi le manuel: 'man mkd'
--> options:
-A décode uniquement les commentaires de style Assembleur
-B style Basic
-C style C: C, c++, php ...
-F style Fortran
-P style Pascal
-S style Shell
-a ajoute au fichier cible
-f:
trouve le langage ( .s .S .c .h .i .f .F .r .p .sh .csh )
-j précise que le fichier source est un fichier de projet.
-l et -p: ligne; (compil.: % ou - en première colonne ou # dans la ligne)
page: (compil.: commence avec " et se termine avec ")
-n insère un numéro de ligne
-s copie dans le fichier cible et à l'écran
-t ne copie que le commentaire
-v mode bavard
-w écrase le fichier cible (par défaut cette option est invalidée)
--> codes: tout caractère ASCII (5 caractères au maximum)
exemple de codes = UM,ou \*OPTw, ou '* HOS', ou '**' pour tout
--> chemin_source: fichier source (option -j: si le fichier source est un fichier de projet)
--> chemin_cible: chemin du fichier cible
Exemple: mkd -Csnv '*S' fichier.c \*.vérif_structure
.Sortie 2
Exemple d'utilisation
[modifier | modifier le code]Fichiers de fonctions
[modifier | modifier le code]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 (header) et son usage.
Exemple pour la fonction cpp_ : dans le fichier cpp_.c
/*D
fonction cpp_
-----------------------------------------------------------------------------
ACTION:
La fonction cpp_ lit le fichier source (pnfile) qui est transmis en
paramètre et décode les lignes de commentaires précodés dans le style C++
puis les transcrit dans le fichier de destination (pfdoc) lorsque le code
correspond à un des codes externes à la fonction;
Les variables globales sont les codes et les options.
Les codes, tabeau de 5 caractères:
extern char codes[];
ils doivent être définis dans le programme d'appel:
char codes[5] = {0,0,0,0,0};
Les options, n,s,t,v.
extern unsigned char n,s,t,v;
elles doivent définies dans le programme d'appel:
unsigned char n=0,s=0,t=0,v=0;
Avec les options :
n: La transcription est précédée du numéro de ligne. Ceci permet
d'atteindre facilement la ligne commentée.
t: Avec l'option t seul le texte commenté est recopié.
Sans l'option t le commentaire est entièrement recopié.
Cette option t permet donc de générer des documents directement
exploitables ou publiables.
s: ajoute le commentaire à l'écran et permet les redirections > , >> ,
ou || etc.
v: mode bavard
Remarque :
Si la détection d'un commentaire à transcrire commence par le caractère '/'
suivi de '*' il sera transcrit jusqu'à rencontrer le caractère '*' suivi
de '/', quel que soit le commentaire ligne inclus dans ce commentaire.
Si la détection d'un commentaire commence par deux caractères '/', le
commentaire sera copié jusqu'au prochain retour à la ligne (NL) ou fin de
fichier (EOF).
Ces dispositions facilitent la génération automatique des fichiers
d'entête fichier.h ou .hpp etc.
SYNTAXE:
#include "version.h"
#include "cpp_.h"
int cpp_(FILE *pfdoc, FILE *pnfile);
PORTABILITE:
Microsoft Visual studio sous Windows : x86(Win32) x64(Win32 et WIN64)
gcc sous Unix/Linux.
DESCRIPTION:
cpp_ fonction
FILE* pfdoc: pointeur sur le fichier de destination ouvert par le
programme appelant.
FILE* pnfile: pointeur sur le fichier source ouvert par le programme
appelant
VALEUR RETOURNEE:
Retourne 0 en cas de succès.
DROIT DE COPIE: (précisé dans version.h) :
*/
/*H
// cpp_.c:
extern int cpp_ (FILE *pfdoc, FILE *pnfile);
*/
Fichiers de commande et Makefile
[modifier | modifier le code]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.
Exemple de lignes dans un Makefile.
Dans cet exemple le Makefile se trouve dans le répertoire des fichiers sources du projet.
APP = MyProgram # This is any "macro" Create_header_and_functions-doc: # here, this is any unconditional directive. if [ -e "/usr/bin/mkd" ]; \ # Warning: the first char is a tabulation and not spaces then \ ls -1 *.cpp > $APP.prj; \ # first create or overwrite new project file mkd -Ctw H $APP.prj $APP.h: \ # create or overwrite header file mkd -Ctw D $APP.prj $APP.txt: \ # create or overwrite functions documentation mkd -Cwn w $APP.prj $APP.wars; \# create or overwrite warnind documentation for programmers else \ @echo "The mkd command is not installed in bin directory"; \ fi
Manuels
[modifier | modifier le code]Mise à jour des manuels
[modifier | modifier le code][(en + de + fr) Mise à jour des manuels (page consultée le 21/12/2012)]
Manuel en français
[modifier | modifier le code]Manuel UNIX (Commande détaillée) MKD(1)
NOM
mkd - make documentation. Extrait des informations codées dans les
programmes sources, et produit une documentation spécifique.
SYNOPSIS
mkd [-ABCFPSafjlpstw] codes chemin_source [chemin_cible]
DESCRIPTION
mkd Des commentaires sélectionnés (ou tous les commentaires) sont
extraits des programmes sources: 'chemin_source', et sont copiés
dans un fichier documentaire: 'chemin_cible', afin de produire
une documentation spécifique . Habituellement les fichiers
documentaires sont des Organigrammes, des Structures de
programme, des commentaires pour Programmeurs, des points de
Test et 'warnings' .... Les codes de sélection peuvent être
respectivement 'O', 'S', 'P', 'T' et 'www' juste après le
caractère début de commentaire.
codes Les commentaires commençant par ces caractères sont extraits du
programme source et sont ajoutés au fichier documentaire. Tous
les caractères ASCII peuvent servir a coder les commentaires,
toutefois on utilise habituellement des caractères majuscules,
sauf w pour 'warning'. Avec deux étoiles en paramètre codes, mkd
extrait tous les commentaires. (Voir aussi option t et les
exemples).
chemin_source
Chemin du fichier source (ou fichier projet: option j)
chemin_cible
Chemin du fichier documentaire. Par défaut chemin_cible est une
copie de chemin_source auquel on remplace le suffixe par le
suffixe ´.doc´.
OPTIONS
Options en majuscules:
Restreint 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)
options en minuscules:
-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 verbose) Duplique les commentaires extraits sur la
sortie standard.
-t (text) Ne copie que le commentaire.
-w (overwrite) Réécrit le fichier documentaire.
EXEMPLES
avec une commande C Shell :
(Commande au terminal ou à la konsole)
mkd -Ct F manual mkd.1 | gzip -f mkd.1.gz
(Produit un manuel UNIX en français. au format UTF-8 depuis la
version 12.03) C: pour décoder le fichier en langage C, s:avec
visualisation à l´ écran, t:ne copier que le commentaire,
F:sélectionner les commentaires débutants par F.
mkd -Ct M manual mkd.1 | gzip -f mkd.1.gz
(Produit un manuel UNIX standard en anglais au format UTF-8
depuis la version 12.03)
mkd -Csl '*Sied' mkd3.c '*.verif_struct'
(avec les options de compilation CD1 ou CD2 = '#', produit une
documentation avec la structure du programme, avec les: include,
define, ifdef, else, et endif, des options de compilations afin
de vérifier la structure du programme.) C:décoder les
commentaires style C, s:vérifier à l'écran, l:décoder egalement
des lignes commençant par les caractères CD1 ou CD2 ou CD3 et
suivis des char_codes:*Sied.
mkd -jfsl '*OHie' mkd_docu.prj mkd.org
(avec les options de compilation CD1 ou CD2 = '#', produit un
organigramme. Les commentaires commencent par *,O,H, et les
chemins d'accès aux fichiers source sont les constituants du
fichier projet. Les options : 'f' trouve le style du langage,
'j' dit que le fichier source est un fichier projet (liste des
fichiers à documenter).
mkd -l '*ide' mkd3.c '*.id_ei'
(avec les options de compilation CD1='#' ou CD2='#', décode les
#includes, #define, #ifdef, #else, #endif des options de
compilation en C ).
mkd -pj '**' mkd_docu.prj mkd.strings
(avec les options de compilation CD4=CD5=´\"´, extrait les
chaînes de caractères du programme. (les commentaires sont
transmis a la sortie standard).
mkd (sans argument)
Génère une erreur et envoie la syntaxe au terminal avec les
caractères compilés pour les options l et p.
SIEHE AUCH
mkdcppw(1)
HISTOIRE
1986 - mkd pour DOS, et mkdoc pour UNIX, sont écrits au format ASCII
par Jean-Paul Louyot pour le laboratoire 'CEM' de l'université de
Montpellier (France).
1991 - mkdoc 3.12 pour PC et UNIX (Sun)
1995 - mkdoc 3.22 pour Linux Red-Hat
2004 - mkdoc 4 pour SUN-SPARC, HP-UX, RedHat, Windows 98, Windows 2000
2007 - 2012 - de mkdoc R7.01 à mkd R12.01 sont au format ISO-8859-1.
Le nom 'mkdoc' est abandonné avec la version 10.01 compilée avec
Visual C++ 2010
2012 - mkd 12.03 adapté au format UTF-8 pour son internationalisation.
Dans la foulée mkdcppw est écrit pour langages C, c++ et php en mode
graphique avec gcc et 'gtkmm' (fenêtres).
AUTEURS
Mise à jour : Clara JIMENEZ
Traductions : Alizée (Catalan, Espagnol), Luca (Italien).
http://edeulo.free.fr/wiki/index.php/Projet_mkd/Compilations_UNIX-LINUX
NOTES
Cette version 12.03.0 ne lit et ne décode pas les fichier inclus par
'#include' dans les sources.
BUGS
Report d'erreurs (Bugs report) : http://edeulo.free.fr/phpBB3/index.php
Générateur de documents mkd 3 Décembre 2012 MKD(1)
|
Systèmes d'exploitation
[modifier | modifier le code]Debian et Ubuntu
[modifier | modifier le code]La maintenance des applications mkd est assurée et distribuée sous forme de paquets pour Linux Ubuntu et systèmes à base Debian[3].
Voir aussi le chapitre Liens Externes ci-dessous
Fedora et Red Hat
[modifier | modifier le code]L'application a été intensément utilisée sous Red_Hat, SUN-Sparc, HP-UX jusqu'aux années 2000 au format de caractères ASCII, puis au format ISO 8859-1; L'emplacement des répertoires différait des emplacements actuels
mkd est compilable tel quel pour Fedora. (Format de caractères UTF-8)
Les paquets RPM ne sont pas pris en charge par les mainteneurs.
Autres distributions LINUX
[modifier | modifier le code]De nombreuses Distributions Linux sont disponibles. mkd est, à priori, compatible avec tous les systèmes Unix et Linux, parfois au chemin près des répertoires des documentations et des manuels.
DOS/Windows
[modifier | modifier le code]mkd pour MS-Windows est utilisé en ligne de commande dans un terminal.
Voir aussi
[modifier | modifier le code](en) Comparison of documentation generators
Liens externes
[modifier | modifier le code]- ISO/IEC 26514:2008 preview
- Le projet mkd Présentation du projet mkd et ses dérivés mkd* sur le site des mainteneurs.
- Téléchargements pour systèmes debian et logithèque ubuntu
Disponibilité des sources : Sources pour autres systèmes (UNIX, LINUX, WINDOWS)
References
[modifier | modifier le code]- ISO/IEC 26514:2008
- (1986-2001) Informatique - Centre d'Electronique et de Micro-électronique de Montpellier, Université Montpellier II, 34000 Montpellier France
www.cem2.univ-montp2.fr. See new laboratory IES - paquets pour ubuntu