Projet mkd/mkd/Aide

De Wiki EELL.

(Différences entre les versions)
m (Ajout de la section mkddocu)
m (Générer la documentation avec mkddocu : Mise à jour)
 
Ligne 134 : Ligne 134 :
== Générer la documentation avec mkddocu ==
== Générer la documentation avec mkddocu ==
-
'''mkddocu''' est un utilitaire introduit avec les versions mkd de 2014.  
+
'''mkddocu''' est un utilitaire introduit avec les versions mkd de 2014. '''(mkd-doc_140515_all.deb)'''
Cet utilitaire facilite l'édition de la documentation logicielle standard.  
Cet utilitaire facilite l'édition de la documentation logicielle standard.  
-
Il suffit de se placer avec un terminal dans le répertoire des sources du projet et de lancer la commande mkdocu.
+
On place la commande mkddocu dans le fichier de compilation ou dans le Makefile. La documentation est ainsi régénérée à chaque compilation après correction des fichiers du répertoire source.
-
Il est aussi possible de copier le shell mkddocu dans le répertoire des sources et le renommer pour éviter les interférences (mkddoc.sh). Shell que l'on peut adapter à volonté.
+
On peut aussi se placer avec un terminal dans le répertoire des sources du projet et de lancer la commande '''mkddocu'''.
-
<pre>mkddocu(1)                    Linux User's Manual                  mkddocu(1)
+
Il est aussi possible de copier le shell '''/usr/bin/mkddocu''' dans le répertoire des sources et le renommer (mkddoc.sh) pour éviter les interférences avec mkddocu. Shell que l'on peut adapter à volonté.
-
 
