Pour écrire une documentation avec AlcoveBook, vous m'avez pas besoin d'outil particulier. Nous vous recommandons cependant d'utiliser l'éditeur Emacs et son mode psgml, qui offre des possibilités tout à fait intéressantes (la section intitulée Psgml dans Annexe A).
Nous allons commencer par un exemple de document AlcoveBook basique. Notez que cette exemple, bien qu'étant un document DocBook valide, n'est pas un exemple AlcoveBook et sera progressivement complété au fur et à mesure des sections suivantes pour le rendre valide.
Exemple 6. Exemple basique de document AlcoveBook
<!doctype article PUBLIC "-//Alcove//DTD DocBook V4.1-Based Subset AlcoveBook V0.1 Draft//EN"> <article> <articleinfo> <title>Principia Discordia
</title> <subtitle>or, How I Found the Goddess and What I Did To Her When I Found Her
</subtitle> <author> <firstname>Malaclypse
</firstname> <surname>Le Jeune
</surname> <affiliation> <jobtitle>Directeur Technique
</jobtitle> <orgname>Front de Libération Érisien
</orgname> <address><email>malaclypse@eris.com
</email></address> </affiliation> </author> <date>17 mai 1723
</date> </articleinfo> <section> <title>Introduction</title> <para> ... </para> </section> </article>
La balise article
nous indique que le
document est un article. Tous les autres éléments de ce
document sont contenus dans cet élément « racine ».
La première paire de balises title
, contenue
dans l'élément articleinfo
spécifie le titre de
l'article (plus généralement, les éléments contenus dans
l'élément articleinfo
décrivent les informations
utiles sur l'article: auteur, date, etc.).
Que signifie l'élément DOCTYPE au début de ce document ? Il
s'agit de la déclaration du type du document, qui définit le
type de document SGML dont il s'agit et quelle est la DTD que
nous utilisons pour le formatage. Vous n'avez pas besoin de la
comprendre, mais juste d'être sûrs que le début de chacun des
documents que vous formatez avec AlcoveBook conttient cette
définition. En fonction de la taille du document que vous
écrivez, vous pouvez être amenés à modifier le mot
article
et à le remplacer par
book
, chapter
,
refentry
ou n'importe quel autre élément
nécessaire.
On trouve à la fin de cet exemple un élément section
, que nous détaillerons plus
tard. Cet élément héberge le contenu de la première section du
document.