Utilisateur:Goelette Cardabela/Bac à sable/mkd (Extracteur de documents)
[[Fichier:|250px|center|middle]]
Paragraphe court d'introduction au livre.
Pour lire ce livre, commencez par ... Courte introduction sur page de garde.
Sommaire
[modifier le wikicode]Utilisateur:Goelette Cardabela/Bac à sable/mkd (Extracteur de documents)/Sommaire
Voir aussi
[modifier le wikicode]- ...liens vers d'autres livres...
| ||
|
| ||
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
[modifier | modifier le wikicode]mkd [-ABCFPSafjlnpstvw] codes chemin_source [chemin_cible]
Disponibilité
[modifier | modifier le wikicode]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
[modifier | modifier le wikicode]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:
- 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
[modifier | modifier le wikicode]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
[modifier | modifier le wikicode]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
[modifier | modifier le wikicode]Fichiers sources
[modifier | modifier le wikicode]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
[modifier | modifier le wikicode]- 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
[modifier | modifier le wikicode]#!/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
[modifier | modifier le wikicode]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
[modifier | modifier le wikicode]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
[modifier | modifier le wikicode]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
[modifier | modifier le wikicode]Traductions
[modifier | modifier le wikicode]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
[modifier | modifier le wikicode]- 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
[modifier | modifier le wikicode]© EELL, Éditeurs Européens de Logiciels Libres, EUPL 2007.
- 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
[modifier | modifier le wikicode]anglais Comparison of documentation generators mkdcppw, mkdcpp en mode graphique.
Histoire
[modifier | modifier le wikicode]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).
