Référence

Cette section est un court guide au éléments les plus utilisés d'AlcoveBook. Pour un détail plus exhaustif, voir la AlcoveBook DTD.

Élément d'en-tête d'article

Tous les articles d'AlcoveBook doivent contenir un en-tête d'article. Cet en-tête contient des informations comme le titre de l'article, un historique des révisions, un résumé et ainsi de suite. Notez que l'ordre de ces éléments n'est pas important, mais certains éléments ne doivent apparaître qu'une seule et unique fois (title, subtitle, date, revhistory), certains peuvent apparaître plusieurs fois (abstract, invpartnumber) et tous les autres doivent être groupés lorsqu'ils apparaissent plusieurs fois (par exemple, vous ne pouvez insérer un élément corpauthor entre deux éléments author).

L'en-tête

L'élément articleinfo contient tous les autres éléments qui composent l'en-tête de l'article.

Le titre de l'article

L'élément title trouvé dans l'en-tête de l'article définit le titre de l'article. Ainsi, si vous écrivez un article appelé Le Nécromicon, votre en-tête ressemblera à ceci:

Exemple 13. Exemple de titre d'article

	    
<article lang="fr">
  <articleinfo>
    <title>Le Nécromicon</title>
    ...
  </articleinfo>
</article>
	    
	  

L'auteur de l'article

L'élément author contient toutes les informations relatives à l'auteur, ce qui inclut son nom, son prénom, son surnom, son adresse email, son affiliation à une organisation, etc. Chacune de ces informations est formatée séparément dans un sous-élément de l'élément author. Cela peut sembler lourd, mais ça en vaut la peine: plus le marquage est détaillé, plus de l'information utile peut être extraite du document (par exemple, produire une liste des documents produits par chaque inidividu dans une entreprise serait complexe si les informations ne sont pas assez structurées).

Voici un exemple d'en-tête d'article avec le prénom et le nom de l'auteur, ainsi que son adresse email et son organisation:

Exemple 14. Exemple de renseignement de l'auteur

	    
<articleinfo>
  ...
  <author>
    <firstname>Benjamin</firstname>
    <surname>Drieu</surname>
    <affiliation>
      <orgname>Alcôve Worldwide Inc.</orgname>
      <address>
        <email>Benjamin.Drieu@fr.alcove.com</email>
      </address>
    </affiliation>
  </author>
  ...
</articleinfo>
	  

Note : Il est possible de spécifier plusieurs auteurs pour un article, il suffit de les placer les uns à la suite des autres, dans autant d'éléments author qu'il y a d'auteurs.

Historique des révisions

La plupart des documentations techniques font l'objet d'une série de révisions au fur et à mesure que l'auteur améliore et met à jour le document. Afin que les lecteurs sachent quelle version ils sont en train de lire, la documentation technique utilise souvent un numéro de version ainsi que d'autres informations comme la date de modification. Dans un article AlcoveBook, l'information de révision fait partie de l'en-tête de l'article et est contenue dans l'élément revhistory. Ainsi, par exemple:

Exemple 15. Exemple d'historique des révisions

	    
<articleinfo>
  ...
  <revhistory>
    <revision>
      <revnumber>0.1</revnumber>
      <date>17 août 2001</date>
      <revremarks>
        Premier draft
      </revremarks>
    </revision>

    <revision>
      <revnumber>0.2</revnumber>
      <date>23 août 2001</date>
      <revremarks>
        Mise à jour de la section 1.
      </revremarks>
    </revision>
  </revhistory>
  ...
</articleinfo>
	  

Parmi les éléments disponibles dans un contexte revision:

  • revnumber, le numéro de version de la révision ;

  • date, la date de la révision ;

  • revremarks, une courte description des modifications apportées par rapport à la révision précédente.

Avertissement

Notez que l'ordre des révisions est croissant, c'est à dire que les révisions les plus récentes doivent se trouver à la fin de la liste des révisions.

Résumé de l'article

Un résumé de l'article est toujours de très bon goût afin d'indiquer au lecteur le sujet de l'article. Dans un article AlcoveBook, le résumé fait partie de l'en-tête et est contenu dans un élément abstract.

