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:
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:
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.
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:
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.
Tuyau : 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.
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:
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:
Vous pouvez marquer une commande ou une ligne de commande ne utilisant l'élément command. Par exemple:
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.
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:
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:
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.