4.2. DocBook

DocBook est une DTD créée par le Davenport Group pour la rédaction de documentation technique. De sorte que, et au contraire de LinuxDoc ou HTML, les marques DocBook sont plus conçues pour décrire ce qu'est quelque chose que comment il faut le présenter.

formel vs. informel:

Certains éléments ont deux versions - formelle et informelle. Habituellement, la version formelle de l'élément comporte une titre. La version informelle n'en a pas.

La DTD DocBook est disponible au catalogue des logiciels portés avec le “méta-logiciel porté” textproc/docbook. Elle est automatiquement installée par ce dernier.

4.2.1. Extensions FreeBSD

Le Projet de Documentation de FreeBSD a ajouté quelques nouveaux éléments à la DTD DocBook. Ces éléments permettent un marquage plus précis.

Dans la suite, quand il sera question d'un élément propre à FreeBSD, ce sera clairement indiqué.

Le terme “DocBook” désigne dans ce qui suit la DTD DocBook avec les extensions FreeBSD.

Note:

Il n'y a rien dans ces extensions qui soit propre à FreeBSD, on a juste pensé que ce seraient des ajouts utiles pour ce projet précis. Si d'autres contributeurs aux autres projets “*nix” (NetBSD, OpenBSD, Linux, …) sont intéressés à participer à la mise au point d'un jeu d'extensions DocBook standard, merci de contacter Nik Clayton .

Les extensions FreeBSD ne font pas (actuellement) partie du catalogue des logiciels portés. Elles sont inclues dans les sources du Projet de Documentation et se trouvent dans doc/share/xml/freebsd.dtd.

4.2.2. Identifiant Public Formel - Formal Public Identifier, (FPI)

En conformité avec les conventions DocBook concernant les FPIs pour les personnalisations de DocBook, le FPI pour la DTD DocBook avec les extensions FreeBSD est :

PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"

4.2.3. Structure des documents

DocBook vous permet de structurer votre documentation de différentes façons. Le Projet de Documentation de FreeBSD utilise deux types de documents de base, le livre et l'article.

Un livre est organisé en chapters. C'est une obligation. Il peut y avoir des parts entre le livre et le chapitre si l'on veut un niveau supplémentaire dans le découpage.

Un chapitre peut avoir (ou non) une ou plusieurs sections. Elles sont désignées par l'élément sect1. Si une section inclue une autre section, utilisez l'élément sect2, et ainsi de suite, jusqu'à sect5.

Le contenu du livre est lui-même dans les chapitres et sections.

Un article est plus simple qu'un livre, et n'a pas de chapitres. Au lieu de cela, le contenu d'un article est organisé en une ou plusieurs sections, à l'aide des mêmes éléments sect1 (sect2 et ainsi de suite) dont on se sert pour les livres.

Il vous faudra manifestement choisir le type de document à utiliser selon la nature du document que vous rédigez. Les articles sont bien adaptés pour des documents qui n'ont pas besoin d'être décomposés en chapitres, et qui sont, relativement parlant, assez court - jusqu'à 20-25 pages. Les livres eux conviennent aux documents qui peuvent être découpés en plusieurs chapitres, avec éventuellement des annexes, et autres composants.

Les guides FreeBSD sont tous des articles, tandis que ce document, la FAQ FreeBSD, et le Manuel de Référence FreeBSD sont des livres.

4.2.3.1. Commencer un livre

Le contenu d'un livre est un inclus dans l'élément book. Tout autant que des marques organisant le contenu, cet élément peut contenir des éléments qui donnent des informations supplémentaires sur le livre. Ce sont soit des méta-informations, utilisées pour y faire référence, soit un contenu supplémentaire servant à générer la page de titre.

Ces informations supplémentaires doivent être inclues dans l'élément bookinfo.

Exemple 4.21. Boilerplate??? book avec bookinfo
<book>
  <bookinfo>
    <title>Mettez le titre ici</title>

    <author>
      <firstname>Votre prénom</firstname>
      <surname>Votre nom de famille</surname>
      <affiliation>
        <address><email>Votre adresse de courrier
              électronique</email></address>
      </affiliation>
    </author>

    <copyright>
      <year>1998</year>
      <holder role="mailto:Votre adresse de courrier
            électronique">Votre nom</holder>
    </copyright>

    <pubdate role="rcs">$Date$</pubdate>

    <releaseinfo>$Id$</releaseinfo>

    <abstract>
      <para>Résumez ici le contenu du
            livre.</para>
    </abstract>
  </bookinfo>

  …

</book>

4.2.3.2. Commencer un article

Le contenu d'un article est un inclus dans l'élément article. Tout autant que des marques organisant le contenu, cet élément peut contenir des éléments qui donnent des informations supplémentaires sur l'article. Ce sont soit des méta-informations, utilisées pour y faire référence, soit un contenu supplémentaire servant à générer la page de titre.