Exemple 16. Exemple de résumé d'article

	    
<articleinfo>
  ...
  <abstract>
    <para>Cet article explique en profondeur la méthodologie à suivre
      pour cuisiner le lapin en gibelotte.  Après avoir passé en revue
      la liste des ingrédients ainsi que les aspects fonctionnels
      nécessaires, il détaille la succession de manipulations
      nécessaires pour obtenir le plat complet.  Enfin, nous concluons
      par une suggestion de présentation du produit final.
    </para>
  </abstract>
  ...
</articleinfo>
	  

Informations légales et corporates

Spécifier le client destinataire

L'élément contractsponsor permet de spécifier le client destinataire de ce document.

Coordonnées corporate

Le nom de la société émettrice du document peut être renseigné dans l'élément corpauthor, situé apres l'abstract. Comme nous ne disposons pas encore de marquage pour renseigner l'adresse dans un élément corpauthor, les coordonnées d'Alcôve doivent elles être placées juste après, dans l'élément address. Ci-après un exemple complet, que nous vous conseillons d'utiliser systématiquement:

Exemple 17. Exemple de spécification des coordonnées de l'émetteur

	    
<corpauthor>
  <ulink url="http://www.alcove.com/">Alcôve</ulink>
</corpauthor>
<address>
  153, <street>Boulevard Anatole France</street>
  <postcode>93200</postcode> 
  <city>Saint Denis</city>
  <country>France</country>
    Tel: <phone>+33 1 49 22 68 00</phone>
    Fax: <phone>+33 1 49 22 68 01</phone>
</address>
	    

Copyright

Tous les documents produits par Alcôve doivent posséder un copyright, normalement le double copyright de la société Alcôve elle-même et celui de l'ingénieur qui écrit la documentation en question (demander confirmation au responsable du projet, des exceptions peuvent exister).

Le copyright est décrit dans l'élément copyright et les conditions de distribution dans l'élément legalnotice. Ainsi, pour un document placé sous les termes de la licence GNU FDL:

Exemple 18. Exemple de copyright et de termes de distribution

	    
<copyright>
  <year>2001</year>
  <holder>Alcôve et Benjamin Drieu</holder>
</copyright>
<legalnotice>
  <para>
    This document can be redistributed under the terms of the GNU Free
    Documentation Licence.
  </para>
</legalnotice>
	      

Marquer du texte

Les éléments suivants peuvent se situer dans un paragraphe de texte afin de marquer une partie du texte de manière particulière:

Marquer du contenu informatique

DocBook (et donc AlcoveBook) a été conçu pour marquer de la documentation informatique technique. La majorité des éléments définis possèdent donc une sémantique informatique forte (noms de fichiers, commandes, etc.).

Exemples de code

Lorsque vous avez besoin d'inclure un exemple de code de plusieurs lignes dans votre document, vous devriez utiliser l'élément programlisting inclus dans l'élément example. L'avantage d'utiliser l'élément example est de nommer chacun des exemples de votre article, ce qui peut être utile pour générer une table des exemples.

Astuce : L'élément programlisting possède un attribut width qui permet de contrôler la largeur d'un listing de programme. Cet attribut spécifie le nombre de caractères affichés dans la largeur.

Exemple 19. Exemple d'insertion de programme source

	    
<section>
  <title>Un exemple de programme C</title>
  <para>
    Le premier programme en C que vous allez écrire sera le suivant:
  </para>
  <example>
    <title>Hello.c</title>
    <programlisting width="70">
      #include &lt;stdio.h&gt;
      int 
      main (int argc, char ** argv)
      {
        printf("Hello world!\n");
      }
    </programlisting>
  </example>
</section>
	  

