Mkd (Extracteur de documents)/Ajouter des modules

Make documents


Maintenancelink={{{link}}}

Cette page est susceptible de subir des modifications occasionnelles

Pourquoi ajouter des modules ?

modifier

Il est aisé d'extraire des fichiers, des lignes complètes, contenant une chaîne déterminée de caractères. Voir la commande Grep et Awk.

Les fichiers de textes sont de plus en plus compliqués, il est difficile d’extraire des blocs de commentaires débarrassés des signes de balisage; d'où l'intérêt de créer des modules adaptés aux langages de programmation ou d'éditions utilisant des balises; Postscript, SGML et autres méta langages; Xml, Html, ... .

Comment ajouter un module ?

modifier

Quel langage de programmation ?

modifier

Tous les langages de programmation peuvent convenir à condition qu'ils soient compilable avec gcc pour produire des fichiers objets liables entre eux (linkables)

Définir le module

modifier

Il faut déterminer quel est le style de commentaire à extraire. Repérer éventuellement un fichier similaire existant. Il existe en standard des modules d' extraction de lignes et des modules d' extraction de blocs.

Certains fichiers ont des commentaires plus compliqués comme : <!-- texte --> avec quatre caractères voire plus. Dans des cas plus complexes il pourrait être préférable de repérer des chaînes de caractères plutôt que des caractères ASCII. Ceci aurait l'avantage d'être adapté aux caractères asiatiques en UTF 8, 16, ou 32 avec des chaînes de caractères données paramètres d'entrée.

Créer le pseudo-code

modifier

Le pseudo code que nous utilisons est un commentaire qui va décrire ce que l'on fait et ce que l'on doit obtenir, ce qu'il faut faire dans certaines conditions comme créer une boucle jusqu'à ce que l'on obtienne ce que l'on cherche.
Il y a de nombreux ouvrages qui décrivent les manières de programmer. Le plus célèbre est sans aucun doute la méthode Merise pour la programmation impérative.

Il est préférable d'écrire le pseudo code avant d'écrire les lignes de codes.

 //O Ceci est un pseudo code style C++
 std::cout << "Unable to open file "<< fprj << std::endl; // message to stdout

Examinez les fichiers à disposition pour avoir une meilleure idée de l'utilisation du pseudo code.

Intégration des lignes de codes

modifier

Langue de programmation et internationalisation

modifier

Nous utilisons gettext pour adapter les messages aux différentes langues parlées.

Pour que l'on puisse facilement traduire les messages il convient de les écrire en anglais US (ASCII).
Les divers caractères accentués des langues européennes ne sont pas si faciles à traduire.

Compilation de l'unité de test

modifier

Les options du fichier version.h

modifier

Le fichier d'entête version.h est utilisé pour compiler la série d'applications dérivées de la commande mkd.
La vérification des options est indispensable avant toute compilation.

La fonction maîtresse - main()

modifier

La fonction main doit ouvrir les fichiers source et cible et transmettre l'adresse de ces fichiers ouverts à la fonction à éprouver (tester).

Elle doit en retour, s'il y a lieu, d'afficher la valeur de retour de fonction à défaut de d'afficher un message correspondant à cette valeur de retour.

Il n'est pas interdit d'ouvrir "en dur" toujours les mêmes fichiers source et cible, cela dépend des tests demandés.
L'essentiel pour les tests unitaires est de répondre aux directives. Il peut cependant être nécessaire d'entrer des arguments comme n, s, t par exemple pour l'épreuve de la fonction cpp_() que nous prenons souvent en exemple.

#include "version.h"
// #include "" // entête du fichier à tester app.h si la fonction est indépendante comme cpp.c
// #include "" // fichier de la fonction app.i si la fonction doit être incluse
// Variables globales:
     unsigned char A,B,C,F,P,S,a,f,j,l,n,p,s,t,v,w;
     char codes[5] = {0,0,0,0,0};
//*O Début de la fontion main():
     int main(int argc, char **argv)
     {
        //O Déclarations
        int ret=0;
        char fsrc[MAX]; /* Nom du fichier source  */
        char fdoc[MAX]; /* Nom du fichier cible   */
        FILE *pnfile;   /* FICHIER A EXTRAIRE   */
        FILE *pfdoc;    /* FICHIER A DOCUMENTER */

        //O Pseudo code des instructions
        .....
        return ret;
      }
//*O Fin de la fontion main()

Exemple complet avec mkdcpp (Éditeur ISO-8859-1)

Le Makefile pour la compilation de l'unité

modifier

Le makefile suivant, mkdcpp.mak complet pour une installation standard a été bridé pour les tests unitaires.

Épreuve unitaire

modifier

Générer la documentation unitaire