+
Voir le [[Shell_command_projects/mkd#Manuel_mkddocu_en_fran.C3.A7ais|manuel de mkddocu]]<br>
-
 
+
Voir aussi la discussion [http://edeulo.free.fr/phpBB3/viewtopic.php?f=16&t=323&p=382#p382 mkd 140515 disponible]
-
NOM
+
-
      mkddocu - Génère la documentation informatique avec mkd (1).
+
-
 
+
-
SYNOPSIS
+
-
      mkddocu projet
+
-
 
+
-
DESCRIPTION
+
-
      mkddocu
+
-
              La  commande  mkddocu  associée  à mkd, extrait les commentaires
+
-
              codés par un caractère de  repérage  pour  créer  les  documents
+
-
              logiciels.  Exemple  :  //D  ceci  est  un commentaire php ou C,
+
-
              répéré par le caractère 'D'
+
-
              Si des fichiers de langage C sont présents,  mkddocu  génère  un
+
-
              fichier d'entête global (header) du projet informatique grâce au
+
-
              caractère de repérage 'H'.
+
-
              Caractère de repérage :
+
-
              D Extrait la documentation générale.
+
-
              H Crée le fichier d'entête global (header) si un fichier  C  est
+
-
              présent.
+
-
              P  Extrait  un document utile aux mainteneurs, noms, dates, ver‐
+
-
              sions, etc.
+
-
              T Extrait le  document  des  directives  de  tests.  (Unitaires,
+
-
              d'intégration, etc.)
+
-
 
+
-
      projet C'est  sous  ce nom_de_projet que seront crées ou mis à jour les
+
-
              fichiers du répertoire 'maintenance/nom_de_projet'
+
-
 
+
-
VALEURS RETOURNÉES
+
-
        0 Fin normale à la fin de l'exécution de  la  commande  ou  de  l'aide
+
-
      (syntaxe).
+
-
      -1 La commande mkd n'est pas installée.
+
-
      -2  Command  stoppée. La  sauvegarde  de la série de documents dans le
+
-
      répertoire Backups n'a pas été effectuée.
+
-
      -3 Command stoppée. Le paramètre project est vide.
+
-
 
+
-
EXEMPLES
+
-
      L'auto-documentation de cette commande se crée avec le fichier d'origne
+
-
      des sources mkddocu.sh. Lancer la commande :
+
-
      mkddocu.sh mkddocu
+
-
      Le répertoire maintenance/mkddocu contiendra les documents.
+
-
 
+
-
      Les  répertoires de projet sont générés par séries et peuvent avoir été
+
-
      sauvegardés dans un répertoire  maintenance/Backups  si  le  nombre  de
+
-
      fichiers de projet de la série a atteind la limite BACKUPSMAX
+
-
      Pour  les  essais  on  peut  limiter  BACKUPSMAX à 2 (3 sauvegardes par
+
-
      série.)
+
-
 
+
-
REMARQUES
+
-
      BACKUPSMAX est normalement fixé à 9 mais peut être modifié par  édition
+
-
      du fichier : /usr/bin/mkddocu.
+
-
 
+
-
VOIR AUSSI
+
-
      mkd(1) xgettext(1) poedit(1)
+
-
      file:////usr/share/doc/mkddocu/
+
-
      file:////usr/share/doc/mkd/
+
-
 
+
-
TÉLÉCHARGEMENTS
+
-
      http://edeulo.free.fr
+
-
 
+
-
AUTEURS
+
-
      Clara, JPL, Luca
+
-
      Email : http://edeulo.free.fr/contacts/formmail.php
+
-
 
+
-
BUGS
+
-
      Rapports de bugs :  http://edeulo.free.fr/phpBB3/viewforum.php?f=14
+
-
 
+
-
 
+
-
 
+
-
                                  2014-02-24                        mkddocu(1)
+
-
</pre>
+
[[Catégorie:Documentation]]
[[Catégorie:Documentation]]
[[Catégorie:Mkd]]
[[Catégorie:Mkd]]

Version actuelle en date du 13 décembre 2014 à 15:04

Retour vers Shell_command_projects/mkd

Sommaire

Exemple d'utilisation

Fichiers de fonctions

Quand c'est possible on écrit chaque fonction d'une application dans un fichier séparé.
Quand les fonctions sont regroupées dans un même fichier, la documentation des fonction apparaîtra dans le même ordre que dans le fichier.

Dans le fichier de la fonction on précise sa syntaxe d'utilisation et son usage (header).

Exemple pour la fonction cpp_ : dans le fichier cpp_.c
Notez qu'il est préférable d'écrire en anglais pour une meilleure traduction.
Voir l'aide en anglais.

/*P
     fichier cpp_.c 
     Directives programmeurs (cycle en V)
     Dernière date de modification et nom du programmeur
*/

/*D 
	fonction cpp_
 -----------------------------------------------------------------------------
 ACTION:
	La fonction cpp_ lit le fichier source (pnfile) qui est transmis en 
	paramètre et décode les lignes de commentaires pré-codés dans le style 
	c++ puis les transcrit dans le fichier de destination (pfdoc).
	Les variables globales sont les '''codes''' et les '''options''' définis 
        dans la fonction appelante:
	Les codes, tableau de 5 caractères: 
		extern char codes[]; 
		ils doivent être définis dans le programme d'appel:
		char codes[5] = {0,0,0,0,0};
	Les options, n,s,t,v.
		extern unsigned char n,s,t,v;
		elles doivent définies dans le programme d'appel:
		unsigned char n=0,s=0,t=0,v=0;
	Avec les options :
	n: La transcription est précédée du numéro de ligne. Ceci permet 
		d'atteindre facilement la ligne commentée.
	t: Avec l'option t seul le texte commenté est recopié.
		Sans l'option t le commentaire est entièrement recopié.
		Cette option t permet donc de générer des documents directement 
		exploitables ou publiables.
	s: ajoute le commentaire à l'écran et permet les redirections > , >> ,
           ou || etc.
	v: mode bavard
	Remarque :
	Si la détection d'un commentaire à transcrire commence par les caractères
        /* il sera transcrit jusqu'à rencontrer les caractères */ quels que 
        soient les commentaires lignes inclus dans ce commentaire.
	Si la détection d'un commentaire commence par les caractères //, la ligne 
	commentaire sera copiée jusqu'au prochain retour à la ligne (NL) ou fin 
        de fichier (EOF).
	Ces dispositions facilitent la génération automatique des fichiers 
	d'entête fichier.h ou .hpp etc.

 SYNTAXE:
	#include "version.h"
	#include "cpp_.h"
	int cpp_(FILE * pfdoc, FILE * pnfile);

 PORTABILITE:
	Microsoft Visual studio sous Windows : x86(Win32) x64(Win32 et WIN64)
	gcc sous Unix/Linux.

 DESCRIPTION:
	cpp_ fonction
	FILE * pfdoc: pointeur sur le fichier de destination ouvert par le 
	programme appelant.
	FILE * pnfile: pointeur sur le fichier source ouvert par le programme
	appelant

 VALEUR RETOURNEE:
	Retourne 0 en cas de succès.

 DROIT DE COPIE: (précisé dans version.h) :
*/

/*H  
	// cpp_.c:
	extern int cpp_ (FILE * pfdoc, FILE * pnfile);
*/
     int cpp_ (FILE * pfdoc, FILE * pnfile)
     {//S Fonction début
       ... // Lignes de programme
     }//S Fonction fin

Fichiers de commande et Makefile

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')

Dans les exemples qui suivent on utilise les caractères H et D pour générer la documentation.
Il est d'usage d'utiliser:

  • D ou F Fonctions - pour générer le fichier documentaire des fonctions
  • G Général - doc générale
  • H Header pour générer le fichier d'entête .h
  • M Manuel (En anglais. Sous Unix / Linux : « Man (1) » ou autre )
  • O Organigramme ou pseudo-code
  • P Programmeurs - doc programmeurs (cycle en V)
  • S Structure - {/*S*/ ... ou avec "//" }//S
  • U Utilisateurs - doc. destinée aux utilisateurs
  • e note en anglais
  • f note en français
  • w warnings - Attention !

Tous les caractères ASCII sont utilisables, lettres et chiffres.

 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.

Exemple de lignes dans un Makefile.
Dans cet exemple le Makefile se trouve dans le répertoire des fichiers sources du projet.

APP = MyProgram # This is any "macro"

Create_header_and_functions-doc: # here, this is any unconditional directive. 
     if [ -e "/usr/bin/mkd" ]; \ # Warning: the first char is a tabulation and not spaces
     then \
          ls -1 *.cpp > $APP.prj; \       # first create or overwrite new project file
          mkd -Ctw H $APP.prj $APP.h: \   # create or overwrite header file
          mkd -Ctw D $APP.prj $APP.txt: \ # create or overwrite functions documentation
          mkd -Cwn w $APP.prj $APP.wars; \# create or overwrite warnings doc. for programmers
     else \
          @echo "The mkd command is not found in /usr/bin directory"; \
     fi

Générer la documentation avec mkddocu

mkddocu est un utilitaire introduit avec les versions mkd de 2014. (mkd-doc_140515_all.deb)

Cet utilitaire facilite l'édition de la documentation logicielle standard.

On place la commande mkddocu dans le fichier de compilation ou dans le Makefile. La documentation est ainsi régénérée à chaque compilation après correction des fichiers du répertoire source.

On peut aussi se placer avec un terminal dans le répertoire des sources du projet et de lancer la commande mkddocu.

Il est aussi possible de copier le shell /usr/bin/mkddocu dans le répertoire des sources et le renommer (mkddoc.sh) pour éviter les interférences avec mkddocu. Shell que l'on peut adapter à volonté.

Voir le manuel de mkddocu
Voir aussi la discussion mkd 140515 disponible

Outils personnels