↑ Retour au portail mkd
Dossier extractdoc du 04/12/2009 mis à jour 05/04/2012
A QUOI SERVENT MKD ET SES DÉRIVÉS ?
mkd pour consoles ou terminaux sert essentiellement à la maintenance des logiciels.
Avec la version mkd-12.03 l'application est internationalisée avec la prise en charge des caractères UTF-8
mkd génère automatiquement la documentation ou/et le manuel qui correspondent exactement aux fichiers actualisés.
mkd extrait les fichiers d'entête des fonctions mises à jour pour créer une documentation complète des fonctions d'un projet.
On se sert également de cette application pour l'installation des logiciels et dans le Makefile de compilation d'un projet.
mkdcpp est une version restreinte de mkd aux langages du style C , c++, php.
mkdasm est une version restreinte de mkd aux langages de type assembleur.
Ces deux dernières applications ont été réalisées pour effectuer des tests sur les modules cpp et asm.
Elles n'ont pas été prévues pour être utilisées comme mkd qui est la seule application réellement intéressante dans les projets.
mkdcppw : Version fenêtrée de mkdcpp, plus complète, prélude à mkdw version fenêtrée de mkd.
LE PROJET:
Ce projet reprend tout ou partie du projet MakeDoc (ou mkdoc ou encore mkd) de l'ex Centre d'Electronique de Montpellier, Université Montpellier II
Ce projet resté sans licence est maintenant repris sous licence libre européenne: European Union Public Licence (EUPL) par l' EELL
Ce logiciel doit évidemment, vu sa conception sous logiciel libre, rester libre de droit, gratuit, et ne peut en aucun cas faire l'objet d'une prise de brevet, d'une transaction ou d'une copie dans un but commercial, cependant le "copyleft" est autorisé et bienvenu.
Son but est d'être polyvalent, aussi universel que possible. Il doit permettre de générer de multiples documents à partir de commentaires précodés dans des fichiers de sources eux aussi multiples. (par exemple: des compilation avec des fichiers cpp + assembleur + fichiers texte etc.).
Les documents habituels sont:
Documentation sur l'architecture et la conception.
Documentation technique: d'exploitation, matérielle, programmeurs.
Documentation utilisateurs: bibliothèque logicielle, tutoriel.
Documentation de marketing.
L'extraction permet en un tour de main, d'assurer le contrôle rapide et la mise à jour de l'ensemble des documents précités.
LE NOM:
Le nom choisi est mkd par le fait qu'en 2010 les noms mkdoc, makeDoc et makeDocu ont, entre temps, été pris par d'autres logiciels.
Ce nom, pour les besoins pourra avoir des extensions comme:
- mkdasm pour décoder la documentation de style l'assembleur, équivalent à mkd -A, où mkd fait appel au module asm_
- mkdcpp ou mkdphp pour le décodage de style C++ ou PHP, équivalent à mkd -c mais plus explicite, où mkd fait appel au module cpp_ etc.
Les extensions asm, cpp, php, etc. liés à mkd permettent d'accéder directement aux modules asm_, cpp_, etc. (php est équivalent à cpp pour le décodage).
En début 2012 cette idée de créer des applications comme mkdphp et similaires est abandonnée.
Ces applications n'apportent rien de nouveau.
Une application fenêtrée de mkdcpp (mkdcppw) en cependant en cours d'évaluation.
LA COMPILATION, LES PLATEFORMES:
La compilation devra être validée sous WINDOWS et sous UNIX/LINUX, voire sous MAC pour les processeurs 32 et 64 bits. La version 16 bits devra être préservée et pourra être mise à jour.
L'épreuve finale d'intégration pourra se faire au travers de fichiers shells (.bat ou .bash).
On pourra multiplier le nombre des modules au gré de l'évolution des langages et le cas échéant on pourra créer des libraires si le nombre des modules devient trop importants (.dll sous Windows ou .so sous UNIX/LINUX). Dans ce cas il faudra modifier les paramètres de transmission aux modules afin de récupérer les options. (Les variables d'options sont globales dans les versions actuelles)
Détails concernant les anciennes versions (antérieures à 3.22):
Contrairement aux versions précédentes, qui incluaient chaque fichier dans une seule compilation, tous les modules seront compilés séparéments et pourront faire l'objet d'épreuves unitaires de modules ou d'épreuves spécifiques lors de l'intégration.
Les compilations avec des options particulières des versions anciennes seront reprises dans des modules particuliers (anciennes compilations avec les options ligne et page).
Exemple mkdstring pour extraire les chaines de caractères, mkdpostscript pour extraire les commentaires postscript etc. feront l'objet de nouveaux modules et
on introduira un nouveau code de commande pour remplacer l'option de compilation FULL_LINE (si nécessaire).
Lignes de commande console du programme exécutable:
Ligne de commandes traditionnelle:
mkd [--Options] [-5 caractères à décoder] fichier_source [fichier_destinataire]
Lignes de commandes spéciales:
mkdxx..xx [--Options] [-5 caractères max à décoder] fichier_source [fichier_destinataire]
où l'option 'f' n'a pas de sens.
Par défaut le fichier_destinataire prendra le nom du fichier source suivi de l'extension .txt
Options: a, f, j, n, s, t, v, w, langage à décoder
a, f, j, v, w sont des options particulières au module de commande (main mkd)
n, s, t sont des options destinées aux modules (asm_, cpp_, fortran_, etc.)
a, ajouter à un fichier destinataire (append)
f, trouver le style de commentaire à décoder en fonction de son extension (find), pourra être
affiné par un recherche à l'intérieur des fichiers.
j, le fichier source est un fichier de projet, se combine avec l'optiopn 'f' s'il composé de
fichiers sources différents.
n, fait précéder le commentaire du numéro de ligne sur les premières colonnes.
s, ajouter les commentaires décodés à l'écran. (Permet parfois des ajouts SHELL avec les
redirections > et >>).
t, ne copie que le texte. (copy text only) contrarie certaines options contrariantes comme le
mode bavard dans l'écriture de la documentation.
v, mode bavard (verbose)
w, crée ou recrée le fichier destinataire de même nom (overwrite)
langage à décoder:
exemples : C pour style C, (C++ ou PHP), F pour style FORTRAN, P pour style PASCAL, etc.
Le style des langages compilés devra être précisé par la commande mkd --help --? ou dans la
documentation utilisateur mkd.1 sous UNIX/LINUX
Caractères à décoder:
Tous caractères alphanumériques et caractères spéciaux ** (5 caractères maximum)
LE DROIT DE COPIE:
© EELL, Éditeurs Européens de Logiciels Libres, 20074
Contact: JPL EELL
Concédée sous licence EUPL, version 1.1 ou – dès leur approbation par la Commission européenne - versions ultérieures de l’EUPL (la «Licence»).
Vous ne pouvez utiliser la présente œuvre que conformément à la Licence.
Vous pouvez obtenir une copie de la Licence à l’adresse suivante:
http://ec.europa.eu/idabc/eupl5 ou sur ce site en version française Licence EUPL V1.1
Sauf obligation légale ou contractuelle écrite, le logiciel distribué sous la Licence est distribué «en l’état»,
SANS GARANTIES OU CONDITIONS QUELLES QU’ELLES SOIENT, expresses ou implicites.
Consultez la Licence pour les autorisations et les restrictions linguistiques spécifiques relevant de la Licence.==ÉVOLUTION DU PROJET:==
Les bases précisées dans ce document sont susceptibles d'évoluer en fonction des besoins des programmeurs ou autres professions intéressées.
Dans un premier temps on reprendra les modules définis dans les versions précédentes.
En mars 2010 le module cpp_ a été ajouté dans la version 10.03 pour extraire les documents de style C++, PHP, etc.
Les fichiers documentaires et de gestion des erreurs pour les différentes langues devront, si possible, être rapidement proposés au moins en français et anglais, puis dans les différentes langues européennes, sans oublier les autres langues évidemment.
Jusqu'en 2012 nous nous contentions des caractères ASCII étendus. Les caractères entrés en programmation (au clavier) ne nous ont pas obligés à reconcevoir fonamentalement les différents modules.
Les documents, aujourd'hui peuvent être écrits dans des langues très différentes et les codes utf8 ne suffisent pas. Il faut envisager de revoir nos souces. Cette question est d'actualité !
Exemple de manuel généré par mkd
Dérouler
MKD(1) (fr)
MKD(1) MKD(1)
NAME
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électionnes (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:
Restreind l'extraction des commentaires a 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 a 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.
-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 Cshell :
mkd -Ct F manual mkd.1 | gzip -f mkd.1.gz
(Produit un manuel UNIX en francais. 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 debutants 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 commencant 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
fichiers source sont décrits dans le fichier projet.) f:trouver
le style de langage, j:le fichier source est un fichier projet
qui contient la liste des fichiers a 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.
AUTHOR
JP LOUYOT, Clara JIMENEZ
http://edeulo.free.fr/wiki/index.php/Portail:mkd
NOTES
Cette version 12.03.0 ne lit et ne décode pas les fichier inclus par
'#include' dans les sources.
BUGS
Bugs Report: http://edeulo.free.fr/phpBB3/viewforum.php?f=14
29 Mars 2012 MKD(1)
Dérouler
MKD(1) (en)
MKD(1) MKD(1)
NAME
mkd - make documentation. Extract coded informations from programs
sources and product specific documentation.
SYNOPSIS
mkd [-ABCFPSafjlpstw] char_codes path_source [path_target]
DESCRIPTION
mkd
Selected comments (or all comments) are extracted from programs
sources and product specific documentation to target file. Usual
target files are Organigrams, or Structure of programs, or
comments for Programmers, Warnings and Tests points .... Coded
informations are respectively 'O', 'S', 'P', 'www', ant 'T' just
after the comment character.
char_codes
All ASCII. The comment are extracted if the comment begin with
this character. With two star mkd extract all comments.
path_source
Path source file (or project file: option j ).
path_target
Path target file. Default, path target is idendical to source
file with extension ´.doc´ .
OPTIONS
Uppercase options:
restrict comments to one specific language:
-A extract Assembler style comments ( ; to end of line )
-B Basic style (REM or ' -> end of line)
-C C style ( / * -> * / )
-F Fortran style (c,C or * -> end of line)
-P Pascal style ( { -> } )
-S Shell or ratfor style ( # -> end of line)
Lowercase options:
-a append to current target file.
-f find source file language. (useful with project file)
-j used if source file is a project file.
-l lines (extract lines delimited by CD1 or CD2 in first colomn or
CD3 in line, and next New-Line. CD1, CD2, CD3 are compilable
options in version.h from mkd distribution)
-p page (extract text delimited by CD4 and CD5 -begin with CD4 and
end with CD5-. CD4, CD5 are compilable options in version.h from
mkd distribution)
-s add to screen. (verbose)
-t text (copy only the comment).
-w overwrite the current target file.
EXAMPLES
with Cshell command:
mkd -Ct F manual mkd.1 | gzip -f mkd.1.gz
Product UNIX manual for french users.
mkd -Ct M manual mkd.1 | gzip -f mkd.1.gz
Product UNIX manual.
mkd -Csl '*Sied' mkd3.c '*.verif_struct'
Product documentation with structure of program, includes,
defines, ifdef else and endif compile options, to verify
structure of program. (with compilable options CD1='#' or
CD2='#' in version.h from mkd distribution).
mkd -jfsl '*OHie' mkd_docu.prj mkd.org
Product organigram. Comment begin with *,O,H, and sources files
are itemize in project file. (with compilable options CD1='#'
or CD2='#').
mkd -l '*ide' mkd3.c '*.id_ei'
(with compilable options CD1='#' or CD2='#').
mkd -pj '**' mkd_docu.prj mkd.strings
Extract strings from program. (messages are printed to stdout).
(sources files are itemize in project file, and with compilable
options CD4=CD5=´\"´).
mkd (without argument)
Cause any error and syntax are transmit to terminal with
caracters compiled to use options l and p.
AUTHOR
JP LOUYOT, Clara JIMENEZ.
http://edeulo.free.fr/wiki/index.php/Portail:mkd
NOTES
No match, for read and decode include files from sources files in this
Release 12.03.0
BUGS
Bugs Report: http://edeulo.free.fr/phpBB3/viewforum.php?f=14
29 March 2012 MKD(1)
Exemple de pseudocode généré par mkd
Dérouler
pseudocode cpp.c
Commande mkd -nts O cpp.c pseudo_cpp.txt
(Il manque un pseudociode entre les lignes 216 et 227 qui nécessite vérification et correction)
127 tant que pas fin de fichier source
131 si début de texte faire c1=LF
133 sinon prendre pour c1 le char pointe
135 si le char est NL repérer la position qui suit NL, dans nl
144 si le char est '\t' incrémenter tab
146 sinon si le char est '/'
148 alors:
152 si suivi par c2 = '*' ou '/' et si options[0]=0 ou si suivi par char code utilisateur
161 alors:
163 si c2 = '/' positionner le booléen ligne à vrai (=1)
165 repérer la position commentaire
169 si option n insérer le numéro de ligne
175 si pas option t
178 se positionner en début de ligne
181 copier la ligne jusqu'au commentaire, dans le fichier doc
189 sinon: (option t)
192 copier des tab autant qu'il y en a dans le source
198 copier des blancs jusqu'à la position commentaire
205 puis si booléen ligne est vrai (=1)
207 alors : copier le commentaire jusqu'en fin de ligne ou End Of File (EOF)
216 sinon : tq ne rencontre pas * suivi de /, copier le commentaire
227 si option n et char=NL insérer le numéro de la ligne qui suit NL
252 Opt. compil. *** FULL_LINE ***
253 si pas option t
256 copier les chars jusqu'en fin de ligne (ou EOF) y compris '\r' sous DOS
263 sinon (option t)
265 Opt. compil. end *** FULL_LINE ***
267 aller au bout de la ligne sans copier, sauf les 'retour chariot'
277 puis envoyer les NL sous forme \n
282 revenir sur NL
286 sinon: (pas de commentaire
289 revenir en arrière de 2 caractères
293 fin si char = '/'
295 fin si pas NL
297 fin tq !EOF
299 Fin