Ces informations supplémentaires doivent être inclues dans l'élément artheader.

Exemple 4.22. Boilerplate??? article avec artheader
<article>
  <artheader>
    <title>Mettez le titre ici</title>

    <author>
      <firstname>Votre prénom</firstname>
      <surname>Votre nom de famille</surname>
      <affiliation>
        <address><email>Votre adresse de courrier
              électronique</email></address>
      </affiliation>
    </author>

    <copyright>
      <year>1998</year>
      <holder role="mailto:Votre adresse de courrier
            électronique">Votre nom</holder>
    </copyright>

    <pubdate role="rcs">$Date$</pubdate>

    <releaseinfo>$Id$</releaseinfo>

    <abstract>
      <para>Résumez ici le contenu de l'article.</para>
    </abstract>
  </artheader>

  …

</article>

4.2.3.3. Séparer les chapitres

Utilisez chapter pour marquer vos chapitres. Chaque chapitre a obligatoirement un title. Les articles n'ont pas de chapitre, ils sont réservés aux livres.

Exemple 4.23. Un chapitre
<chapter>
  <title>Le titre du chapitre</title>

  ...
</chapter>

Un chapitre ne peut pas être vide, il doit contenir des éléments en plus du title. Si vous voulez inclure un chapitre vide, ajoutez lui simplement un paragraphe vide.

Exemple 4.24. Chapitres vides
<chapter>
  <title>C'est un chapitre vide</title>

  <para></para>
</chapter>

4.2.3.4. Sections dans les chapitres