modifier
  • La documentation unitaire doit (devrait ?) être intégrée dans le fichier source afin d'être certain que cette documentation concerne CE fichier source.
  • On extrait cette documentation par copier-coller ou avec mkd.
  • Pour une production importante il faut se référer à la norme ISO[1][2]..
  • Pour une petite production, cette documentation unitaire doit fournir les indications suivantes:
  1. FILE NAMES: Nom du fichier et nom de la fonction.
  2. PROJECT: Nom du projet.
  3. INITIAL PROJECT: Projet initial si le projet a changé de nom.
  4. ADMINISTRATIVE RECORD: Nom d'enregistrement dans les archives avec la date, le lieu etc.
  5. UPDATES: Date, auteur, nature de la modification.
  6. RECOMMANDED TESTS: Description des épreuves pour valider la fonction.
  7. Description de la fonction: (Utile pour le manuel man 3)
    1. NAME: Nom de la fonction (Suivi, éventuellement du nom du fichier source, Voir FILES ci après)
    2. SYNOPSIS: ou SYNTAX: fichiers d’entête (#include) return-value function (parameters);
    3. DESCRIPTION: ou ACTION: action détaillée et sa description.
    4. RETURN VALUE: valeurs de retour de la fonction.
    5. CONFORMING TO: ou STANDARDS: POSIX, ANSI C, BSD, ISO/IEC 9899:2011, gcc, MS-VC10, UTF-8, etc.
    6. PORTABILITY: LINUX-Debian-systems, LINUX-Red-Hat, Windows NT, etc.
    7. COPYRIGHT: Droit de copie s'il y a lieu.
    8. AUTHORS: Concepteur, traducteurs, etc. (Éventuellement)
    9. RESSOURCES: Si le projet nécessite des ressources particulières (gtkmm, etc.)
    10. FILES: Fichiers concernés Fichiers d'entête (.h), sources, etc. (où on les trouve)
    11. NOTES: ou recommandations.
    12. BUGS: Erreurs constatées ou erreurs courantes.
    13. SEE ALSO: Voir aussi, au cas où ...

Éprouver le module (Test unitaire)

modifier

Le répertoire des tests unitaire se compose:

  1. Un ou plusieurs fichiers sources. le fichier source peut simplement s'appeler "Source" mais on préfère lui donner un nom qui le distinguera des autre modules lors des tests d'intégration; par exemple "Test_cpp_U.cc"
  2. Un fichier de commande des test que l'on peut appeler "Tests" ou "Test_cpp_U" que l'on rendra exécutable sous linux, sous Windows on utilise l'extension ".bat"
  3. Un fichier de nettoyage "Clean" ou Test_cpp_U.clean. On le rendra exécutable (Même remarque que précédemment)
  4. Un fichier qui donne le résultat de l'analyse "Analysis" en anglais.

Exemple pour le Styles C

modifier
  • /* ... */ : C, C++, C#, PHP, Java, Javascript, CSS, ...
  • // ... NL : C++, C#, PHP, Java, Javascript

Fichiers de tests unitaires de la fonction cpp_() dans mkd

Tests function files: Test_cpp_U.cc, Test_cpp_U.c
Bash commands files: Tests, Tests_Clean

Analyse des tests unitaires

modifier

Éprouver le module unitaire nécessite de répondre aux recommandations des tests contenus dans la documentation.

Exemple de fichier Analysis

Intégration du module

modifier

L'intégration du module se fait par la compilation d'une application qui utilise ce "module", cette fonction: mkd, mkdcpp, mkdcppw par exemple. Le fichier d'entête version.h doit être modifié en fonction des compilateurs et options de compilation.

Ce module peut être intégré par inclusion (#include) avec l'option de compilation gtkmm pour mkdcppw.

Il peut être compilé séparément sous forme d'objet éventuellement intégrable dans une librairie.
Le module objet sera lié (Link) à l'application par la compilation.
Attention : Une fonction intégrée dans une librairie est figée. Il faut alors veiller à proposer un fichier d'entête correspondant à l'objet; on ne peut plus utiliser version.h.

Pour la fonction cpp() par exemple, il faudra proposer un fichier d'entête cpp.h correspondant à la compilation cpp.o

Épreuve d'intégration

modifier
  • Exemple:
  1. Constater que le module se compile bien dans l'application.
  2. Vérifier que le module répond bien aux paramètres d'entrée et qu'il prend en compte les variables globales. Vérifier les valeurs de retour de fonction et l'affichage des messages correspondants.
  3. Reprendre tous les tests unitaires des fonctions avec les fonctions intégrées dans l'application.

Générer la documentation

modifier
  • Déterminer à qui s'adresse cette documentation, par exemple:
  1. Utilisateur final
    Manuels
  2. Concepteurs
    Suivi de la programmation selon les étapes du cycle en V
  3. Programmeurs
    Documentation des fonctions et librairies de fonctions
    Tests unitaires, d'intégration, de validation

Notes et références

modifier
  1. ISO/IEC 26514:2008
  2. ISO/IEC 26514:2008 prévisualisation