Commencer

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.