Mkd (Extracteur de documents)/Introduction aux exercices/Version imprimable
Sauter à la navigation
Sauter à la recherche
Éditeurs européens de logiciels libres
La commande mkd (extracteur de documents)
Exercices et réponses
Exercices et réponses
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_aux_exercices
Vous avez la permission de copier, distribuer et/ou modifier ce document selon les termes de la Licence de documentation libre GNU, version 1.2 ou plus récente publiée par la Free Software Foundation ; sans sections inaltérables, sans texte de première page de couverture et sans Texte de dernière page de couverture. Une copie de cette licence est incluse dans l'annexe nommée « Licence de documentation libre GNU ».
Aperçu
mkd est une commande Unix / Linux utilisée dans les fichiers de commandes et dans les Makefile pour maintenir à jour la documentation logicielle.
Des versions sont disponibles pour MASM / MS-DOS et pour Visual studio / MS-Windows.
Très simple et très pratique d'utilisation, mkd peut être proposé aux les travaux pratiques de l'informatique pour l'étude du cycle en V.
Sommaire
Cette version imprimable comprend les chapitres suivants :
Introduction aux exercices
Comprendre les options
Comprendre les fichiers de projets
QR pour pages imprimées
Les chapitres suivants ne sont pas inclus dans cette version imprimable :
La commande mkd
mkd-Manuel (fr)
Internationalisation des messages
Internationalisation des manuels
Ajouter des modules
Compilations
Notes
- Une version plus complète est disponible
- https://fr.wikibooks.org/wiki/Mkd_(Extracteur_de_documents)/Livre_imprimable
Exercices
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: A 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). A 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 exemples 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
Aperçu 1.1
- 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
Aperçu 1.2
- 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
Aperçu 1.3
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
Résumé des observations
- 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
Solution 1.5
- 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
Solutions 1.6
- 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
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
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 :
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
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
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
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
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, Editeurs 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
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 RETOURNEE:
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
Maintenance
Cette page est susceptible de subir des modifications occasionnelles
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)
Licence de documentation libre GNU
Résumé
La licence de documentation libre GNU (GNU Free Documentation License) est une licence produite par la Free Software Foundation. Cette licence a pour but de permettre la diffusion de contenu libre.
L'objet de cette Licence est de rendre tout manuel, livre ou autre document écrit « libre » au sens de la liberté d'utilisation, à savoir : assurer à chacun la liberté effective de le copier ou de le redistribuer, avec ou sans modifications, commercialement ou non.
Attention, contenu libre ne veut pas dire domaine public. Les différents créateurs de documents sous licence GFDL restent propriétaire de leurs écrits ou de leurs images. La licence GNU requiert que les auteurs gardent le crédit de leurs contributions. Pour cette raison, toute utilisation de document sous licence GFDL doit mentionner la source de ce contenu (par exemple, soit en créditant l'organisation d'où origine le document ou encore le document directement).
- en français (traduction non officielle, version 1.1): http://cesarx.free.fr/gfdlf.html
- version officielle en anglais: http://www.gnu.org/copyleft/fdl.html
Texte intégral
GNU Free Documentation License
Version 1.2, November 2002
Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or other
functional and useful document "free" in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or noncommercially.
Secondarily, this License preserves for the author and publisher a way
to get credit for their work, while not being considered responsible
for modifications made by others.
This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense. It
complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does. But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book. We recommend this License
principally for works whose purpose is instruction or reference.
1. APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium, that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License. Such a notice grants a
world-wide, royalty-free license, unlimited in duration, to use that
work under the conditions stated herein. The "Document", below,
refers to any such manual or work. Any member of the public is a
licensee, and is addressed as "you". You accept the license if you
copy, modify or distribute the work in a way requiring permission
under copyright law.
A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section of
the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall subject
(or to related matters) and contains nothing that could fall directly
within that overall subject. (Thus, if the Document is in part a
textbook of mathematics, a Secondary Section may not explain any
mathematics.) The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.
The "Invariant Sections" are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License. If a
section does not fit the above definition of Secondary then it is not
allowed to be designated as Invariant. The Document may contain zero
Invariant Sections. If the Document does not identify any Invariant
Sections then there are none.
The "Cover Texts" are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License. A Front-Cover Text may
be at most 5 words, and a Back-Cover Text may be at most 25 words.
A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters. A copy made in an otherwise Transparent file
format whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amount
of text. A copy that is not "Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format, SGML
or XML using a publicly available DTD, and standard-conforming simple
HTML, PostScript or PDF designed for human modification. Examples of
transparent image formats include PNG, XCF and JPG. Opaque formats
include proprietary formats that can be read and edited only by
proprietary word processors, SGML or XML for which the DTD and/or
processing tools are not generally available, and the
machine-generated HTML, PostScript or PDF produced by some word
processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page. For works in
formats which do not have any title page as such, "Title Page" means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.
A section "Entitled XYZ" means a named subunit of the Document whose
title either is precisely XYZ or contains XYZ in parentheses following
text that translates XYZ in another language. (Here XYZ stands for a
specific section name mentioned below, such as "Acknowledgements",
"Dedications", "Endorsements", or "History".) To "Preserve the Title"
of such a section when you modify the Document means that it remains a
section "Entitled XYZ" according to this definition.
The Document may include Warranty Disclaimers next to the notice which
states that this License applies to the Document. These Warranty
Disclaimers are considered to be included by reference in this
License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and has
no effect on the meaning of this License.
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License. You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute. However, you may accept
compensation in exchange for copies. If you distribute a large enough
number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and
you may publicly display copies.
3. COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly have
printed covers) of the Document, numbering more than 100, and the
Document's license notice requires Cover Texts, you must enclose the
copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover. Both covers must also clearly and legibly identify
you as the publisher of these copies. The front cover must present
the full title with all words of the title equally prominent and
visible. You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.
If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a computer-network location from which the general network-using
public has access to download using public-standard network protocols
a complete Transparent copy of the Document, free of added material.
If you use the latter option, you must take reasonably prudent steps,
when you begin distribution of Opaque copies in quantity, to ensure
that this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you distribute an
Opaque copy (directly or through your agents or retailers) of that
edition to the public.
It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it. In addition, you must do these things in the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions
(which should, if there were any, be listed in the History section
of the Document). You may use the same title as a previous version
if the original publisher of that version gives permission.
B. List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the
Document (all of its principal authors, if it has fewer than five),
unless they release you from this requirement.
C. State on the Title page the name of the publisher of the
Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license notice
giving the public permission to use the Modified Version under the
terms of this License, in the form shown in the Addendum below.
G. Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document's license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled "History", Preserve its Title, and add
to it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page. If
there is no section Entitled "History" in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.
J. Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
it was based on. These may be placed in the "History" section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.
K. For any section Entitled "Acknowledgements" or "Dedications",
Preserve the Title of the section, and preserve in the section all
the substance and tone of each of the contributor acknowledgements
and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section titles.
M. Delete any section Entitled "Endorsements". Such a section
may not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled "Endorsements"
or to conflict in title with any Invariant Section.
O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant. To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.
You may add a section Entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties--for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.
You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version. Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity. If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled "History"
in the various original documents, forming one section Entitled
"History"; likewise combine any sections Entitled "Acknowledgements",
and any sections Entitled "Dedications". You must delete all sections
Entitled "Endorsements".
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, is called an "aggregate" if the copyright
resulting from the compilation is not used to limit the legal rights
of the compilation's users beyond what the individual works permit.
When the Document is included in an aggregate, this License does not
apply to the other works in the aggregate which are not themselves
derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half of
the entire aggregate, the Document's Cover Texts may be placed on
covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the whole
aggregate.
8. TRANSLATION
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also include
the original English version of this License and the original versions
of those notices and disclaimers. In case of a disagreement between
the translation and the original version of this License or a notice
or disclaimer, the original version will prevail.
If a section in the Document is Entitled "Acknowledgements",
"Dedications", or "History", the requirement (section 4) to Preserve
its Title (section 1) will typically require changing the actual
title.
9. TERMINATION
You may not copy, modify, sublicense, or distribute the Document except
as expressly provided for under this License. Any other attempt to
copy, modify, sublicense or distribute the Document is void, and will
automatically terminate your rights under this License. However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such
parties remain in full compliance.
10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License "or any later version" applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation. If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.
ADDENDUM: How to use this License for your documents
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:
Copyright (c) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
replace the "with...Texts." line with this:
with the Invariant Sections being LIST THEIR TITLES, with the
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.
