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.
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'élément articleinfo
contient tous les autres éléments qui composent l'en-tête 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:
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.
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. |
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>
L'élément contractsponsor
permet de
spécifier le client destinataire de ce document.
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>
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:
Les éléments suivants peuvent se situer dans un paragraphe de texte afin de marquer une partie du texte de manière particulière:
emphasis
: mise en
évidence de texte (exemple) ;
subscript
: mise en
indice de texte (exemple) ;
superscript
: mise en
facteur de texte
(exemple) ;
quote
: citation.
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.).
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 attributwidth
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 <stdio.h> 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.
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>
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:
D'autres éléments sont disponibles afin de marquer du contenu informatique:
cet élément permet de marquer une chaîne de caractère produite par l'ordinateur. Typiquement, un message d'une application ;
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é ;
cet élément permet de marquer une adresse email ;
cet élément permet de marquer une variable d'environnement ;
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 ;
cet élément permet de spécifier qu'une chaîne de caractère est une variable.
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 ;</para> </listitem> <listitem> <para>le logiciel de monitoring Mon ;</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 ), sauf sur le dernier élément qui se termine par un point. Aucun des éléments ne doit commencer par une majuscule.
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.
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:
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:
utiliser les entités externes SGML ;
utiliser une image en ligne textuelle de DocBook.
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>
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.