Mkd (Extracteur de documents)/La commande mkd avec exercices
avec exercices
Une version à jour et éditable de ce livre est disponible sur Wikilivres,
une bibliothèque de livres pédagogiques, à l'URL :
https://fr.wikibooks.org/wiki/Mkd_(Extracteur_de_documents)
Introduction
- mkd est une commande Unix / Linux utilisée dans les fichiers de commande des mises à jour des logiciels, les Makefile.
- Afin de maintenir la documentation à jour en même temps que la compilation d'une nouvelle version d'un logiciel: dès qu'un fichier du projet logiciel est modifié, la documentation doit être revue et mise à jour au sein même du fichier modifié.
- L'utilisation de mkd n'est pas restrictive au Makefile. La commande est utilisable dès qu'un texte est commenté. (Tous les fichiers de programme compilés ou interprétés, et aussi : Latex, Matlab, Postscript, Tex)
- Il existe aussi, en complément, un exécutable pour UNIX / LINUX, mkddocu qui prend en charge les commandes courantes pour la génération de la documentation logicielle. (Création du projet, génération de la documentation, ...) Lire le manuel de mkddocu qui accompagne les dernières versions de mkd.
- Très simple et très pratique d'utilisation, mkd peut être proposé aux travaux pratiques de l'informatique pour l'étude du cycle en V.
- Des versions sont disponibles pour toutes les versions de MS-Windows, pour Cygwin et Mingw.
Sommaire
Cette version imprimable comprend les chapitres suivants :
Première partie : LA COMMANDE MKD
La commande mkd
Deuxième partie : EXERCICES
Introduction aux exercices
Comprendre les options
Comprendre les fichiers de projets
Codes QR pour pages imprimées
Les chapitres de MAINTENANCE suivants ne sont pas inclus dans cette version imprimable :
Troisième partie : INTERNATIONALISATIONS
Internationalisation des manuels
Internationalisation des messages
Quatrième partie : CODER, TESTER, INTEGRER, DOCUMENTER
Ajouter des modules
Cinquième partie : CONSTRUCTION D'UN PAQUET DEBIAN
Exercice de Construction d'un Paquet 'debian' pour la maintenance logicielle
Dépôt parrainé debian-ubuntu du paquet original mkd-131215
Sixième partie : CONSTRUCTION D'UN PAQUET RED-HAT
Paquets 'RPM' Red Hat Package Manager
NOTES ET ANNEXES
1.mkd-Manuel (fr)
2.Compilations de wiki-livres
3.QR pour pages imprimées
4.Notes Icônes des fichiers et applications héritées
5.Licences
Mkd (Extracteur de documents)
Première partie :
LA COMMANDE MKD
La commande mkd
| ||
|
| ||
Introduction
mkd est une commande destinée à extraire la documentation pour la maintenance et l'exploitation des logiciels en même temps que la compilation, selon les normes ISO[1][2].
Disponibilité
Les paquets Debian peuvent être convertis pour d'autres systèmes linux avec Alien
- Packages debian - ubuntu amd64 et i386.
- Télécharger mkd_140315.tar.gz archive source sur launchpad.
- Sources et paquets RPM pour systèmes bâtis sur le projet Fedora.
- Sources et distributions pour systèmes Windows et dérivés (Cygwin, Mingw).
Syntaxe
mkd [-ABCFPSafjlnpstvw] codes chemin_source [chemin_cible]
Description
mkd
- Les commentaires sélectionnés, dans le pseudo-code, ou tout commentaire, 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 programmation ( 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 de nombreuses 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 ( html, xml, etc ).
codes
- Ce sont des caractères alphanumériques. 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´ jusqu'à la version mkd_120508.
Options
Voir Shell Interface système.
Voir aussi les Notes pour les styles de langages.
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++ ( // et /* -> */ )
-F style Fortran (c,C ou * -> fin de ligne)
-P style Pascal ( { ... } et (* -> *) )
-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. On peut connaître ces options compilées par la commande
mkd \? sous Unix/Linux ou mkd ? sous DOS ou Terminal Widows.
-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. On peut connaître ces options compilées par la commande
mkd \? sous Unix/Linux ou mkd ? sous DOS ou Terminal Widows.
-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
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 la version courante de mkd, à 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 ? commentaire ligne que l'on extrait aussi avec avec cat et grep (Voir aussi le manuel de grep)
grep -n -e --[Code] <Fichier_source> [> Fichier cible]
- Autres options possibles avec -l : \' typé Basic, ; typé Assembleur, etc.
Ici, l'option -p permet d'extraire toutes les chaînes de caractères avec les codes '**'
Exemples
Exemple de fichiers sources pour générer la documentation
Quand c'est possible on écrit chaque fonction d'une application dans un fichier séparé, afin de produire une documentation dans un ordre alphabétique.
Quand les fonctions sont regroupées dans un même fichier, la documentation des fonctions apparaîtra dans le même ordre que dans le fichier.
Dans le fichier de la fonction on précise sa syntaxe d'utilisation, 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
/*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, cpp.h, version.h
/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
Exemple de fichiers cibles obtenus
- 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 !
Exemple de fichiers de commandes Shell. Exemple pour générer les manuels et les mettre à jour
Le fichier Update_mkd_en.1.txt doit être imposé au format UTF-8 avec un éditeur comme gedit ou BlueFish, pour être traduisibles dans toutes les langues. Vérifiez votre syntaxe avec GmanEdit (Éditeur Gnome)[3]
Note: Ceci est un exemple; Voir aussi: Installation du manuel français
#!/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: Attention crée une erreur si les fichiers n'existent pas.
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.txt 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.txt 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
Exemple de Makefile pour générer la documentation
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
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
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 Microsoft Visual Studio 2010[4] )
Fichiers
Traductions
Il existe des traductions sous unix / linux: Voir la page Traductions Internationales
- Les langues anglais français sont intégrées dans la distribution 2012 et sont prévues pour les langues espagnol allemand italien
( Les fichiers de traduction .pot et .po sont à votre disposition ) ainsi que sur le site des mainteneurs.
- Les manuels formatés nroff existent pour anglais allemand français et sont prévus pour espagnol italien
- Voir aussi la documentation de gettext[5] pour les traductions.
Notes
- Il appartient aux programmeurs de veiller à refermer les commentaires, blocs et lignes, par les codes de fermeture appropriés dans les fichiers sources.
- Attention: La fermeture d'un commentaire ligne est un retour chariot (NL, LF, CR/LF) selon les cas. Cette remarque implique un retour chariot en fin de commentaire ligne. Dans ce cas vous devez avoir une ligne vide à la fin du fichier source.
- Jusqu'à la version 2012, mkd ne lit et ne décode pas de façon récursive les fichier inclus par '#include' dans les fichiers sources.
Droits de copie
© EELL, Éditeurs Européens de Logiciels Libres, EUPL 2007.
- Vous êtes libre de copier reproduire et distribuer le livre 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[6] European Union Public Licence totalement compatible avec GNU
DROIT DE COPIE DES FICHIERS SOURCES:
© EELL, Éditeurs Européens de Logiciels Libres, EUPL 2007.
Association à but non lucratif selon l'Article 11 de la convention
européenne des droits de l'homme.
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:
https://joinup.ec.europa.eu/system/files/FR/EUPL%20v.1.1%20-%20Licence.pdf
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.
Concernant la documentation : la Licence est totalement compatible avec la
licence de documentation libre GNU.
Bugs
Voir aussi
anglais Comparison of documentation generators
mkdcppw, mkdcpp en mode graphique.
Histoire
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).
Notes et références
- Notes Style de langage[7]:
Définition de NL: New Line, fin de ligne.
Les styles impératifs (ABCFPSlp) s'excluent les uns des autres et ne permet pas la recherche de style par l'option '-f' (trouver le style)
- Style A (Commentaires style Assembleur)
- ; Commentaire NL
- Style B (Commentaires style Basic)
- REM (après un marqueur ' : ' dans QBasic) Commentaire NL
- ' Commentaire NL
- Styles C
- /* Commentaire */ : C, C++, C#, Java, Javascript, PHP, VHDL 2008, ...
- // Commentaire NL : C, C++, C#, CSS, D, Delphi, Java, Javascript, PHP, Scilab ...
- Style F (Commentaires style Fortran 77) voir Style l pour le Fortran 90 et plus récents.
- C ou c ou * Commentaire NL ; C,c ou * en première colonne.
- Style P (Commentaires style Pascal):
- (* Commentaire *) : AppleScript, Caml, Modula-2, Modula-3, Oberon, Pascal, ...
- { Commentaire } Delphi (Pascal objet)
- Style S (Commentaires style Shell): Csh, Bash, sh, et autres shells, Makefile, Perl, PHP, Python, Ratfor, Ruby, Tcl, ...
- # Commentaire NL
- Option l (selon option compilée) ; décodage des lignes. Remplace une commande impérative (ABCFPS) et les trois extractions peuvent être associée simultanément. CD₁ et CD₂ en première colonne, CD₃ n'importe où dans la ligne.
- avec CD₃ = ' ! ' Fortran 90
- avec CD₁₂₃ = ' % ' Latex, Matlab, Postscript, Tex
- avec CD₁₂₃ = ' # ' comme style S
- Option p (selon option compilée) ; décodage des blocs:
- Avec CD₄ = ' ( ' et CD₅ = ' ) ' : ( Commentaire )
- avec CD₄ = CD₅ = ' " ' Chaînes de caractères " Commentaire "
- avec CD₄ = CD₅ = ' ' ' Chaînes de caractères ' Commentaire '
- avec CD₄ = ' < ' et CD₅ = ' > ' tous les tags
- Remarques: Il est toujours possible d'inclure un style de commentaire dans le commentaire d'un autre style !
- Références
- ↑ ISO/IEC 26514:2008
- ↑ ISO/IEC 26514:2008 prévisualisation
- ↑ GmanEdit (Gnome manpage editor)
- ↑ Package redistribuable Visual C++ 2010 (x86)
- ↑ gettext
- ↑ Licence Publique de l'Union Européenne (fichier pdf)
- ↑ https://fr.wikipedia.org/wiki/Commentaire_(informatique)
Deuxième partie :
EXERCICESExercices
Introduction
Pour ce faire il faut évidemment disposer du matériel (Extrateur de documents, fichiers encodés, etc.) Nous proposons ici des fichiers déjà disponibles, mais vous pouvez essayer avec vos propres fichiers dans la langue et le langage qui vous convient.
Télécharger mkd
- Version Windows:
- Binaire 32 bits mkd.10.03.zip (Compilé avec Visual VC10).
- sources-mkd.10.03.beta.zip Pour MSDEV, Visual VC10, UNIX / LINUX.
- Versions Unix / Linux: (Paquets sécurisés sur Launchpad)
- Version Debian / Ubuntu sur Launchpad:
Binaires, et sources sous réserve d'adapter les chemins des répertoires man et catman.: - Version RPM (Fedora): (Paquets sécurisés sur le serveur eell.fr)
- Autres systèmes linux : Convertissez les paquets debian avec la commande alien
- Vous pouvez tenter de compiler mkd sur Mac:
Sources pour les exercices
Les fichiers ci après sont universels (pour tous les exercices et tous systèmes d'exploitation.)
Exercices élémentaires pour se familiariser avec la commande mkd
VOTRE ATTENTION: À l'impression les solutions n'apparaissent pas dans le texte. Les solutions aux exercices se trouvent dans la section suivante, dans le chapitre nommé Comprendre les options de la commande mkd.
- Vérifiez votre commande mkd. Tapez la commande mkd. L'erreur de syntaxe devrait s'afficher:
mkd PC version, Release 10.03, USAGE:
syntax: mkd [-ABCFPSafjlnpstvw] char_codes path_source [path_target]
or: mkd ? .See also mkd.doc or manual.
- Observez l'effets des options a,s,t,v,w de la commande mkd
- Observez ensuite l'action des codes de sélection de commentaires D, H, O, P, S, T, w (5 maximun)
- Rappel de la commande: mkd [-ABCFPSafjlnpstvw] codes chemin_source [chemin_cible]
- Dans le répertoire des fonctions, tapez les commandes ci dessous dans un terminal:
Commande: mkd -Cwsv H cpp.c
Testez mkd -Cwsv H cpp.c ( pour décoder le Header de style C, w pour écraser un fichier existant, s et v pour afficher à l'écran en mode bavard ) :
- Comprendre les options : aperçu 1.1
Commande: mkd -Cws H cpp.c
Quel est l'effet de l'option -v de la commande précédente ?
- Comprendre les options : aperçu 1.2
Commande: mkd -Cwts H cpp.c
Quel est l'effet de l'option -t sans l'option -v ?
- Comprendre les options : aperçus 1.3
Commande: mkd -Cwt H cpp.c *.h
Comparez ce résultat avec la commande précédente.
- Comprendre les options : aperçus 1.3
Résumé des observations sur les options s, t, v
Faites un résumé de l'utilisation des options n,s,t.v,w.
Essayez aussi l'option -n
Quelle syntaxe proposez-vous pour la génération du fichier d'entête cpp.h ?
- Comprendre les options : Résumé des observations sur les options s, t, v
Créez ou écrasez le fichier cible de l'organigramme cpp.organigramme
- Organigramme simple avec numérotation des lignes: code 'O'
- Organigramme avec structure avec numérotation des lignes: codes "OS"
- Organigramme complet avec les tests warnings et numérotation des lignes: Codes "POSTw"
- Comprendre les options : Solution 1.5
Crééz ou écrasez le fichier de documentation logicielle html du fichier cpp.c
- Le but de l’exercice est de se familiariser avec l'option -a.
- Le Fichier cible: aura pour nom "cpp-documentation_logicielle_codage.html".
- Créez la tête du fichier html avec le code 'h' options -Cwt
- Exemple: mkd -Ctw h cpp.c cpp-documentation_logicielle_codage.html
- Ajoutez le corps avec le code 'd' et les options -Cat (Option -a comme append, ajouter au fichier cible)
- Ajoutez le pied du fichier html avec le code 'f' et les options -Cat
- Visualisez le fichier cpp-documentation_logicielle_codage.html avec votre navigateur
- Quelle meilleure solution proposez-vous pour créer cpp-documentation_logicielle_codage.html ?
- Comprendre les options : Solution 1.6
Exercices pour se familiariser avec les fichiers de projets
ci-après: fichier est un nom quelconque sensé représenter votre projet dans le répertoire des fichiers sources.
Utiliser l'option -f (finder):
Pour valoriser cette option il serait utile d'ajouter un fichier d'un autre langage de programmation à votre convenance (Trouvez sur wikibooks ou wikipedia). À défaut, recopiez et collez le texte ci-dessous dans un fichier nommé putchar.asm sous Windows ou putchar.s sous Linux, à placer dans le répertoire du projet, avec cpp.c et asm.c
Trouvez l'exemple en assembleur Microsoft (MASM) sur wikipédia[1]:
putchar.asm
Ce court fichier est utilisé à titre d'exemple pour donner une solution réaliste aux exercices et peut être remplacé par tout autre fichier en assembleur.
;P Fichier puchar, macro en assembleur pour MS-DOS
;P ATTENTION: N'oubliez pas la dernière ligne vide
;P Macro trouvée sur wikipedia:fr:Assembleur#Macro-assembleur
;P Pour l'exercice suivant:
;P wikibooks:fr:Mkd_(Extracteur_de_documents)/Exercices#Fichiers_de_projet
;
;D Fichier putchar.asm sous DOS/Windows
;D Fichier putchar.s sous Unix/Linux
;D macro putchar
;D ----------------------------------------------------------------------------
;D putchar est une macro MASM qui affiche un caractère sous MS-DOS.
;D On l'utilisera par exemple ainsi
;D putchar "X"
;D Et cela générera :
;D mov dl,"X"
;D mov ah,2
;D int 21h
;D
;
;H // puchar.asm:
;H // Pas de pototype
;
;O macro.asm
putchar Macro car ;O Prototype de la macro
ifdef car ;O si car est défini
mov dl,car ;O le mettre dans dl
endif
mov ah,2 ;O ah=2 : fonction "putchar" en DOS
int 21h ;O appel au DOS
endm ;O fin macro
Aperçus et solutions des exercices pour comprendre les "Fichiers de projets"
Créer un fichier de projet manuellement
Projet exercice.prj ; à créer manuellement avec les fichiers disponibles asm.c cpp.c putchar.s
- Comprendre les fichiers de projets : Aperçu
Créer un fichier de projet avec les commandes système
Projet exercice.prj ; à créer avec les commandes de votre système d'exploitation; ls, dir.
- Comprendre les fichiers de projets : Solution
Créer un fichier de commandes pour :
Vous aurez copié les fichiers à éprouver dans le répertoire des essais . exécutez la commande mkd \? pour visualiser les extensions reconnues par votre mkd. Ces extensions dépendent des options de compilation.
Les fichiers sont écrits dans des langages de programmation différents, le but est de créer des documentations globales avec ou sans le finder (option -f).
- Comprendre les fichiers de projets : Aperçus et solutions des "Fichiers de commandes"
Mettre à jour le fichier d'entête. header global
(header global, exercice.h)
- Comprendre les fichiers de projets : Solutionl
Mettre à jour l'organigramme de chaque fichier de programme
Pseudo-code; Code de repérage 'O', asm.org, cpp.org, putchar.org
- Comprendre les fichiers de projets : Solution et aperçu avec commentaires
Mettre à jour la structure de chaque fichier
avec le pseudo code. Code 'S' et 'O' et 'w', fichier.struct
Fichier:s asm.struct, putchar.struct.
- Comprendre les fichiers de projets : Aperçus
Mettre à jour la documentation globale pour les programmeurs
avec les dates de mise à jour etc. Code 'P' Fichier: exercice.info_programmeurs
- Comprendre les fichiers de projets : Aperçu
Mettre à jour de la documentation logicielle globale
(Conception détaillée, Tests unitaires, du cycle en V) Code 'D' Fichier: exercice.docu
- Comprendre les fichiers de projets : Aperçu
Notes sur le finder
Le finder (trouveur) cherche le style du langage par examen de l'extension du nom de fichier, l'option -f est rarement utilisée.
Extensions spécifique à Windows et MS-DOS: Assembleur, Basic, C, Fortran, Pascal, C ou Prolog.
- .ASM .BAS .C .FOR .PAS .PRO extensions en majuscules ou minuscules.
Extensions spécifique à unix / linux: assembleur, C, Fortran, Ratfor, Pascal, Shell, Cshell
- .s .S .c .h .i .f .F .r .p .sh .csh
Notez que les extensions de fichiers .c .h et .prj sont toujours reconnus alors que .c++, .cpp, .hpp ne sont pas reconnus par le finder tout au moins jusqu'à la version 2012. Il est nécessaire de préciser l'option 'C' dans la ligne de commande.
REMARQUES:
c++, cpp, hpp seront probablement reconnus dans les prochaines mises à jour.
Il est relativement facile de l'implémenter dans le fichier "find.inc.c" ou find.i
Les commentaires en style ADA commencent par deux tirets et ne sont pas reconnus en standard par le finder (trouveur) de mkd, cependant si il est facile de l'implémenter dans le fichier "find.i" il faudra aussi créer un fichier spécifique à ADA (ada.c ou ada.i)
Fichiers de tests unitaires
- Inspirez-vous de la documentation de la fonction cpp_() (fichier cpp.c) pour créer un fichier de commandes qui met la fonction cpp_() à l'épreuve.
- Conditions des tests: tous les tests se feront avec l'option impérative -C
- Vérifiez les options de la fonction: n, s, t, séparément.
- Vérifiez que la numérotation des lignes est correcte dans tous les cas de décodage (lignes et blocs). n, ns. nt, nst.
- Vérifiez que le texte reste à la bonne place dans tous les cas de décodage: toute la ligne (dans la cas de la directive de compilation FULL_LINE), ou texte seul.
- - Vérifiez que les tabulations sont bien prises en charge dans tous les cas, décodage des lignes et des blocs
- - Vérifiez de même pour les espaces.
- Vérifiez que le caractère de fin de fichier n'apparaît pas en fin de texte lorsque le commentaire ne se termine pas par une fin de ligne.
- Documentation:
- Ajouter des modules : Documentation pour éprouver les modules.
- Ajouter des modules : Une solution à cet exercice
Notes et références
Philosophie de la méthode en génie logiciel avec ADA
Comprendre les options de la commande mkd
Généralités
- Syntaxe de la ligne de commande
- mkd [-ABCFPSafjlnpstvw] codes chemin_source [chemin_cible]
- Distinguer les options impératives
- Les options de langages en majuscules ABCFPS permettent d'extraire les commentaires codés dans un style de langage générique.
- Le style C par exemple peut décoder le C, c++, c--, c#, CSS, java, javascript, php
- Les options de langage en minuscules l et p
- Ces options dépendent de la compilation CD1, CD2, CD3, CD4, CD5. On peut connaître ces options par la commande mkd \?; options l et p
- Les options -l d'extraction des lignes peuvent être utilisées simultanément;
- les options -l; CD1 et CD2 :'%' '<' et CD3 '!' on peut simultanément extraire le PostsScript, les tags html, les commentaires Fortran 90
- L'option -p d'extraction de blocs permet d'extraire des blocs de chaînes de caractères avec les options CD4=CD5= '\"'. CD1 '(' avec CD5 ')' permet d'extraire des blocs entre parenthèses
- Les options d'extraction et d'ouverture des fichiers anstvw
- L'ouverture des fichiers peut être la création du fichier cible avec l'option -w ou l'ajout avec l'option -a
- Les options nstv sont des options d'extration et d'affichage
- n permet de connaître le numéro de la ligne extraite
- s permet une copie vers la sortie standard (un écran, un fichier, une imprimante, etc.
- t permet d'éliminer les codes d'extraction et les caractères de début et de fin de commentaire
- v mode bavard qui permet d'afficher les conditions d'extraction au terminal ou à la sortie standard
Exercices élémentaires pour se familiariser avec la commande mkd
Commande: mkd -Cwsv H cpp.c
- en mode bavard (-v), vous devez obtenir à la console:
Options a=0 f=0 j=0 l=0 n=0 p=0 s=1 t=0 w=1 fichier doc : 'cpp.doc' fichier pour doc: 'cpp.c' (fichier cpp.c :) /*H // Files: cpp.c (cpp.inc.c++ for mkdcppw and gtkmm) extern int cpp_ (FILE * pfdoc, FILE * pnfile); */ DOC cpp.doc FIN
- Le fichier cpp.doc contient:
(fichier cpp.c :)Options a=0 f=0 j=0 l=0 n=0 p=0 s=1 t=0 w=1 /*H // Files: cpp.c (cpp.inc.c++ for mkdcppw and gtkmm) extern int cpp_ (FILE * pfdoc, FILE * pnfile); */
- Notez qu'avec l'option -v on ne peut pas obtenir un fichier d'entête cpp.h car cette option crée une première ligne avec le nom du fichier.
Commande: mkd -Cws H cpp.c
- Sans l'option -v on obtient au terminal:
(fichier cpp.c :) /*H // Files: cpp.c (cpp.inc.c++ for mkdcppw and gtkmm) extern int cpp_ (FILE * pfdoc, FILE * pnfile); */
- Le fichier cpp.doc contient:
/*H // Files: cpp.c (cpp.inc.c++ for mkdcppw and gtkmm) extern int cpp_ (FILE * pfdoc, FILE * pnfile); */
- Les options Cw ou Cws ne suffisent pas pas pour créer le fichier d'entête cpp.h car les caractères de commentaires sont recopiés.
Commande: mkd -Cwts H cpp.c
Avec l'option -t et sans l'option -v on obtient au terminal:
(fichier cpp.c :) // Files: cpp.c (cpp.inc.c++ for mkdcppw and gtkmm) extern int cpp_ (FILE * pfdoc, FILE * pnfile);
- Le fichier cpp.doc contient:
// Files: cpp.c (cpp.inc.c++ for mkdcppw and gtkmm) extern int cpp_ (FILE * pfdoc, FILE * pnfile);
Commande: mkd -Cwt H cpp.c *.h
- Cette fois le fichier d'entête cpp.h peut être créé correctement et cette syntaxe doit être employée dans les fichiers de commandes, ainsi que dans les Makefiles
Résumé des observations sur les options s, t, v
- L'option -v, mode bavard, est inappropriée pour générer des documents imprimables. Elle sert pour la mise au point des fichiers de commandes avec l'option -s
- L'option -s permet la mise au point des fichiers de commandes sans nécessité d'éditer le fichier cible.
- L'option -t est nécessaire pour obtenir des document présentables et imprimables.
Créez ou écrasez le fichier cible de l'organigramme cpp.organigramme
- Organigramme simple avec numérotation des lignes:
mkd -Cnstw O cpp.c cpp.organigramme
- Organigramme avec structure avec numérotation des lignes:
mkd -Cnstw OS cpp.c cpp.organigramme
- Organigramme complet avec les tests warnings et numérotation des lignes:
mkd -Cnstw POSTw cpp.c cpp.organigramme
Crééz ou écrasez le fichier de documentation logicielle html du fichier cpp.c
- Familiarisation avec l'option -a
mkd -Ctw h cpp.c cpp-documentation_logicielle_codage.html
mkd -Cat d cpp.c cpp-documentation_logicielle_codage.html
mkd -Cat f cpp.c cpp-documentation_logicielle_codage.html
- Solution globale pour un seul fichier:
mkd -Cat hdf cpp,c cpp-documentation_logicielle_codage.html
Notes et références
Notez que:
- Les options impératives -ABCFPS sont incompatibles entre elles et avec l'option -f (find - trouver le style du langage de programmation).
- Les options -a (append - ajouter) et -w (overwrite - écraser) sont difficilement compatibles ...
Comprendre les fichiers de projets pour mkd
Exercices pour se familiariser avec les fichiers de projets
Les fichiers de projets d'extension .prj ou .pj sont des fichiers qui contiennent la liste des fichiers (sources) pour générer les documents (cibles).
Les fichiers de la liste ont parfois des extensions différentes.
Si les fichier sont tous de même style de commentaires on peut imposer une des options impératives pour générer les documents, mais pour utiliser un fichier de projet il est nécessaire de préciser que le fichier source est un fichier de projet avec l'option -j souvent associé à l'option -f (find). Dans le cas où find ne trouve pas le type de fichier, les styles compilés sont proposés à la sortie standard (Terminal en général)
L'option -j est compatible avec les options impératives.
Créer un fichier de projet manuellement
Projet exercice.prj ; à créer manuellement avec les fichiers disponibles asm.c cpp.c putchar.s
Manuellement on est maître de la liste des fichier et de l'ordre nécessaire au décodage.
Nom du fichier de projet exercice.prj ; dans l'ordre alphabétique:
asm.c cpp.c putchar.s
Créer un fichier de projet avec les commandes système
Projet exercice.prj ; à créer avec les commandes de votre système d'exploitation; ls, dir.
- Avec terminal linux: ls
ls -1 *.s *.c > exercice.prj
Fichier exercice.prj : La mise en ordre alphabétique est automatique.
asm.c cpp.c putchar.s
- Avec terminal cmd Windows 7, dir: option /B: noms courts, et option /ON: tri alphabétique.
Notez que le terminal PowerShell ne convient pas.
dir /B /ON *.asm *.c > exercice.prj
Fichier exercice.prj :
asm.c cpp.c putchar.asm
Créer un fichier de commandes pour :
Vous aurez copié les fichiers à éprouver dans le répertoire des essais . exécutez la commande mkd \? pour visualiser les extensions reconnues par votre mkd. Ces extensions dépendent des options de compilation.
Les fichiers sont écrits dans des langages de programmation différents, le but est de créer des documentations globales avec ou sans le finder (option -f).
Mettre à jour le fichier d'entête. header global
exercice.h
La commande doit trouver le type de fichier du projet exercice.prj avec l'option -f
mkd -jfstw H exercice.prj exercice.h
Fichier exercice.h:
// asm.c:
extern int asm_(FILE *pfdoc, FILE *pnfile);
// Files: cpp.c (cpp.inc.c++ for mkdcppw and gtkmm)
extern int cpp_ (FILE * pfdoc, FILE * pnfile);
// puchar.asm:
// Pas de pototype
Mettre à jour l'organigramme de chaque fichier de programme
Pseudo-code; Code de repérage 'O',
asm.org, cpp.org, putchar.org
- mkd -Cstw O asm.c asm.org
- mkd -Cstw O cpp.c cpp.org
- mkd -Astw O putchar.asm putchar.org
(L'exemple putchar avec MASM est forcément sous MS-DOS)
Fichier putchar.org:
macro.asm
putchar Macro car O Prototype de la macro
ifdef car O si car est défini
mov dl,car O le mettre dans dl
mov ah,2 O ah=2 : fonction "putchar" en DOS
int 21h O appel au DOS
endm O fin macro
Notez que la première ligne est correcte: macro.asm, alors que les commentaires qui suivent sont précédés du caractère O du fait que toute la ligne est recopiée sauf le caractère ; (Ceci est dû à l'option de compilation FULL LINE): La copie de la ligne est entière le caractère de commentaire est remplacé par un espace ligne 256 du fichier asm.c. (Voir asm.struct de l'exercice suivant "Mettre à jour la structure de chaque fichier")
Pour éviter ce qui pourrait être un inconvénient il suffit de recompiler mkd sans l'option FULL_LINE.
Pour une bonne présentation on a toujours intérêt à écrire le pseudo-code sur des lignes séparées avec le caractère ; en première colonne.
Bug: Un des bugs connus est la fin de ligne qui se termine par EOF à la place de EOL (NL retour chariot)
Mettre à jour la structure de chaque fichier
avec le pseudo code. Code 'S' et 'O' et 'w',
asm.struct
mkd -Cswn OSw asm.c asm.struct
Fichier asm.struct (édité avec Bluefish)
(fichier asm.c :)
98 { /*S asm */
109 /*O tant que pas fin de fichier source (c1, c2, c3 différents de EOF)*/
111 { /*S tq !EOF */
112 /*O si début de texte faire c1=LF */
114 /*O sinon prendre pour c1 le char suivant */
116 /*O si le char est NL repérer la position qui suit 'NL' (repérer dans
117 -- l'entier long nl) */
119 { /*S reperage debut de ligne */
123 } /*S reperage debut de ligne */
125 /*O----- si le char est NL ---------------------------------------------------*/
127 { /*S ; en colonne 1 */
130 /*O si c1 est suivi par c2 = ';' et
131 -- si codes[0]=0 ou si suivi par un des 5 char code d'utilisateur */
141 /*O alors copier les caractères dans le fichier doc, et si option s
142 -- ajouter au terminal */
143 { /*S copier */
144 /*O si option n insérer le numéro de ligne et si option s l'ajouter au
145 -- terminal */
147 { /*S n */
150 } /*S n */
151 /*O si l'option t est fausse (pas de texte seul) */
153 { /*S !t */
154 /*O copier le début de ligne */
156 /*O si option s copier le commentaire au terminal */
158 { /*S si opt s */
161 } /*S si opt s */
162 } /*S !t */
163 /*O sinon si il ne faut pas copier tout le commentaire:
164 -- reculer de 1 caractère */
166 /*O tant que l'on a pas trouvé le caractère fin de ligne NL ('\n')*/
168 { /*S w copy line */
169 /*O copier les caractères de la ligne */
172 } /*S w copy line */
173 /*O copier aussi le caractère de fin de ligne et, avec l'option s
174 -- envoyer le retour-chariot au terminal */
177 /*O revenir sur LF du fichier source */
179 } /*S copier */
180 /*O sinon restituer les deux derniers caractères */
182 { /*S sinon */
185 } /*S sinon */
186 } /*S ; en colonne 1 */
188 /*O--------- sinon si c1 = ';' est dans la ligne ----------------------------*/
190 { /*S else */
191 /*O si le caractère c1 est une tabulation incrémenter tab */
193 /*O sinon si c1 = ; */
195 /*O alors: */
196 { /*S char = ; */
198 /*O si codes[0]=0 ou si suivi par c2 = char code utilisateur */
206 /*O alors: */
207 { /*S commentaire page */
208 /*O repérer la position de début de commentaire */
211 /*O si l'option booléenne t est fausse (pas de texte seul) */
213 { /*S !t */
214 /*O se positionner en début de ligne */
217 /*O si l'option n est vraie, insérer le numéro de ligne */
219 { /*S n (numéro de ligne) */
221 /*O si option s vraie, ajouter le numéro de ligne à l'écran */
223 } /*S n */
224 /*O copier toute la ligne tq pas NL (CR/LF), dans le fichier doc */
226 { /*S w */
229 } /*S w*/
230 } /*S !t */
231 /*O sinon: (option t) */
233 { /*S option t */
234 /*O se positionner en dedut de ligne */
237 /*O si option n vraie, insérer le numéro de ligne */
239 { /*S n (numero de ligne) */
241 /*O si s vrai, ajouter le numéro de ligne à l'écran */
243 } /*S n */
246 //P { /*S tabs */
249 //P } /*S tabs */
250 /*O copier toute la ligne jusqu'à la position commentaire */
252 { /*S w */
255 } /*S w*/
256 /*O ajouter un espace pour remplacer le caractère ';' */
258 { /*S espaces */
261 } /*S espaces */
262 /*O puis copier le commentaire tant que NL n'est pas trouvé */
264 { /*S copier commentaire */
267 } /*S copier commentaire */
268 } /*S option t */
269 putc('\n',pfdoc);if(s)putch('\n'); /*O copier NL */
270 ungetc(c1,pnfile); /*O revenir sur NL */
271 } /*S commentaire page */
272 /*O sinon: */
274 { /*S*/
275 /*O revenir un caractère en arrière */
277 } /*S*/
278 } /*S char = ; */
279 } /*S else */
280 } /*S tq !EOF */
282 } /*S asm */ÿ
Notez la fin de fichier avec le caractère ÿ qui témoigne d'une fin incorrecte sur EOF
putchar.struct
mkd -Aswn OSw putchar.asm putchar.struct
(fichier putchar.s :) 19 ;O macro.asm 20 putchar Macro car ;O Prototype de la macro 21 ifdef car ;O si car est d�fini 22 mov dl,car ;O le mettre dans dl 24 mov ah,2 ;O ah=2 : fonction "putchar" en DOS 25 int 21h ;O appel au DOS 26 endm ;O fin macro
Notez la fin de fichier correcte qui témoigne d'une fin correcte sur EOL (New Line)
Notez aussi qu'un des caractères n'est pas au format UTF-8 (le é de défini)
Mettre à jour la documentation globale pour les programmeurs
avec les dates de mise à jour etc. Code 'P'
exercice.info_programmeurs
mkd -fjstw P exercice.prj *.info_programmeurs
Fonction asm_(); Fichier asm.c
Documentation simplifiée.
-------------------------
La fonction asm_() doit décoder des commentaires, pré-codés avec un carac-
tère ASCII qui suit le début de commentaire.
Exemple ;A en 'début' ou 'dans' la ligne.
... et bla bla bla ...(raccourci pour les exercices)
Tests unitaires:
----------------
La fonction doit être éprouvée de telle sorte qu'un commentaire qui se
termine par le caractère de fin de fichier soit entièrement copié dans
le fichier cible.
Le caractère de fin de fichier décodé avant le caractère de fin de ligne
doit être remplacé par un caractère de fin de ligne.
Le caractère de fin de fichier (EOF) ne doit jamais apparaître dans texte
du fichier cible.
-----------------------------------------------------------------------------
© Contact: http://edeulo.free.fr/contacts/formmail.php
© EELL, Éditeurs Européens de Logiciels Libres, EUPL 2007
Association à but non lucratif selon l'Article 11 de la convention européenne
des droits de l'homme.
-----------------------------------------------------------------------------
NOM DU FICHIER: asm.inc.c asm.c
PROJET: mkd
Générer la documentation pré-écrite dans les fichiers de sources multiples.
PROJET INITIAL: mkdoc 1989 pour MS-DOS et UNIX, devenu obsolète.
DOSSIER: extractdoc 04/12/2009
MODIFICATIONS:
asm.inc.c
....
asm.c
Le: ../../2010 par JPL Transformation into independent function for mkdasm
Move the name asm.inc.c to asm.c
Le: 10/01/2010 par Clara objet de la modification contrôle de l'accentuation
des commentaires en ISO-8859-1
Le: 11/02/2010 par JPL Update for MS Visual C10 beta 2
Le: 10/03/2010 par JPL objet de la modification simplification de l'entête
Le: 17/03/2012 par JPL objet de la modification vérification des commentaires
au format UTF-8
rappels: options booléennes à définir
-- dans main() ou winmain()
copier autant de tabulations qu'il y en a dans le source */
Fonction cpp_(); Fichier cpp.c
Documentation simplifiée.
-------------------------
La fonction doit décoder des commentaires, pré-codés avec un caractère
ASCII qui suit le début de commentaire. exemple //A ou /*A
... et bla bla bla ...(raccourci pour les exercices)
Tests unitaires:
----------------
Vérifiez les options n, s et t séparément:
Vérifiez que la numérotation des lignes est correcte dans tous les cas de
décodage (lignes et blocs). n, ns. nt, nst.
Vérifiez que le texte reste à la bonne place dans tous les cas de décodage:
toute la ligne (dans la cas de la directive de compilation FULL_LINE), ou
texte seul.
-- Vérifiez que les tabulations sont bien prises en charge dans tous les
cas, décodage des lignes et des blocs.
-- Vérifiez de même pour les espaces.
La fonction doit être éprouvée de telle sorte qu'un commentaire qui se
termine par le caractère de fin de fichier soit entièrement copié dans le
fichier cible.
Le caractère de fin de fichier décodé avant le(les) caractère(s) de fin de
commentaire doit être remplacé par un caractère de fin de ligne.
Le caractère de fin de fichier (EOF) NE DOIT JAMAIS APPARAÎTRE DANS LE
TEXTE DU FICHIER CIBLE.
Ceci provoquait un bug dans la version Alpha de l'application fenêtrée
mkdcppw à l'étape du test d'intégration.
-----------------------------------------------------------------------------
© Contact: http://edeulo.free.fr/contacts/formmail.php
© EELL, Éditeurs Européens de Logiciels Libres, 2007
Association à but non lucratif selon l'Article 11 de la convention européenne
des droits de l'homme.
-----------------------------------------------------------------------------
FILE NAMES: cpp.inc.c cpp.c cpp.inc.c++
PROJECT: mkd
mkd is a UNIX command to extract pre-encoded comments lines to generate the
software documentation according to ISO standards.
mkd is the abbreviation of make documentation. This command was originally
known under the name mkdoc (make documentation).
This command is not integrated into the standard distributions of Unix / Linux
INITIAL PROJECT:
mkdoc 1989 for MS-DOS and UNIX now obsolete. CEM - University of Montpellier II
ADMINISTRATIVE RECORD:
extractdoc 04/12/2009
FILE UPDATE:
cpp.inc
-------
Date: ../../1986 by JPL Initial programming for MSDOS and UNIX on SUN
Date: ../../1991 by JPL mkdoc 3.12 for PC and UNIX
Date: ../../1995 by JPL mkdoc 3.22 for RED-HAT on LINUX
Date: ../../2004 by JPL mkdoc 4.00 for LINUX ubuntu
Date: 11/02/2010 by JPL Update for MS Visual C10 beta 2
cpp.c
-----
Date: ../../.... by JPL Transformation into independent function for mkdcpp
Move the name cpp.inc.c to cpp.c
cpp.inc.c++ and cpp.c
---------------------
Date: ../03/2012 by CLARA Update the comments to UTF-8 format and C++ for
mkdcppw. Version name for mkdcppw: cpp.inc.c++
Date: 02/05/2012 by CLARA Special adaptation for mkdcppw with gtkmm
Date: 10/03/2013 by JPL Rewrite comments in english (en) to facilitate the
translations
w appearance of codes in lines if codes[] flags are false
w depends of codes[]
CR/LF under DOS
(c1='*' voir c2)
c1 = always '*'
Fichier puchar, macro en assembleur pour MS-DOS
Macro trouvée sur wikipedia:fr:Assembleur#Macro-assembleur
Pour l'exercice suivant:
wikibooks:fr:Mkd_(Extracteur_de_documents)/Exercices#Fichiers_de_projet
Mettre à jour de la documentation logicielle globale
(Conception détaillée, Tests unitaires, du cycle en V) Code 'D'
exercice.docu
mkd -fjst D exercice.prj *.docu
exercice.docu
Fonction asm_(); Fichier asm.c
fonction asm_
-----------------------------------------------------------------------------
NOM DU FICHIER; asm.c
ACTION:
La fonction asm_ lit le fichier écrit en assembleur et extrait les
renseignements de structure, l'organigramme, la documentation destinée
aux programmeurs, au fichier d'entête (.h) ou à la documentation
destinée à l'utilisateur etc.
On utilise ici les codes d'identification des commentaires suivants :
D: pour la documentation générale sur les fonctions (listing)
H: pour générer le fichier d'entête (header, .h ou .hpp)
O: pour l'organigramme
S: pour le contrôle de la structure du programme
T: pour les points de tests
U: pour la documentation utilisateur
Options :
n : numéro de ligne (ajoute le numéro de ligne)
s : écran (ajoute le commentaire à l'écran)
t : texte seul (ne copie pas les caractères de repérage)
SYNTAXE:
#include "version.h"
#include "asm.h"
int asm_(FILE *pfdoc, FILE *pnfile);
PORTABILITE:
Win32 Win64 UNIX/Linux x86 et amd64
DESCRIPTION:
FILE *pfdoc : pointeur sur le flux du fichier de destination
File *pnfile : pointeur sur le flux du fichier source
VALEUR RETOURNÉE:
Ne retourne rien
DROIT DE COPIE:
© mkd, EUPL 2007, précisée dans version.h
Fonction cpp_(); Fichier cpp.c
function cpp_
-----------------------------------------------------------------------------
FILE NAMES: cpp.c and cpp.inc.c++ with gtkmm for mkdcppw
( Comments in UTF-8 with Bluefish text editor )
ACTION:
The cpp_ function reads the source file (pnfile) transmitted from the
calling function, and d�codes the comments pre-encoded in lines or
blocks of style c++. and then writing this comments in a target file
(pfdoc).
Pre-coded characters are defined in a external global table 'Codes';
The golbal variables are 'Codes' and 'Options'.
The 'Codes': table of 5 characters:
extern char codes[];
They must be defined in the calling function:
char codes[5] = {0,0,0,0,0};
The 'Options': n,s,t,v.
extern unsigned char n,s,t;
They must be defined in the calling function:
unsigned char n=0,s=0,t=0;
With the options:
n: The transcript is preceded by line number. This allows to easily
reach the commented line.
s: Add the comment to the screen 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.
Remark:
If the decoded comment begins with the characters "/ *", the comment
is copied until find the characters "* /", whatever included any
comment-line starting with "//".
If the decoded comment begins with the characters "//", the line is
copied until find the end-of-line or new-line 'NL' character or
end-of-file 'EOF'.
This provisions facilitate the automatic generation of header files
(file.h ; .hpp ; etc.) and documentation of functions.
SYNTAX:
In UNIX / LINUX environnement:
#include "/usr/include/mkd/version.h" // IMPORTANT: Compilation directives
#include "/usr/include/mkd/cpp.h"
int cpp_(FILE * pfdoc, FILE * pnfile);
PORTABILITY:
Microsoft Visual studio under Windows : x86(Win32) x64(Win32 and WIN64)
gcc under Unix / Linux.
DESCRIPTION:
cpp_ fonction
FILE * pfdoc: pointer of the target file opened by the calling function
FILE * pnfile: pointer of the source file opened by the calling function
RETURN VALUE:
Return 0 in case of success in konsole version, nothing with gtkmm.
COPYRIGHT: (Specified in version.h)
SEE ALSO MANUAL:
Man(3) attached in English.
Command line : man 3 cpp_
Fichier putchar.asm sous DOS/Windows
Fichier putchar.s sous Unix/Linux
macro putchar
----------------------------------------------------------------------------
putchar est une macro MASM qui affiche un caract�re sous MS-DOS.
On l'utilisera par exemple ainsi
putchar "X"
Et cela génèrera :
mov dl,"X"
mov ah,2
int 21h
Notes et références
Codes QR des téléchargements
Les codes QR (Quick Response) permettent aux lecteurs des pages imprimées de se connecter rapidement sur le wikilivre à l'aide d'un lecteur de codes QR (disponible sur les smartphones) pour:
- recompiler le livre sous une forme différente ou obtenir une version à jour,
- compiler d'autres pages.
-
Article wikibook
Mkd
Extracteur de documents -
Compilation
La commande mkd
avec
QR des téléchargements -
Compilation pour ePub
Exercices avec mkd,
avec les réponses aux exercices -
Compilation:Extracteur de documents mkd
avec Exercices et QR des téléchargements
.svg)
-
Packs mkd sources + binaires Ubuntu (i386+amd64)
Téléchargement -
Packs mkdcppw sources + binaires Ubuntu (i386+amd64)
Téléchargement -
mkd Windows Beta 2010 (x86)
Téléchargement
Lien à corriger
.png)