Mkd (Extracteur de documents)/Comprendre les fichiers de projets
Exercices pour se familiariser avec les fichiers de projets
[modifier | modifier le wikicode]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
[modifier | modifier le wikicode]Projet exercice.prj ; à créer manuellement avec les fichiers disponibles asm.c cpp.c putchar.s
Aperçu
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
[modifier | modifier le wikicode]Projet exercice.prj ; à créer avec les commandes de votre système d'exploitation; ls, dir.
Solution
- 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 :
[modifier | modifier le wikicode]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
[modifier | modifier le wikicode]exercice.h
Solution
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
[modifier | modifier le wikicode]Pseudo-code; Code de repérage 'O',
asm.org, cpp.org, putchar.org
Solution et aperçu avec commentaires
- 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
[modifier | modifier le wikicode]avec le pseudo code. Code 'S' et 'O' et 'w',
asm.struct
Aperçu de asm.struct et commentaire
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
Aperçu de putchar.struct et commentaire
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
[modifier | modifier le wikicode]avec les dates de mise à jour etc. Code 'P'
exercice.info_programmeurs
Aperçu
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
[modifier | modifier le wikicode](Conception détaillée, Tests unitaires, du cycle en V) Code 'D'
exercice.docu
Aperçu
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