Mkd (Commande unix)
De Wiki EELL.
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
Sommaire |
Syntaxe de la ligne de commande
La commande suivante dans un terminal ou la konsole :
- nadine@Ordinateur-de-nadine-linux:~$ mkd \?
affiche la syntaxe : <source lang="text"> 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 </source>
Exemple d'utilisation
Fichiers de fonctions
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
/*P
File cpp_.c
Programmers directives (in V cycle)
Last Date und Programmer name
*/
/*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);
*/
int cpp_ (FILE * pfdoc, FILE * pnfile)
{ //S Function Begin
... // Function Lines
} //S Function End
Fichiers de commande et Makefile
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
Mise à jour des traductions
(en) (de) (fr)[3]
(Voir aussi les liens externes)
Systèmes d'exploitation
Debian et Ubuntu
La maintenance des applications mkd est assurée et distribuée sous forme de paquets pour Linux Ubuntu et systèmes à base Debian[4].
Voir aussi le chapitre Liens Externes ci-dessous
Fedora et Red Hat
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
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
mkd pour MS-Windows est utilisé en ligne de commande dans un terminal.
Voir aussi
(en) Comparison of documentation generators
Liens
Liens externes
Liens utiles
Autres langues pour mkd sur wikipedia
wikipedia:de:Mkd (Unix-Befehl)
wikipedia:en:Mkd (Unix command)
wikipedia:fr:Mkd (Commande unix)
Liens internes
Liens utiles
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)
Autres langues pour mkd en interne
Présentation de mkd:
- (de) Mkd (Unix-Befehl)
- (en) Mkd (Unix command)
- (es) Votre aide serait la bienvenue
- (fr) Mkd (Commande unix)
- (it) Votre aide serait la bienvenue
Aide mkd:
- (de) Votre aide serait la bienvenue
- (en) Projet mkd/mkd/Help
- (es) Votre aide serait la bienvenue
- (fr) Projet mkd/mkd/Aide
- (it) Votre aide serait la bienvenue
Mise à jour des manuels:
- (de) Unix Handbuch(1)
- (en) Unix Manual(1)
- (es) Votre aide serait la bienvenue
- (fr) Manuel(1) Unix
- (it) Votre aide serait la bienvenue
References
- ↑ 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 - ↑ (de) (en) (fr) Mises à jour des traductions
- ↑ paquets pour ubuntu
