May 16, 2014 12:28:36 PM lutece lutece avatar   628    

Lutèce : Normes de Documentation

Normes de documentation


La documentation de Lutèce est écrite au format XML, puis est générée à l'aide de Mavenaux formats HTML et PDF.

Un nombre limité de balises est utilisé, afin de permettre une mise en page homogène dans les deux formats.

Créer une documentation : les règles de base

L'encoding utilisé est UTF-8, les chapitres sont découpés en section et subsection .

Le code HTML inclu dans ces chapitres ne doit pas utiliser la balise <br> , mal interpretée lors de la génération PDF. La balise <p> est donc à utiliser pour effectuer des retours à la ligne.

Les tables doivent comporter au mmoins un titre en première ligne( <th> )

Les images doivent mesurer 780px de large (centrer l'image sur fond blanc), et être créées au format .gif .

Exemples de mise en oeuvre

Structure globale du fichier :

<?xml version=1.0 encoding=UTF-8?>
    <document>
        <properties>
            <title>Lutèce : titre du document</title>
        </properties>
        <body>

            <section name=Titre de chapitre 1>
                ...................
            </section>

        </body>
    </document>

Un document peut contenir plusieurs sections.

Une section peut contenir du texte formaté par un paragraphe (<p> ), ainsi qu'une ou plusieurs sous-section(s)

Exemple :

<section name=Titre de chapitre 1>
        <p>
            Introduction du chapitre 1
        </p>

        <subsection name=Sous-chapitre 1>
            <p>
                    texte ...
            </p>
        </subsection> 

        <subsection name=Sous-chapitre 2>
            <p>
                texte ...
            </p>
        </subsection> 

    </section>

Le résultat est le suivant :

Titre de chapitre 1


Introduction du chapitre 1

Sous-chapitre 1

texte ...

Sous-chapitre 2

texte ...

Il est possible d'inclure une liste dans un paragraphe :

<p>
      <ul>
         <li>exemple de liste 1</li>
         <li>exemple de liste 2</li>
      </ul>
   </p>

   <p>
      <ol>
         <li>exemple de liste numérotée 1</li>
         <li>exemple de liste numérotée 2</li>
   </ol>
</p>

Résultat :

  • exemple de liste 1
  • exemple de liste 2
  • exemple de liste numérotée 1
  • exemple de liste numérotée 2

Le texte peut être formaté avec des balise du type <strong> , <em> , <code>

<p>
      <code>texte au format code</code>
   </p>
   <p>
      <strong>texte au format strong</strong>
   </p>
   <p>
      <em>texte au format em</em>
   </p>

Résultat :

  • texte au format code
  • texte au format strong
  • texte au format em

Des exemples de code peuvent être introduit à l'aide de la balise <pre> :

<p> 
   <div class=source>
   <pre>
<application>
   <application-class>fr.paris.lutece.plugins.securedtest.SecuredTestApp</application-class>
   <application-security-model>1</application-security-model>
</application>
   </pre>
   </div>
   </p>

Attention : pour que le rendu soit conforme lors de l'utilisation de la balise <pre> , il faut coller le texte à gauche, sans tenir compte de l'indentation générale du code xml du fichier.

Le résultat est :

<application>
    <application-class>fr.paris.lutece.plugins.securedtest.SecuredTestApp</application-class>
    <application-security-model>1</application-security-model>
 </application>

Pour insérer un tableau, la syntaxe est la suivante :

<p>
        <table>
            <tr>
                <th>Titre 1</th>
                <th>Titre 2</th>
            </tr>
            <tr>
                <td>Colonne 1</td>
                <td>Colonne 2</td>
            </tr>
        </table>
    </p>

Ce qui donne le tableau suivant :

Titre 1Titre 2
Colonne 1Colonne 2

Pour afficher une copie d'écran :

<p>
        <center>
            <img src=images/logo_lutece.gif />
        </center>
    </p>

La balise <center> n'est prise en compte que pour la génération HTML.

Pour que l'image ne soit pas déformée dans la version PDF, une astuce consiste à créer l'image utilisée pour la génération de ce format sur une taille de 780px de large (pour un format de sortie A4), la copie d'écran étant centrée dans cette largeur.