actualisation de la doc Doc/doc_procedure_verification.tex suite a la creation du script Perl/genere_catalogue_tests.pl (nouvelles recommandations a signaler aux utilisateurs pour l ecriture des fichiers README)

Doc/doc_procedure_verification.tex

@@ -95,6 +95,7 @@ citecolor= green %couleur citation biblio
 
 \tableofcontents
 
+\clearpage
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -160,7 +161,6 @@ La proc
 
 %%
 \clearpage
-\newpage
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \section{Organisation des tests}\label{section_organisation_tests}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -205,7 +205,6 @@ On distingue actuellement deux sortes de tests selon le temps de calcul : les te
 
 %%
 \clearpage
-\newpage
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{Lancement et vérification d'un test}
 
@@ -266,15 +265,30 @@ Les fichiers facultatifs en lien avec l'ex
 \item[$\bullet$] les fichiers donnant les arguments à l'exécutable Herezh++ (fichiers~d'extension~\verb|.argument|[i])\\
 \end{itemize}
 
-D'autres fichiers facultatifs peuvent \^etre contenus dans un répertoire de test. Il n'y a pas de restriction mis à part qu'un répertoire de test ne doit pas contenir des fichiers trop lourd en terme d'espace disque. Typiquement, il peut \^etre utile d'ajouter les fichiers suivants :
+D'autres fichiers facultatifs peuvent \^etre contenus dans un répertoire de test. Il n'y a pas de restriction mis à part qu'un répertoire de test ne doit pas contenir des fichiers trop lourds en terme d'espace disque. Typiquement, il peut \^etre utile d'ajouter les fichiers suivants :
 \begin{itemize}
 \item[$\bullet$] des fichiers de mise en données du test pour d'autres codes de calcul (par exemple : fichier \verb|.inp| pour Abaqus)
 \item[$\bullet$] des fichiers donnant des résultats donnés par d'autres codes de calcul ou par des solutions analytiques (bien que le fichier \verb|README| puisse \^etre utilisé pour écrire ces données)
 \end{itemize}
 
 \clearpage
-\newpage
 \begin{figure}[!h]
+{\color{brown} 
+\begin{verbatim}
+------------------------------------------------------------
+Auteur
+------------------------------------------------------------
+liste des auteurs sous la forme : Prenom Nom (email)
+remarque : un auteur par ligne
+
+------------------------------------------------------------
+Mots-cles
+------------------------------------------------------------
+liste des mots-cles (un par ligne)
+remarque : un mot-cle peut contenir des espaces
+           (exemple : contraintes planes)
+\end{verbatim}
+}
 {\color{blue} 
 \begin{verbatim}
 ------------------------------------------------------------
@@ -289,11 +303,6 @@ du texte...
 \end{verbatim}
 }
 \begin{verbatim}
-------------------------------------------------------------
-Mots-cles
-------------------------------------------------------------
-du texte...
-
 ------------------------------------------------------------
 Grandeurs de comparaison
 ------------------------------------------------------------
@@ -315,11 +324,18 @@ Comparaison avec des codes de calcul
 du texte...
 
 \end{verbatim}
-\caption{Trame du fichier README présent dans chaque répertoire de test. \underline{Les deux rubriques en bleu sont obligatoires}}
+\caption{Trame du fichier README présent dans chaque répertoire de test. {\color{blue} Les rubriques en bleu sont \underline{obligatoires}.} {\color{brown} Les rubriques en marron sont importantes pour la traçabilité des tests mais non obligatoires.}}
 \label{format_fichier_README}
 \end{figure}
 \clearpage
