Introduction au Projet de Documentation de FreeBSD pour les nouveaux participants
Précédent Chapitre 4. Marques SGML Suivant

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/sgml/freebsd.dtd.

4.2.2. Identifiant Public Formel - Formal Public Indentifier, (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é <chapter>s. C'est une obligation. Il peut y avoir des <part>s entre le livre et le chapitre s'il 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>

    ...
  </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>

        ...
      </sect3>
    </sect2>

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

      ...
    </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 <part>s

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

<part>
  <title>Introduction</title>

  <chapter>
    <title>Resum&eacute;</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 <para>s vous suffiront. Les <formalpara>s ont un <title>, et avec les <simpara>s, certains éléments sont interdits à l'intérieur du paragraphe. Tenez-vous en aux <para>s.

Exemple 4-26. <para>

Utilisez :

<para>C'est un paragraphe. Il peut contenir
  presque n'importe quel autre &eacute;l&eacute;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&eacute;ambule &agrave; la Constitution des Etats-Unis</title>

  <attribution>Copi&eacute; d'un site Web quelque part</attribution>
        
  <para>Nous le Peuple des Etats-Unis, dans le but de former
    une Union plus parfaite, d'&eacute;tablir la Justice, de garantir
    la Tranquilit&eacute; domestique, assurer la d&eacute;fense collective,
    promouvoir notre Bien-&ecirc;tre g&eacute;n&eacute;ral, et conserver &agrave;
    nous-m&ecirc;mes et &agrave; notre Post&eacute;rit&eacute; les bienfaits de la
    Libert&eacute;, proclamons et &eacute;tablissons cette Constitution des
    Etats-Unis d'Am&eacute;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>[1]

<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 <step>s, qui à leur tour sont composés de <step>s ou <substep>s. Chaque <step> contient des éléments de blocs.

Exemple 4-29. <itemizedlist>, <orderedlist> et <procedure>

Utilisez :

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

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

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

  <listitem>
    <para>C'est le second &eacute;l&eacute;ment de la liste ordonn&eacute;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 élements 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 1 C'est le titre de la colonne 2
Ligne 1, colonne 1 Ligne 1, colonne 2
Ligne 2, colonne 1 Ligne 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 1 C'est le titre de la colonne 2
Ligne 1, colonne 1 Ligne 1, colonne 2
Ligne 2, colonne 1 Ligne 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&egrave;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/sgml/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 &eacute;lectronique le plus employ&eacute; 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&egrave;tres de la ligne de commande de
  <citerefentry><refentrytitle>sendmail</refentrytitle>
    <manvolnum>8</manvolnum></citerefentry>,
    <option>-bp</option>, affiche l'&eacute;tat des messages
    dans la file d'attente. V&eacute;rifiez-le en ex&eacute;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&eacute;f&eacute;rence en Anglais dans
  <filename>/usr/doc/en/handbook/</filename>. Le
  fichier principal, dans ce r&eacute;pertoire, s'appelle
  <filename>handbook.sgml</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.sgml. 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&eacute;ries.
  <devicename>sio</devicename> correspond
  &agrave; un certain nombre d'entr&eacute;es dans
  <filename>/dev</filename>, dont
  <filename>/dev/ttyd0</filename> et
  <filename>/dev/cuaa0</filename>.</para>

<para>A l'inverse, les p&eacute;riph&eacute;riques r&eacute;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éciamales sur deux positions séparées par des deux-points.

Exemple 4-38. <hostid> et roles

Utilisez :

<para>La machine locale peut toujours
  &ecirc;tre d&eacute;sign&eacute;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&eacute;seau
  <hostid role="netmask">255.255.255.255</hostid>
  (qui peut aussi s'&eacute;crire
  <hostid role="netmask">0xffffffff)</hostid>.</para>

<para>L'adresse MAC identifie de fa&ccedil;on unique
  chaque carte r&eacute;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&acirc;ches d'administration syst&egrave;me,
  vous aurez besoin d'&ecirc;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&eacute;n&eacute;ralement, invoquer <maketarget>all</maketarget>
  reconstruit l'application, et invoquer
  <maketarget>clean</maketarget> supprime les
  fichiers temporaires (<filename>.o</filename>
  par exemple) cr&eacute;&eacute;s lors de la reconstruction.</para>

<para><maketarget>clean</maketarget> peut &ecirc;tre
  contr&ocirc;l&eacute;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&eacute;termine la table de nombreuses
  tables syst&egrave;me et d&eacute;finit approximativement le nombre de
  connexions simultan&eacute;es qu'acceptera le syst&egrave;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'utitilisateur 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&eacute;termine la table de nombreuses
  tables syst&egrave;me et d&eacute;finit approximativement le nombre
  de connexions simultan&eacute;es qu'acceptera le syst&egrave;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&icirc;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&eacute;taill&eacute;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&eacute;taill&eacute;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&ucirc;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.

Notes

[1]

Il y a d'autres types de listes dans DocBook, mais ils ne nous concernent pas pour le moment.
Précédent Sommaire Suivant
Marques SGML Niveau supérieur * LinuxDoc

Ce document, ainsi que d'autres peut être téléchargé sur 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>.

Hosting by: Hurra Communications GmbH
Generated: 2007-01-26 18:01:12