Mkd (Extracteur de documents)/Introduction aux exercices

Make documents

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.:

Paquets pour Ubuntu / Debian

Version RPM (Fedora): (Paquets sécurisés sur le serveur eell.fr)

Paquets RPM

Autres systèmes linux : Convertissez les paquets debian avec la commande alien

• Vous pouvez tenter de compiler mkd sur Mac:

Exercices en langage C - GCC standard sur Mac

Sources pour les exercices

Les fichiers ci après sont universels (pour tous les exercices et tous systèmes d'exploitation.)

cpp.c pour exercices

asm.c pour exercices

Autres formats de fichiers

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.

• Inspirez-vous du manuel en français ou en anglais

• 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:

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