-\newpage
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Recherche de tests}\label{section_recherche_de_tests}
+
+Un document pdf de nom \verb|documentation_tests.pdf| est présent à la racine du projet CVS. Il dresse la liste actuelle des tests et résume en quelques phrases leur contenu. Un index en fin de document permet de faire une recherche par mot-clé.\\
+
+Ce document est rédigé automatiquement sur la base du contenus des fichiers README montré sur la figure \ref{format_fichier_README}.
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -328,14 +344,15 @@ du texte...
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{Vue d'ensemble}
-Globalement, créer un nouveau test consiste à ajouter un nouveau répertoire dans le répertoire \verb|Batterie|. Le choix de son emplacement dans l'arborescence est libre en s'inspirant tout de m\^eme des descriptifs donnés en section \ref{section_classement_tests}. Le contenu du répertoire est celui défini en section \ref{section_contenu_repertoire_test}. 
+Créer un nouveau test consiste à ajouter un nouveau répertoire dans le répertoire \verb|Batterie|. Le choix de son emplacement dans l'arborescence est libre en s'inspirant tout de m\^eme des descriptifs donnés en section \ref{section_classement_tests}. Le contenu du répertoire est celui défini en section \ref{section_contenu_repertoire_test}. 
 Les fichiers facultatifs dépendent du type de traitement Herezh++. Dans tous les cas, l'arborescence du répertoire de test est de la forme montrée sur la figure \ref{arbo_repertoire_test} et les règles suivantes sont à respecter :
 \begin{itemize}
 \item[$\bullet$] Le nom du nouveau répertoire est choisi en utilisant uniquement les lettres de a à z, les chiffres de 0 à 9, le signe moins "-" et le tiret bas "\_". Si le test est un test "Rapide" (moins de 30 secondes), le nom commence par \verb|Test_R|, sinon il commence par \verb|Test_L|.
 \item[$\bullet$] Un seul fichier d'extension \verb|.info| doit \^etre présent dans le répertoire. Ce fichier doit \^etre présent m\^eme s'il est vide.
 \item[$\bullet$] Pour chaque calcul, il est nécessaire de créer un fichier \verb|.CVisu| (\verb|.CVisu1|, \verb|.CVisu2|, etc...) m\^eme si celui-ci est vide. Ces fichiers servent non seulement à Herezh++ mais également au script \verb|Perl/test.pl| pour repérer les calculs à lancer (un calcul par fichier \verb|.CVisu|).
 \item[$\bullet$] tous les fichiers \verb|.CVisu|[i] et les fichiers facultatifs nécessaires à l'exécution d'un test (\verb|.verif|[i], \verb|.commande|[i], etc...) ont la m\^eme racine que le fichier \verb|.info| (par exemple, si on a le fichier \verb|nom_fichier.info|, l'éventuel fichier \verb|.verif1| doit avoir pour nom \verb|nom_fichier.verif1|)
-\item[$\bullet$] le fichier \verb|README| contient obligatoirement les rubriques \it But du test \rm et \it Description du calcul \rm montrées sur la figure \ref{format_fichier_README}. Ces deux rubriques serviront à générer automatiquement une documentation pdf (catalogue de tests).\\
+\item[$\bullet$] le fichier \verb|README| contient obligatoirement les rubriques \it But du test \rm et \it Description du calcul \rm montrées sur la figure \ref{format_fichier_README}. Ces deux rubriques serviront à générer automatiquement une documentation pdf (catalogue de tests). Dans le m\^eme but, les rubriques \it Auteur \rm et \it Mots-cles\rm, qui ne sont pas obligatoires, donnent des informations précieuses (merci de les renseigner).
+\item[] Remarque importante : ne pas écrire des lignes de tirets (\verb|---| et plus) dans le corps d'une rubrique.\\
 \end{itemize}
 
 
@@ -406,7 +423,7 @@ La sous-section \ref{section_commandes_CVS} est un rappel des commandes CVS de b
 
 \begin{itemize}
 \item[$\bullet$] \verb|README| :\\
-La trame du fichier est montrée sur la figure \ref{format_fichier_README}. La syntaxe de l'intitulé des deux rubriques obligatoires (en bleu) doit \^etre strictement respectée. Les autres rubriques sont indiquées à titre de proposition et pour des questions d'harmonie sur la forme d'un test à l'autre.\\
+La trame du fichier est montrée sur la figure \ref{format_fichier_README}. La syntaxe de l'intitulé des deux rubriques obligatoires (en bleu) doit \^etre strictement respectée. Il est fortement encouragé de renseigner les rubriques \it Auteur \rm et \it Mots-cles\rm. Les autres rubriques sont indiquées à titre de proposition et pour des questions d'harmonie sur la forme d'un test à l'autre. Comme montré sur la figure \ref{format_fichier_README}, chaque titre de rubrique est précédé et suivi d'une ligne d'au moins trois tirets (\verb|---| et plus). Les lignes de tirets  doivent \^etre réservées aux titres des rubriques (Ce motif sert à repérer la fin d'une rubrique. L'insertion d'une ligne de tirets dans le corps d'une rubrique mettra en défaut le script de génération automatique de la documentation!!).\\
 \item[$\bullet$] \verb|.info| :
 \begin{itemize}
 \item[] Ce fichier est l'unique fichier d'extension \verb|.info| présent dans le répertoire. Il est obligatoire mais peut \^etre vide (par exemple dans le cas d'un création de fichier \verb|.info| avec l'option Herezh \verb|-n|).\\
@@ -589,12 +606,17 @@ L'arborescence pour ce genre de test devrait avoir la forme suivante :\\
 
 
 %%
-\newpage
 \clearpage
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \section{Évolution des mises à jour}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
+\begin{itemize}
+\item[$\bullet$] 2015-06-29 (Julien Troufflard) :
+\begin{itemize}
+\item[-]création d'un nouveau script (\verb|Perl/genere_catalogue_tests.pl|). Il génère automatiquement une documentation sur les tests (résumé et index pour recherche par mots-clés). Ce document est placé à la racine du projet sous le nom \verb|documentation_tests.pdf|. Le mode de fonctionnement (lecture des fichiers README de chaque test) impose une nouvelle contrainte sur la forme des fichiers README (interdiction d'utiliser des lignes de 3 tirets ou plus dans le corps d'une rubrique README car ce motif signifie la fin d'une rubrique). Cette contrainte est le choix actuel mais peut \^etre modifié à tout moment en définissant une balise de fin de rubrique à utiliser dans les fichiers README (par exemple : \verb|fin_rubrique|) et en indiquant sa syntaxe dans la variable \verb|$MOTIF_FIN_RUBRIQUE| du script \verb|Perl/genere_catalogue_tests.pl|.\\
+\item[-]Apparition d'une nouvelle rubrique README : \it Auteur \rm (renseigne le ou les auteurs du test avec prénom, nom, adresse mail). rubrique qui appara\^it dans la documentation des tests.
+\end{itemize}%tiret
+\end{itemize}%bullet