Si vous désirez inclure sans peine un document comportant beaucoup de caractères spécifiques à SGML (c'est le cas de documents SGML, XML, HTML et même de programmes C), vous devriez utiliser une instruction de formatage spéciale pour indiquer à l'analyseur SGML d'ignorer tous les éléments qu'il pourrait y trouver. Cette instruction est le marqueur CDATA, donc le début doit apparaître juste après l'élément de début de programlisting et dont la fin doit être placée avant l'élément de fin de programlisting:

Exemple 20. Exemple d'insertion de code HTML

<para>
  <programlisting width="70">
  <![CDATA[
    <html>
      <head>
        <title>Titre de ma page</title>
      </head>

      <body bgcolor="#ffffff">
        Les photos de mes vacances
      </body>
    </html>
    
  ]]>
  
  </programlisting>
</para>
	  

Notez que le début du marqueur CDATA est "<![CDATA[" et que la fin du marqueur CDATA est "]]>". Tout formatage inclus entre le début et la fin de ce marqueur sera ignoré par les outils de traitement de votre document SGML et sera considéré comme du texte simple.

Le désavantage de cette méthode est que vous ne pouvez pas utiliser, par exemple, d'éléments tels que function, varname, classname, etc. pour agrémenter vos exemples, ni placer des notes de bas de page ni rien de semblable. Un « embellisseur » d'exemples sera probablement fournit dans le futur, mais vous devrez faire le travail à la main si vous voulez faire des choses compliquées. Il se peut que vous préfériez utiliser un callout là ou vous auriez utilisé les notes de bas de page.

Fichiers et répertoires

L'élément filename vous permet de marquer les fichiers, mais aussi les répertoires en ajoutant un attribut class="directory" dans cette balise. Par exemple:

Exemple 21. Exemple d'utilisation de noms de répertoire

	    
<para>
  En cas de problème lors de la mise à jour de Mandrake 7.2 en
  Mandrake 8.0, nous vous recommandons d'effacer le contenu du
  répertoire <filename class="directory">/usr</filename> et de
  réinstaller une distribution Debian GNU/Linux à la place.
</para>
	    
	  

Commandes

Vous pouvez marquer une commande ou une ligne de commande ne utilisant l'élément command. Par exemple:

Exemple 22. Exemple d'utilisation de commandes

<para>
  L'installation de logiciels empaquetés se fait sous Debian
  GNU/Linux par l'utilisation de la commande
  <command>apt-get install
  <replaceable>logiciel</replaceable></command>.
</para>
	  

Notez dans l'exemple précédent l'utilisation de l'élément replaceable, qui indique que le texte est un terme remplaçable par une valeur quelconque.

Il est possible de faire la même chose pour les options:

Exemple 23. Exemple d'utilisation de commandes et d'options

<para>
  <programlisting width="70">
    <command>apt-get <option>-f</option> install</command>
  </programlisting>
</para>
	  

Autres éléments

D'autres éléments sont disponibles afin de marquer du contenu informatique:

computeroutput

cet élément permet de marquer une chaîne de caractère produite par l'ordinateur. Typiquement, un message d'une application ;

database

cet élément permet de marquer le nom d'éléments de bases de données, typiquement des noms de tables ou de champs de données. L'attribut class de cet élément permet de spécifier le type de donnée marqué ;

email

cet élément permet de marquer une adresse email ;

envar

cet élément permet de marquer une variable d'environnement ;

userinput

cet élément permet de marquer une chaîne de caractère comme étant entrée par l'utilisateur. Typiquement, des données saisies sur l'entrée standard et communiquées à un programme ;

varname

cet élément permet de spécifier qu'une chaîne de caractère est une variable.

Mise en page: listes, tables, figures

Listes

Les listes peuvent être obtenues de plusieurs manières, mais la plus usuelle est d'utiliser l'élément itemizedlist pour une liste non ordonnée et orderedlist pour une liste ordonnée (numérotée). Chacune de ces deux listes contient une succession d'éléments listitem, contenant à son tour un élément para ou autre.

Exemple 24. Exemple d'utilisation de listes

<para>
  Logiciels utilisés dans l'offre proposée:
</para>
<itemizedlist>
  <listitem>
    <para>le serveur web Apache&nbsp;;</para>
  </listitem>
  <listitem>
    <para>le logiciel de monitoring Mon&nbsp;;</para>
  </listitem>
  <listitem>
    <para>le noyau Linux 2.4.1.</para>
  </listitem>
</itemizedlist>
	  

Note : La typographie Française impose l'utilisation du point-virgule à la fin de chaque élément d'une liste, précédé d'un demi-espace insécable (c'est à dire l'élément &nbsp;), sauf sur le dernier élément qui se termine par un point. Aucun des éléments ne doit commencer par une majuscule.

Tables

L'utilisation des tables est un peu complexe en raison de la relative verbosité d'AlcoveBook sur cet aspect. Le principe est de définir des groupes de cellules, incluses dans des lignes, elles-mêmes incluses dans un groupe de lignes. Un exemple vous permettra d'y voir un peu plus clair:

Exemple 25. Exemple de table

<table>
  <title>Exemple de table</title>
  <tgroup cols="3">
    <thead>
      <row>
        <entry>Nom</entry>
        <entry>Âge</entry>
        <entry>Sexe</entry>
      </row>
    </thead>
    <tbody>
      <row>
        <entry>Benjamin Drieu</entry>
        <entry>23</entry>
        <entry>Masculin</entry>
      </row>
      <row>
        <entry>Casimir</entry>
        <entry>34</entry>
        <entry>Orange</entry>
      </row>
    </tbody>
  </tgroup>
</table>
	  

Les éléments suivants sont utilisés pour décrire une table et se situent dans un élément table:

  • entry décrit le contenu d'une cellule ;

  • row décrit le contenu d'une ligne. Il doit contenir autant d'éléments entry que de colonnes ;

  • tbody décrit le contenu de la table. Il contient autant d'éléments row que de lignes ;

  • thead décrit le contenu de l'en-tête de la table. Il contient autant d'éléments entry que de colonnes ;

  • tgroup décrit le contenu de la table. Il doit contenir au moins un élément tbody ou thead et il doit contenir un paramètre cols, positionné au nombre de colonnes de la table ;

  • title décrit le titre de la table.

Figures

L'inclusion de figure se fait par le biais de l'utilisation de l'élément figure. Cet élément permet de nommer une figure et d'y inclure un élément imageobject. Par exemple, pour inclure la photo de mon chien (au format EPS) dans une propale:

Exemple 26. Exemple de figure

<figure>
  <title>La photo de mon chien</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="rex.eps">
    </imageobject>
  </mediaobject>
</figure>
	  

Insérer des fichiers externes

Il peut être utile d'insérer des fichiers externes dans un document SGML (par exemple pour découper le document source en autant de fichiers que de chapitres ou par exemple pour insérer un fichier dans un exemple plutôt que de le copier/coller). Deux méthodes permettent de le faire:

Les entités externes

Les entités externes sont définies dans l'élément d'identification du document. Voici un exemple de définition et d'utilisation d'entités externes:

Exemple 27. Exemple d'utilisation d'entités externes

<!DOCTYPE article PUBLIC "-//Alcove//DTD DocBook V4.1-Based Subset AlcoveBook V0.1 Draft//EN" [
  <!entity prenom "Benjamin">
  <!entity nom "Drieu">
]>
<article lang="fr">
  <articleinfo>
    <title>Une introduction pratique à AlcoveBook</title>
    <subtitle></subtitle>
    <author>
      <firstname>&prenom;</firstname>
      <surname>&nom;</surname>
    </author>
    <date>27 août 2001</date>
  </articleinfo>
</article>
	  

Utilisation d'images en ligne

L'utilisation d'une image en ligne implique la définition d'un élément imagedata (la section intitulée Figures), par exemple dans un contexte mediaobject. L'attribut format doit être positionné à la valeur linespecific. L'avantage de cette solution est qu'il n'y a pas transformation SGML du document inclut. En revanche, cette solution est spécifique à DocBook.

Exemple 28. Exemple d'utilisation d'image textuelle

<mediaobject>
  <imageobject>
    <imagedata fileref="/etc/passwd" format="linespecific">
  </imageobject>
</mediaobject>