Dans les livres, les chapitres peuvent (mais ce n'est pas obligatoire) être décomposés en sections, sous-sections, et ainsi de suite. Dans les articles, les sections sont les principaux éléments d'organisation et chaque article doit contenir au moins une section. Utilisez l'élément sectn. Le n est le type de section, qui indique son niveau de profondeur.

La première sectn est sect1. Vous pouvez en avoir plus d'une dans un chapitre. Elles peuvent inclure un ou plusieurs éléments sect2, et ainsi de suite, jusqu'à sect5.

Exemple 4.25. Sections dans les chapitres
<chapter>
  <title>Exemple de chapitre</title>

  <para>Du texte dans le chapitre.</para>

  <sect1>
    <title>Première section (1.1)</title>

    &hellip;
  </sect1>

  <sect1>
    <title>Seconde section (1.2)</title>

    <sect2>
      <title>Première sous-section (1.2.1)</title>

      <sect3>
        <title>Première sous-sous-section (1.2.1.1)</title>

        &hellip;
      </sect3>
    </sect2>

    <sect2>
      <title>Seconde sous-section (1.2.2)</title>

      &hellip;
    </sect2>
  </sect1>
</chapter>

Note:

Cet exemple donne les numéros des sections dans leurs titres. Vous ne devez pas le faire. Les feuilles de style s'en chargent (voir plus bas pour plus de détails), et vous n'avez pas à vous en préoccupez.

4.2.3.5. Subdivision en parts

Vous pouvez avoir un niveau d'organisation supplémentaire entre le book et le chapter en définissant une ou plusieurs parts. Ce n'est pas possible dans un article.

<part>
  <title>Introduction</title>

  <chapter>
    <title>Resumé</title>

    ...
  </chapter>

  <chapter>
    <title>Qu'est-ce que FreeBSD&nbsp;?</title>

    ...
  </chapter>

  <chapter>
    <title>Historique</title>

    ...
  </chapter>
</part>

4.2.4. Eléments de blocs

4.2.4.1. Paragraphes

DocBook connaît trois types de paragraphes : formalpara, para et simpara.

La plupart du temps, des paras vous suffiront. Les formalparas ont un title, et avec les simparas, certains éléments sont interdits à l'intérieur du paragraphe. Tenez-vous en aux paras.

Exemple 4.26. para

Utilisez :

<para>C'est un paragraphe. Il peut contenir
  presque n'importe quel autre élément.</para> 

Apparence :

C'est un paragraphe. Il peut contenir presque n'importe quel autre élément.


4.2.4.2. Citations en bloc

Une citation en bloc est un long extrait d'un autre document qui ne doit pas faire partie du paragraphe courant. Vous n'en aurez probablement pas besoin souvent.

Les citations en blocs peuvent facultativement avoir un titre et une attribution (ou n'avoir ni titre ni attribution).

Exemple 4.27. blockquote

Utilisez :

<para>Un court extrait de la constitution des Etats-Unis&nbsp;:</para>

<blockquote>
  <title>Préambule &agrave; la Constitution des Etats-Unis</title>

  <attribution>Copié d'un site Web quelque part</attribution>

  <para>Nous le Peuple des Etats-Unis, dans le but de former
    une Union plus parfaite, d'établir la Justice, de garantir
    la Tranquilité domestique, assurer la défense collective,
    promouvoir notre Bien-être général, et conserver &agrave;
    nous-mêmes et &agrave; notre Postérité les bienfaits de la
    Liberté, proclamons et établissons cette Constitution des
    Etats-Unis d'Amérique.</para>
</blockquote>

Apparence :

Un court extrait de la constitution des Etats-Unis :

 
Préambule à la Constitution des Etats-Unis

Nous le Peuple des Etats-Unis, dans le but de former une Union plus parfaite, d'établir la Justice, de garantir la Tranquilité domestique, assurer la défense collective, promouvoir notre Bien-être général, et conserver à nous-mêmes et à notre Postérité les bienfaits de la Liberté, proclamons et établissons cette Constitution des Etats-Unis d'Amérique.

 
 --Copié d'un site Web quelque part

4.2.4.3. Indications, notes, avertissements, mises en garde, informations importantes et barres verticales.

Vous devrez peut-être ajouter des informations distinctes du texte lui-même. Ce sont habituellement des “méta-informations” que l'utilisateur doit connaître.

Selon la nature de l'information, vous utiliserez l'un des élements tip, note, warning, caution ou important. Ou bien, si l'information est en rapport avec le texte, mais ne correspond à aucun des cas précédents, servez-vous de sidebar.

Les cas où il faut choisir l'un ou l'autre de ces éléments ne sont pas clairement explicités. Voici ce que suggère la documentation DocBook :

  • Une Note est une information destinée à tous les lecteurs.

  • Un élément Important est une variante de la Note.

  • Une Caution est une information relative à la perte de données ou dégats logiciels éventuels.

  • Un Warning est une information relative aux dégats matériels ou risques corporels.

Exemple 4.28. warning

Utilisez :

<warning>
  <para>Installer FreeBSD peut vous donner envie de supprimer
    Windows de votre disque dur.</para>
</warning>

Avertissement:

Installer FreeBSD peut vous donner envie de supprimer Windows de votre disque dur.

4.2.4.4. Listes and procédures

Vous aurez souvent besoin de lister des informations ou d'indiquer à l'utilisateur les différentes étapes nécessaires pour effectuer une tâche donnée.

Pour cela, servez-vous de itemizedlist, orderedlist ou procedure[3]

itemizedlist et orderedlist sont semblables à leurs contreparties ul et ol en HTML. Chacune comporte un ou plusieurs éléments listitem, et chaque listitem contient un ou plusieurs éléments de blocs. Les élements listitem sont analogues aux marques li du HTML. Néanmoins, au contraire du HTML, ils sont ici obligatoires.

Une procedure est légérement différente. Elle consiste en steps, qui à leur tour sont composés de steps ou substeps. Chaque step contient des éléments de blocs.

Exemple 4.29. itemizedlist, orderedlist et procedure

Utilisez :

<itemizedlist>
  <listitem>
    <para>C'est le premier élément de la liste.</para>
  </listitem>

  <listitem>
    <para>C'est le second élément de la liste.</para>
  </listitem>
</itemizedlist>

<orderedlist>
  <listitem>
    <para>C'est le premier élément de la liste
      ordonnée.</para>
  </listitem>

  <listitem>
    <para>C'est le second élément de la liste ordonnée.</para>
  </listitem>
</orderedlist>

<procedure>
  <step>
    <para>Faites ceci.</para>
  </step>

  <step>
    <para>Puis cela.</para>
  </step>

  <step>
    <para>Et maintenant cela.</para>
  </step>
</procedure>

Apparence :

  • C'est le premier élément de la liste.

  • C'est le second élément de la liste.

  1. C'est le premier élément de la liste ordonnée.

  2. C'est le second élément de la liste ordonnée.


  1. Faites ceci.

  2. Puis cela.

  3. Et maintenant cela.

4.2.4.5. Extraits de fichiers

Si vous voulez incorporer un extrait de fichier (ou éventuellement une fichier entier), mettez-le dans un élément programlisting.

Les blancs et sauts de ligne à l'intérieur de programlisting sont significatifs. Cela signifie en particulier que la marque de début doit être sur la même ligne que la première ligne du listing et que la marque de fin doit être sur la même ligne que la dernière ligne du listing, sans quoi il y aurait des lignes blanches en trop.

Exemple 4.30. programlisting

Utilisez :

<para>Quand vous aurez fini, votre programme
 ressemblera &agrave; cela :</para>

<programlisting>#include &lt;stdio.h&gt;

int
main(void)
{
    printf("bonjour, le monde\n");
}</programlisting>

Notez qu'il faut utiliser les entités correspondantes et non les signes “supérieur” et “inférieur” à la ligne #include.

Apparence :

Quand vous aurez fini votre programme, ressemblera à cela :

#include <stdio.h>

int
main(void)
{
    printf("bonjour, le monde\n");
}

Note:

DocBook dispose d'un mécanisme pour faire référence à des sections d'un programlisting inclus auparavant, appelé “rappels” (voir programlistingco pour plus d'information). Je ne le comprend pas tout à fait (i.e., je ne l'ai jamais employé), je ne peux donc pas le décrire. En attendant, vous pouvez numéroter les lignes et y faire référence ensuite. Cela changera dès que je trouverais le temps de comprendre et documenter les “rappels”.

4.2.4.6. Tables

Au contraire d'HTML, vous n'avez pas besoin d'utiliser les tables pour des questions de présentation, puisque les feuilles de style s'en chargent. Les tables servent uniquement pour les données en tableaux.

Brièvement (voyez la documentation de DocBook pour plus de détails), une table (qui peut-être formelle ou informelle) est constituée d'un élément table. Il contient au moins un élément tgroup, dont l'attribut donne le nombre de colonnes dans ce sous-tableau. Dans le sous-tableau, vous pouvez ensuite avoir un élément thead, qui contient les éléments correspondant aux en-têtes des colonnes, et un tbody qui contient le corps du tableau.

Les thead et tbody contiennent des éléments row - lignes, qui contiennent à leur tour des éléments entry. Chaque élément entry correspond à une cellule du tableau.

Exemple 4.31. informaltable

Utilisez :

<informaltable>
  <tgroup cols="2">
    <thead>
      <row>
        <entry>C'est le titre de la colonne 1</entry>
        <entry>C'est le titre de la colonne 2</entry>
      </row>
    </thead>

    <tbody>
      <row>
        <entry>Ligne 1, colonne 1</entry>
        <entry>Ligne 1, colonne 2</entry>
      </row>

      <row>
        <entry>Ligne 2, colonne 1</entry>
        <entry>Ligne 2, colonne 2</entry>
      </row>
    </tbody>
  </tgroup>
</informaltable>

Apparence :

C'est le titre de la colonne 1C'est le titre de la colonne 2
Ligne 1, colonne 1Ligne 1, colonne 2
Ligne 2, colonne 1Ligne 2, colonne 2

Si vous ne voulez pas de bordures autour du tableau, vous pouvez ajouter à l'élément informaltable l'attribut frame avec la valeur none (i.e., <informaltable frame="none">).

Exemple 4.32. Tableaux avec frame="none"

Apparence :

C'est le titre de la colonne 1C'est le titre de la colonne 2
Ligne 1, colonne 1Ligne 1, colonne 2
Ligne 2, colonne 1Ligne 2, colonne 2

4.2.4.7. Exemples que l'utilisateur doit suivre

Vous aurez souvent à donner des exemples que l'utilisateur puisse suivre. Ce seront habituellement des dialogues avec la machine : l'utilisateur tape une commande, il reçoit une réponse, il tape une autre commande, et ainsi de suite.

Il y a là un certain nombre d'entités et d'éléments qui entrent en jeu.

screen

Tout ce que l'utilisateur voit dans cet exemple est affiché sur l'écran de l'ordinateur, l'élément suivant est donc screen.

A l'intérieur de screen, les blancs sont significatifs.

prompt, &prompt.root; et &prompt.user;

Parmi ce que l'utilisateur verra à l'écran, il y a les invites (du système, de l'interpréteur de commandes ou des applications). Ils doivent être marqués avec prompt.

Le cas particulier des deux invites de l'interpréteur de commandes, pour un utilisateur ordinaire et pour le super-utilisateur, est traité avec des entités. Chaque fois que vous voulez montrer que l'utilisateur est sous l'interpréteur de commande, servez-vous de &prompt.root; ou &prompt.user; selon le cas. Il n'y a pas besoin qu'elles soient à l'intérieur de prompt.

Note:

&prompt.root; et &prompt.user; sont des extensions FreeBSD à DocBook, et ne font pas partie de la DTD originale.

userinput

Quant il s'agit de texte que l'utilisateur doit taper, mettez-le dans un élément userinput. Il sera normalement affiché différement.

Exemple 4.33. screen, prompt et userinput

Utilisez :

<screen>&prompt.user; <userinput>ls -1</userinput>
foo1
foo2
foo3
&prompt.user; <userinput>ls -1 | grep foo2</userinput>
foo2
&prompt.user; <userinput>su</userinput>
<prompt>Password: </prompt>
&prompt.root; <userinput>cat foo2</userinput>
C'est le fichier 'foo2'</screen>

Apparence:

% ls -1
foo1
foo2
foo3
% ls -1 | grep foo2
foo2
% su
Password: 
# cat foo2
C'est le fichier 'foo2'

Note:

Bien que nous montrions le contenu du fichier foo2, nous n'utilisons pas la marque programlisting. Réservez programlisting pour les extraits de fichiers hors du dialogue homme/machine.

4.2.5. Eléments en ligne

4.2.5.1. Mettre de l'information en valeur

Si vous voulez mettre en valeur un mot ou une phrase, servez-vous de emphasis. La présentation en sera peut-être en italiques, ou gras, ou bien ce sera prononcé différement par un logiciel de synthèse vocale.

Il n'y a aucun moyen de changer la présentation du texte mis en valeur dans votre document, pas d'équivalent des b et i. Si l'information que vous donnez est importante, envisagez d'utiliser important plutôt que emphasis.

Exemple 4.34. emphasis

Utilisez :

<para>FreeBSD est sans aucun doute
  <emphasis>le</emphasis> premier système
  d'exploitation de type Unix pour
  architecture Intel.</para>

Apparence :

FreeBSD est sans aucun doute le premier système d'exploitation de type Unix pour architecture Intel.


4.2.5.2. Applications, commandes, options et références

Il vous arrivera souvent de désigner des applications ou des commandes quand vous rédigerez quelque chose pour le Manuel de Référence. Distinguer les unes des autres est simple : une application est un ensemble de (ou éventuellement un seul) programmes dédiés à une tâche particulière. Une commande est le nom d'un programme que l'utilisateur peut exécuter.

Vous aurez aussi de temps à autre à lister une ou plusieurs des options d'une commande.

Pour finir, il arrivera souvent que vous vouliez indiquer en même temps que la commande, son numéro de section dans les pages de manuel, au format “commande(numéro)” habituel dans les documentations Unix.

Désignez les noms d'applications avec application.

Si vous voulez lister une commande avec son numéro de section dans le manuel (ce qui sera la plupart du temps le cas), l'élément DocBook pour cela est citerefentry. Il contiendra deux autres éléments, refentrytitle et manvolnum. Le contenu de refentrytitle est le nom de la commande, et celui de manvolnum est son numéro de section dans le manuel.

Ce peut être fastidieux à taper, aussi a-t-on défini une séries d'entités générales pour faciliter ces références. Chacune de ces entités est de la forme &man.page-de-manuel.section-du-manuel;.

Ces entités sont dans le fichier doc/share/xml/man-refs.ent, qui peut-être référencé par le FPI :

PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"

L'introduction de votre documentation ressemblera donc probalement à  :

<!DOCTYPE book PUBLIC
  "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [

<!ENTITY % man PUBLIC
  "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;

…

]>

Servez-vous de command quand vous voulez mettre le nom d'une commande dans le texte en le présentant comme quelque chose que l'utilisateur doit taper.

Utilisez option pour désigner les options d'une commande.

Ce peut être confus, et le bon choix n'est pas toujours évident. Espérons que les exemples qui suivent éclaircirons les choses.

Exemple 4.35. Applications, commandes et options.

Utilisez :

<para><application>Sendmail</application> est le logiciel de
  courrier électronique le plus employé sous Unix.</para>

<para><application>Sendmail</application> comporte les
  programmes <citerefentry>
    <refentrytitle>sendmail</refentrytitle>
    <manvolnum>8</manvolnum>
  </citerefentry> et &man.newaliases.8;.</para>

<para>L'un des paramètres de la ligne de commande de
  <citerefentry><refentrytitle>sendmail</refentrytitle>
    <manvolnum>8</manvolnum></citerefentry>,
    <option>-bp</option>, affiche l'état des messages
    dans la file d'attente. Vérifiez-le en exécutant
    <command>sendmail -bp</command>.</para>

Apparence :

Sendmail est le logiciel de courrier électronique le plus employé sous Unix.

Sendmail comporte les programmes sendmail(8) et newaliases(8).

L'un des paramètres de la ligne de commande de sendmail(8), -bp, affiche l'état des messages dans la file d'attente. Vérifiez-le en exécutant sendmail -bp.


Note:

Remarquez comme il est plus facile d'utiliser la notation &man.commande.section;.

4.2.5.3. Fichiers, répertoires, extensions

Chaque fois que vous voulez donner le nom d'un fichier, d'un répertoire ou de l'extension d'un fichier, servez-vous de filename.

Exemple 4.36. filename

Utilisez :

<para>Vous trouverez le source SGML du Manuel
  de Référence en Anglais dans
  <filename>/usr/doc/en/handbook/</filename>. Le
  fichier principal, dans ce répertoire, s'appelle
  <filename>handbook.xml</filename>. Il doit aussi
  y avoir un <filename>Makefile</filename> et un
  certain nombre de fichiers avec l'extension
  <filename>.ent</filename>.</para>

Apparence :

Vous trouverez le source SGML du Manuel de Référence en Anglais dans /usr/doc/en/handbook/. Le fichier principal, dans ce répertoire, s'appelle handbook.xml. Il doit aussi y avoir un Makefile et un certain nombre de fichiers avec l'extension .ent.


4.2.5.4. Fichiers spéciaux de périphériques

extension FreeBSD:

Ces éléments font partie des extensions FreeBSD à DocBook et n'existent pas dans la DTD DocBook d'origine.

Pour faire référence à des fichiers spéciaux de périphériques, vous avez deux solutions. Soit utiliser le nom du fichier spécial dans /dev, soit le nom sous lequel il est désigné dans le noyau. Dans ce dernier cas, servez-vous de devicename.

Il y a des cas où vous n'aurez pas le choix. Pour certains périphériques, les cartes réseaux par exemple, il n'y a pas d'entrées dans /dev, ou bien celles-ci sont très différentes des noms utilisés dans le noyau.

Exemple 4.37. devicename

Utilisez :

<para><devicename>sio</devicename> sert
  sous FreeBSD aux communications séries.
  <devicename>sio</devicename> correspond
  &agrave; un certain nombre d'entrées dans
  <filename>/dev</filename>, dont
  <filename>/dev/ttyd0</filename> et
  <filename>/dev/cuaa0</filename>.</para>

<para>A l'inverse, les périphériques réseaux, tel que
  <devicename>ed0</devicename> n'apparaissent pas dans
  <filename>/dev</filename>.</para>

<para>Sous MS-DOS, le premier lecteur de disquette s'appelle
  <devicename>a:</devicename>. Sous FreeBSD, c'est
  <filename>/dev/fd0</filename>.</para>

Apparence :

sio sert sous FreeBSD aux communications séries. sio correspond à un certain nombre d'entrées dans /dev, dont /dev/ttyd0 et /dev/cuaa0.

A l'inverse, les périphériques réseaux, tel que ed0 n'apparaissent pas dans /dev.

Sous MS-DOS, le premier lecteur de disquette s'appelle a:. Sous FreeBSD, c'est /dev/fd0.


4.2.5.5. Machines, domaines, adresses IP, et ainsi de suite

extension FreeBSD:

Ces éléments font partie des extensions FreeBSD à DocBook et n'existent pas dans la DTD DocBook d'origine.

Il y a différentes façons de dénoter les informations d'identification des machines en réseau, selon le type d'information. Elles utilisent toutes hostid comme élément, l'attribut role servant à qualifier le type d'information.

Pas de valeur de l'attribut, ou role="hostname"

Sans valeur de l'attribut (i.e., hostid...hostid), l'information donnée est le seul nom de la machine, freefall ou wcarchive, par exemple. Vous pouvez l'expliciter avec role="hostname".

role="domainname"

C'est ici un nom de domaine, comme FreeBSD.org ou ngo.org.uk. Il n'y a pas de nom de machine.

role="fqdn"

C'est le nom complet de la machine - Fully Qualified Domain Name, composé du nom de la machine et du nom de domaine.

role="ipaddr"

On donne alors l'adresse IP, probablement sous forme de quatre nombres séparés par des points.

role="netmask"

C'est un masque de sous-réseau, qui peut être donné comme quatre nombres séparés par des points, un chaîne en hexadécimal ou un / suivi d'un nombre.

role="mac"

C'est une adresse Ethernet MAC, exprimée par un séries de valeurs hexadécimales sur deux positions séparées par des deux-points.

Exemple 4.38. hostid et roles

Utilisez :

<para>La machine locale peut toujours
  être désignée par <hostid>localhost</hostid>,
  et aura l'adresse IP
  <hostid role="ipaddr">127.0.0.1</hostid>.</para>

<para>Le domaine
  <hostid role="domainname">FreeBSD.org</hostid>
  inclut un certain nombre de machine, dont
  <hostid role="fqdn">freefall.FreeBSD.org</hostid> et
  <hostid role="fqdn">bento.FreeBSD.org</hostid>.</para>

<para>Quand vous ajoutez un alias IP &agrave; une interface (avec
  <command>ifconfig</command>), utilisez
  <emphasis>toujours</emphasis> le masque de sous-réseau
  <hostid role="netmask">255.255.255.255</hostid>
  (qui peut aussi s'écrire
  <hostid role="netmask">0xffffffff)</hostid>.</para>

<para>L'adresse MAC identifie de façon unique
  chaque carte réseau existante.  Une adresse MAC
  ressemble typiquement &agrave; <hostid
    role="mac">08:00:20:87:ef:d0</hostid>.</para>

Apparence :

La machine locale peut toujours être désignée par localhost, et aura l'adresse IP 127.0.0.1.

Le domaine FreeBSD.org inclut un certain nombre de machine, dont freefall.FreeBSD.org et bento.FreeBSD.org.

Quand vous ajoutez un alias IP à une interface (avec ifconfig), utilisez toujours le masque de sous-réseau 255.255.255.255 (qui peut aussi s'écrire 0xffffffff).

L'adresse MAC identifie de façon unique chaque carte réseau existante. Une adresse MAC ressemble typiquement à 08:00:20:87:ef:d0.


4.2.5.6. Noms d'utilisateurs

extension FreeBSD:

Ces éléments font partie des extensions FreeBSD à DocBook et n'existent pas dans la DTD DocBook d'origine.

Si vous avez besoin de faire référence à un nom d'utilisateur, comme root ou bin, servez-vous de username.

Exemple 4.39. username

Utilisez :

<para>Pour effectuer la plupart des
  tâches d'administration système,
  vous aurez besoin d'être
  <username>root</username>.</para>

Apparence :

Pour effectuer la plupart des tâches d'administration système, vous aurez besoin d'être root.


4.2.5.7. Décrire les Makefiles

extension FreeBSD:

Ces éléments font partie des extensions FreeBSD à DocBook et n'existent pas dans la DTD DocBook d'origine.

Il y a des éléments pour décrire les composantes d'un Makefiles, maketarget et makevar.

maketarget désigne une cible définie dans un Makefile qui peut être utilisée en paramètre de make. makevar désigne une variable qui peut être définie (dans l'environnement, sur la ligne de commande de make ou dans le Makefile) et affecte le processus .

Exemple 4.40. maketarget et makevar

Utilisez :

<para>Il y a deux cibles courantes dans les
  <filename>Makefile</filename>&nbsp;:
  <maketarget>all</maketarget> et
  <maketarget>clean</maketarget>.</para>

<para>Généralement, invoquer <maketarget>all</maketarget>
  reconstruit l'application, et invoquer
  <maketarget>clean</maketarget> supprime les
  fichiers temporaires (<filename>.o</filename>
  par exemple) créés lors de la reconstruction.</para>

<para><maketarget>clean</maketarget> peut être
  contrôlée par un certain nombre
  de variables, dont <makevar>CLOBBER</makevar> et
  <makevar>RECURSE</makevar>.</para>

Apparence :

Il y a deux cibles courantes dans les Makefile : all et clean.

Généralement, invoquer all reconstruit l'application, et invoquer clean supprime les fichiers temporaires (.o par exemple) créés lors de la reconstruction.

clean peut être contrôlée par un certain nombre de variables, dont CLOBBER et RECURSE.


4.2.5.8. Litéraux

Vous aurez souvent besoin d'inclure “litéralement” du texte dans le Manuel. Ce sont des extraits d'un fichier, que l'on doit pouvoir copier tel quel dans un autre fichier.

Il vous suffira parfois de programlisting pour cela. programlisting n'est pas toujours approprié, en particulier quand vous voulez inclure un extrait de fichier au fil de l'eau, dans le corps même du paragraphe.

Servez-vous dans ces cas-là de literal.

Exemple 4.41. literal

Utilisez :

<para>La ligne <literal>maxusers 10</literal> du fichier
  de configuration du noyau détermine la table de nombreuses
  tables système et définit approximativement le nombre de
  connexions simultanées qu'acceptera le système.</para>

Apparence :

La ligne maxusers 10 du fichier de configuration du noyau détermine la table de nombreuses tables système et définit approximativement le nombre de connexions simultanées qu'acceptera le système.


4.2.5.9. Montrer ce que l'utilisateur doit renseigner

Il arrivera souvent que vous vouliez montrer à l'utilisateur ce qu'il doit faire, faire référence à un fichier, à une ligne de commande, ou autre, dans lesquels l'utilisateur ne pourra pas purement et simplement copier les examples que vous lui donnez, mais devra y renseigner lui-même certaines informations.

replaceable est prévu pour ces cas-là. Servez-vous en à l'intérieur d'autres éléments pour indiquer quels contenus l'utilisateur doit remplacer.

Exemple 4.42. replaceable

Utilisez :

<informalexample>
  <screen>&prompt.user; <userinput>man
  <replaceable>command</replaceable></userinput></screen>
</informalexample>

Apparence :

% man command

replaceable peut servir dans de nombreux autres éléments, dont literal. Cet exemple montre aussi qu'il ne faut mettre replaceable qu'autour du contenu que l'utilisateur doit fournir. Il faut laisser le reste tel quel.

Utilisez :

<para>La ligne <literal>maxusers 10</literal> du fichier
  de configuration du noyau détermine la table de nombreuses
  tables système et définit approximativement le nombre
  de connexions simultanées qu'acceptera le système.</para>

<para><literal>32</literal> est un valeur correcte de
  <replaceable>n</replaceable> pour une station
  de travail.</para>

Apparence :

La ligne maxusers 10 du fichier de configuration du noyau détermine la table de nombreuses tables système et définit approximativement le nombre de connexions simultanées qu'acceptera le système.

32 est un valeur correcte de n pour une station de travail.


4.2.6. Liens

Note:

Les liens sont aussi des éléments en ligne.

4.2.6.1. Mettre des liens vers d'autres parties du même document

Pour mettre de liens à l'intérieur même du document, il faut que vous précisiez d'où part le lien (i.e., le texte ou autre, sur lequel l'utilisateur clique) et où il va.

Chaque élément DocBook possède un attribut id. Vous pouvez utiliser cet attribut pour donner un nom unique à l'élément.

C'est cette valeur que vous utiliserez quand vous préciserez la destination du lien.

Habituellement, vous mettrez des liens sur des chapitres ou des sections, vous ajouterez donc un attribut id à ces éléments.

Exemple 4.43. id de chapitres et de section
<chapter id="chapitre1">
  <title>Introduction</title>

  <para>C'est l'introduction. Elle comporte une sous-section,
    qui a aussi un identifiant.</para>

  <sect1 id="chapter1-sect1">
    <title>Sous-section 1</title>

    <para>C'est la sous-section.</para>
  </sect1>
</chapter>

Vous devriez utiliser des valeurs plus explicites. Ces valeurs doivent être uniques pour le document (i.e., pas uniquement dans le fichier, mais dans le document dans lequel le fichier peut éventuellement être inclus aussi). Remarquez que l'id de la sous-section est construit en le préfixant de l'id du chapitre. Cela aide à construire des identifiants uniques.

Si vous voulez que l'utilisateur puisse aller à un endroit précis du document (éventuellement au milieu du paragraphe), ou à un exemple, servez-vous de anchor. Cet élément n'a pas de contenu, mais il a un attribut id.

Exemple 4.44. anchor
<para>Ce paragraphe inclut un
  <anchor id="para1">lien interne. Il n'apparaît
  pas dans le document.</para>

Si vous voulez fournir à l'utilisateur un lien qu'il puisse activer (probablement en cliquant dessus) pour aller à une section du document qui a un attribut id, vous pouvez vous servir de xref ou link.

Ces deux éléments ont un attribut linkend. La valeur de cette attribut doit être celle que vous avez utilisée comme attribut id (peu importe si cette valeur n'a pas encore été définie dans le document, les liens peuvent être en avant ou en arrière).

Si vous vous servez de xref, vous n'avez pas le contrôle du texte du lien. Il sera généré automatiquement.

Exemple 4.45. Se servir de xref

Supposons que ce fragment apparaisse quelque part dans un document qui contienne l'exemple que nous avons donné pour id :

<para>Vous trouverez plus d'information
  au <xref linkend="chapter1">.</para>

<para>Vous trouverez des informations plus détaillées dans
  <xref linkend="chapter1-sect1">.</para>

Le texte du lien sera généré automatiquement, et cela ressemblera à (le texte mis en valeur indique que c'est cela le lien) :

Vous trouverez plus d'information au Chapitre Un.

Vous trouverez des informations plus détaillées dans la section appellée Sous-section 1.


Remarquez que le texte du lien est construit à partir du titre de la section ou du numéro du chapitre.

Note:

Cela veut dire que vous ne pouvez pas utiliser xref pour mettre un lien sur l'attribut id d'un élément anchor. L'anchor n'a pas de contenu et xref ne pourrait donc pas générer le texte du lien.

Si vous voulez avoir la maîtrise du texte du lien, servez-vous alors de link. Cet élément encadre un contenu qui sera utilisé comme lien.

Exemple 4.46. Utiliser link

Supposons que ce fragment apparaisse quelque part dans un document qui contienne l'exemple que nous avons donné pour id :

<para>Vous trouverez plus d'information
  au <link linkend="chapter1">premier chapitre</link>.</para>

<para>Vous trouverez des informations plus détaillées dans
  <link linkend="chapter1-sect1">cette</link>
  section.</para>

Ce qui générera (le texte mis en valeur indique que c'est cela le lien) :

Vous trouverez plus d'information au premier chapitre.

Vous trouverez des informations plus détaillées dans cette section.


Note:

Le dernier exemple n'est pas à suivre. N'utilisez jamais “ce” ou “ici” comme origine du lien. Le lecteur devra détailler le contexte dans lequel c'est employé pour comprendre où le lien va le mener.

Note:

Vous pouvez vous servir de link pour mettre un lien sur un id ou une anchor, puisque le contenu du link définit le texte qui sera utilisé comme lien.

4.2.6.2. Liens vers d'autres documents sur le WWW

Mettre des liens sur des documents externes est beaucoup plus facile, si tant est que vous connaissiez l'URL du document sur lequel vous voulez mettre un lien. Servez-vous de ulink. L'attribut url sera l'URL de la page où pointera le lien, et le contenu du lien sera utilisé pour que l'utilisateur puisse l'activer.

Exemple 4.47. ulink

Utilisez :

<para>Vous pouvez bien sûr cessez de lire
  ce document, et aller au lieu de cela sur la <ulink
    url="http://www.FreeBSD.org/"> page Web de FreeBSD</ulink>.</para>

Apparence :

Vous pouvez bien sûr cessez de lire ce document, et aller au lieu de cela sur la page Web de FreeBSD.




[3] Il y a d'autres types de listes dans DocBook, mais ils ne nous concernent pas pour le moment.

Ce document, ainsi que d'autres peut être téléchargé sur ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/

Pour toutes questions à propos de FreeBSD, lisez la documentation avant de contacter <questions@FreeBSD.org>.

Pour les questions sur cette documentation, contactez <doc@FreeBSD.org>.