Mkd (Extracteur de documents)/La commande mkd avec exercices

Un livre de Wikilivres.
Sauter à la navigation Sauter à la recherche






Mkd (Extracteur de documents)

https://fr.wikibooks.org/wiki/Mkd(Extracteur_de_documents)








Husky puzzle book.svg





Nuvola-inspired File Icons for MediaWiki-fileicon-ps.png

Ceci est la version imprimable de Mkd (Extracteur de documents).

  • Ce livre fait environ 55 (format paysage) pages au format A4 (dans la version du 2016-08-25).
  • Si vous imprimez cette page, choisissez « Aperçu avant impression » dans votre navigateur, ou cliquez sur le lien Version imprimable dans la boîte à outils, vous verrez cette page sans ce message, ni éléments de navigation sur la gauche ou en haut.
  • Cliquez sur Rafraîchir cette page pour obtenir la dernière version du wikilivre.
  • Pour plus d'informations sur les version imprimables, y compris la manière d'obtenir une version PDF, vous pouvez lire l'article Versions imprimables.
Éditeurs européens de logiciels libres
mkd, commande UNIX
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)

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


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

Générer la documentation logicielle

Ce livre doit être rangé sur l'étagère Wikilivres Informatique
Systèmes d'exploitation, langages informatiques, logiciels CDU/6/68/681/681.3/681.3.0

Introduction

Mkd-256x256.png

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 sources compilables sont disponibles pour Windows, Unix, Linux.
Les binaires sont disponibles pour:

Windows[3] équipés de processeurs 32 et 64 bits.
Unix/Linux équipés de processeurs 32 bits x86 (i386), et 64 bits (amd64).
Les paquets d'installation sont disponibles pour les sytèmes à base Debian, Ubuntu, à télécharger[4].
Les paquets RPM pour les systèmes RED-HAT sont disponibles en téléchargement sur le serveur de l'EELL[5]
Les paquets Debian peuvent être convertis pour d'autres systèmes avec Alien[6]

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:
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)[7]
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[8] )

Fichiers

Traductions

Il existe des traductions sous unix / linux: Voir la page Traductions Internationales

  • Les manuels formatés nroff existent pour anglais allemand français et sont prévus pour espagnol italien
  • Voir aussi la documentation de gettext[9] 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[10] European Union Public Licence totalement compatible avec GNU

Bugs

Mise à jour des 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).

Consultez également ces pages dans d’autres projets Wikimedia :

Article encyclopédique sur Wikipédia.


Notes et références

  • Notes Style de langage[11]:

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
  1. ISO/IEC 26514:2008
  2. ISO/IEC 26514:2008 prévisualisation
  3. mkd pour Windows
  4. Launchpad
  5. Téléchargement RPM sur le serveur de l'EELL
  6. Site officiel du convertisseur de paquets Alien
  7. GmanEdit (Gnome manpage editor)
  8. Package redistribuable Visual C++ 2010 (x86)
  9. gettext
  10. Licence Publique de l'Union Européenne (fichier pdf)
  11. https://fr.wikipedia.org/wiki/Commentaire_(informatique)





Mkd (Extracteur de documents)

Deuxième partie :

EXERCICES

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: 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ésulat 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]:

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

  1. wikipedia:Assembleur#Macro-assembleur

Comprendre les options de la commande mkd

Make documents

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

Commande: mkd -Cws H cpp.c


Commande: mkd -Cwts H cpp.c


Résumé des observations sur les options s, t, v


Créez ou écrasez le fichier cible de l'organigramme cpp.organigramme


Crééz ou écrasez le fichier de documentation logicielle html du fichier cpp.c


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

Make documents

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


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.


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


Mettre à jour l'organigramme de chaque fichier de programme

Pseudo-code; Code de repérage 'O',
asm.org, cpp.org, putchar.org


Mettre à jour la structure de chaque fichier

avec le pseudo code. Code 'S' et 'O' et 'w',
asm.struct

putchar.struct

Mettre à jour la documentation globale pour les programmeurs

avec les dates de mise à jour etc. Code 'P'
exercice.info_programmeurs


Mettre à jour de la documentation logicielle globale

(Conception détaillée, Tests unitaires, du cycle en V) Code 'D'
exercice.docu

Notes et références

Codes QR des téléchargements

Maintenance
link={{{link}}}

Cette page est susceptible de subir des modifications occasionnelles

Make documents

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.