Projet mkd
De Wiki EELL.
Dossier extractdoc 04/12/2009
Sommaire |
A QUOI SERT MKD ET SES DÉRIVÉS ?
mkd pour consoles ou terminaux sert essentiellement à l'installation de logiciels.
mkd génère automatiquement la documentation ou/et le manuel qui correspondent exactement aux fichiers actualisés du logiciel.
On se sert également de cette application dans les 'Makefile' de la compilation des modules d'un projet : mkd extrait les fichiers d'entête des fonctions mises à jour.
mkdcpp est une version restreinte aux langages du style c++, C , c++, php.
mkdasm est une version restreinte 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.
Le fenêtrage est à la mode. Des versions fenêtrées, non intégrables aux fichiers d'installation 'install' et 'Makefile' sont en cours d'écriture à titre expérimental. En janvier 2012 Clara nous a proposé l'application expérimentale mkdcppw qui est la version fenêtrée de mkdcpp.
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.
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).
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)
É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.
