# Mkd (Extracteur de documents)/Ajouter des modules

Cette page est susceptible de subir des modifications occasionnelles

## Pourquoi ajouter des modules ?

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 ?
### Quel langage de programmation ?

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

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

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.
Examinez les fichiers à disposition pour avoir une meilleure idée de l'utilisation du pseudo code.

### Intégration des lignes de codes
#### Langue de programmation et internationalisation

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
### Les options du fichier version.h

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

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.
Exemple complet avec mkdcpp (Éditeur ISO-8859-1)
mkdcpp.c

### Le Makefile pour la compilation de l'unité

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

## Épreuve unitaire
### Générer la documentation unitaire

* 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..
* Pour une petite production, cette documentation unitaire doit fournir les indications suivantes:
* FILE NAMES: Nom du fichier et nom de la fonction.
* PROJECT: Nom du projet.
* INITIAL PROJECT: Projet initial si le projet a changé de nom.
* ADMINISTRATIVE RECORD: Nom d'enregistrement dans les archives avec la date, le lieu etc.
* UPDATES: Date, auteur, nature de la modification.
* RECOMMANDED TESTS: Description des épreuves pour valider la fonction.
* Description de la fonction: (Utile pour le manuel man 3)
** NAME: Nom de la fonction (Suivi, éventuellement du nom du fichier source, Voir FILES ci après)
** SYNOPSIS: ou SYNTAX: fichiers d’entête (#include) return-value function (parameters);
** DESCRIPTION: ou ACTION: action détaillée et sa description.
** RETURN VALUE: valeurs de retour de la fonction.
** CONFORMING TO: ou STANDARDS: POSIX, ANSI C, BSD, ISO/IEC 9899:2011, gcc, MS-VC10, UTF-8, etc.
** PORTABILITY: LINUX-Debian-systems, LINUX-Red-Hat, Windows NT, etc.
** COPYRIGHT: Droit de copie s'il y a lieu.
** AUTHORS: Concepteur, traducteurs, etc. (Éventuellement)
** RESSOURCES: Si le projet nécessite des ressources particulières (gtkmm, etc.)
** FILES: Fichiers concernés Fichiers d'entête (.h), sources, etc. (où on les trouve)
** NOTES: ou recommandations.
** BUGS: Erreurs constatées ou erreurs courantes.
** SEE ALSO: Voir aussi, au cas où ...

### Éprouver le module (Test unitaire)

Le répertoire des tests unitaire se compose:
* 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"
* 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"
* Un fichier de nettoyage "Clean" ou Test_cpp_U.clean. On le rendra exécutable (Même remarque que précédemment)
* Un fichier qui donne le résultat de l'analyse "Analysis" en anglais.

#### Exemple pour le Styles C

* /* ... */ : 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
File Test_cpp_U.c
File Tests
File Tests_Clean

### Analyse des tests unitaires

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

## Intégration du module

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

* Exemple:
* Constater que le module se compile bien dans l'application.
* 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.
* Reprendre tous les tests unitaires des fonctions avec les fonctions intégrées dans l'application.

## Générer la documentation

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

## Notes et références

* ↑ ISO/IEC 26514:2008
* ↑ ISO/IEC 26514:2008 prévisualisation