diff options
Diffstat (limited to 'fr_FR.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml')
| -rw-r--r-- | fr_FR.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml | 2356 |
1 files changed, 0 insertions, 2356 deletions
diff --git a/fr_FR.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/fr_FR.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml deleted file mode 100644 index a131820fd0..0000000000 --- a/fr_FR.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml +++ /dev/null @@ -1,2356 +0,0 @@ -<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. - - Redistribution and use in source (SGML DocBook) and 'compiled' forms - (SGML HTML, PDF, PostScript, RTF and so forth) with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code (SGML DocBook) must retain the above - copyright notice, this list of conditions and the following - disclaimer as the first lines of this file unmodified. - - 2. Redistributions in compiled form (transformed to other DTDs, - converted to PDF, PostScript, RTF and other formats) must reproduce - the above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other materials - provided with the distribution. - - THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES - (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - $Id: chapter.sgml,v 1.1 2000-06-12 15:46:41 gioria Exp $ ---> - -<chapter id="sgml-markup"> - <title>Marques SGML</title> - - <para>Ce chapitre décrit les trois langages de marquage que vous - rencontrerez si vous contribuez au Projet de Documentation de FreeBSD. - Chaque section décrit le langage et détaille les marques que vous serez - probablement amenés à utiliser, ou qui sont déjà utilisées.</para> - - <para>Ces langages sont riches en éléments et il est parfois difficile de - savoir lequels employer dans un contexte particulier. Cette section - décrit ceux dont vous aurez probablement besoin et donne des exemples de - la manière de s'en servir.</para> - - <para>Ce n'est <emphasis>pas</emphasis> une liste exhaustive d'éléments, - cela ne ferait que reprendre le contenu de la documentation de chacun de - ces langages. L'objectif de cette section est de lister les éléments qui - ont le plus de chance de vous être utiles. Si vous avez des questions sur - le type de marque à employer dans un contexte particulier, posez-les s'il - vous plaît à la liste de diffusion du Projet de Documentation de FreeBSD, - <email>freebsd-doc@freebsd.org</email>.</para> - - <note> - <title>En ligne vs. de bloc</title> - - <para>Dans la suite de ce document, quand on décrira des éléments, - <emphasis>en ligne</emphasis> signifie que l'élément peut apparaître à - l'intérieur d'un bloc et ne génère pas de passage à la ligne. A - l'inverse un élément de bloc provoque un passage à la ligne (et d'autres - opérations) lorsqu'on le rencontre.</para> - </note> - - <sect1> - <title>HTML</title> - - <para>HTML, l'<foreignphrase>HyperText Markup - Language</foreignphrase> - Langage de Marquage de - l'Hypertexte - est le langage de prédilection du - World Wide Web. Vous trouverez plus d'informations sur - <URL:<ulink - url="http://www.w3.org/">http://www.w3.org/</ulink>>.</para> - - <para>HTML est utilisé pour marquer les pages du site Web de FreeBSD. Il - ne devrait (habituellement) pas servir pour d'autre type de - documentation, parce que DocBook offre un jeu de marques beaucoup plus - riche. Vous ne devriez donc rencontrez des pages HTML que si vous - écrivez pour le site Web.</para> - - <para>Il y a eu plusieurs versions de HTML, 1, 2, 3.0, 3.2, et il existe - deux variantes de la dernière version, 4.0 (disponible à la fois en - version <emphasis>stricte</emphasis> et - <emphasis>relachée</emphasis>).</para> - - <para>Les DTDs HTML existent au catalogue des logiciels portés dans - <filename>textproc/html</filename>. Elles sont automatiquement - installées par le méta-port - <filename>textproc/docproj</filename>.</para> - - <sect2> - <title><foreignphrase>Formal Public Identifier - (FPI)</foreignphrase> - Identifiant Public Formel</title> - - <para>Il y a un certain nombre de FPIs HTML, selon la version (qu'on - appelle aussi le niveau) de HTML avec laquelle vous voulez que votre - document soit compatible.</para> - - <para>La plupart des documents HTML du site Web de FreeBSD respectent - strictement la version relachée de HTML 4.0 :</para> - - <programlisting> -PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> - </sect2> - - <sect2> - <title>Sections</title> - - <para>Un document HTML est habituellement composé de deux sections. La - première section, appelée - <emphasis>head</emphasis> - en-tête, contient des - informations sur le document, comme son titre, le nom de son auteur, - le document dans lequel il est inclus, et ainsi de suite. La seconde - section, le <emphasis>body</emphasis> - corps, contient ce - qui sera affiché.</para> - - <para>Ces sections sont dénotées par les éléments - <sgmltag>head</sgmltag> et <sgmltag>body</sgmltag> respectivement. Ces - éléments appartiennent à l'élément de premier niveau - <sgmltag>html</sgmltag>.</para> - - <example> - <title>Structure habituelle d'un document HTML</title> - - <programlisting> -<html> - <head> - <title><replaceable>Le titre du document</replaceable></title> - </head> - - <body> - - … - - </body> -</html></programlisting> - </example> - </sect2> - - <sect2> - <title>Eléments de blocs</title> - - <sect3> - <title>Titres</title> - - <para>HTML vous permet d'avoir jusqu'à six niveaux de titres - différents dans votre document.</para> - - <para>Le titre le plus gros et le plus visible est - <sgmltag>h1</sgmltag>, puis <sgmltag>h2</sgmltag>, jusqu'à - <sgmltag>h6</sgmltag>.</para> - - <para>Le contenu de l'élément est le texte du titre.</para> - - <example> - <title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, etc.</title> - - <para>Utilisez :</para> - - <programlisting> -<![ CDATA [<h1>Première section</h1> - -<!-- Introduction du document --> - -<h2>C'est le titre de la première section</h2> - -<!-- Contenu de la première section --> - -<h3>C'est le titre de la première sous-section</h3> - -<!-- Contenu de la première sous-section --> - -<h2>C'est le titre de la seconde section</h2> - -<!-- Contenu de la seconde section -->]]></programlisting> - </example> - - <para>Un page HTML doit normalementi avoir un titre de premier niveau - (<sgmltag>h1</sgmltag>). Il peut contenir plusieurs titres de second - niveau (<sgmltag>h2</sgmltag>), et à leur tour, de nombreux titres - de troisième niveau. Chaque élément - <sgmltag>h<replaceable>n</replaceable></sgmltag> doit appartenir à - un même élément de niveau supérieur. Il faut éviter de sauter d'un - cran dans la numérotation.</para> - - <example> - <title>Mauvais ordonnancement des éléments - <sgmltag>h<replaceable>n</replaceable></sgmltag></title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<h1>Première section</h1> - -<!-- Introduction du document --> - -<h3>Sous-section</h3> - -<!-- Ce n'est pas bon, <h2> a été oublié -->]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Paragraphes</title> - - <para>HTML n'a qu'un seul élément paragraphe, - <sgmltag>p</sgmltag>.</para> - - <example> - <title><sgmltag>p</sgmltag></title> - - <para>Utilisez :</para> - - <programlisting> -<![ CDATA [<p>C'est un paragraphe. Il peut contenir pratiquement - n'importe quel élément.</p>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Citations</title> - - <para>Une citation d'un long extrait d'un autre document, qui ne doit - pas apparaître dans le paragraphe en cours, mais est mise dans un bloc - de citation.</para> - - <example> - <title><sgmltag>blockquote</sgmltag></title> - - <para>Utilisez :</para> - - <programlisting> -<![ CDATA [<p>Un court extrait de la Constitution des Etats-Unis :</p> - -<blockquote>Nous le Peuple des Etats-Unis, dans le But de former - une Union plus parfaite, d'établir la Justice, d'assurer - la Tranquilité domestique, de défendre chacun, de promouvoir - le Bien-être général, et de garantir les Bénédictions de - la Liberté à nous-mêmes et à notre Postérité, décidons et - établissons cette Constitution des Etats-Unis d'Amérique.</blockquote>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Listes</title> - - <para>Il y a trois types de listes que vous pouvez afficher : - ordonnée, non ordonnée et de définition.</para> - - <para>Typiquement, chaque entrée d'une liste ordonnée sera numérotée, - alors que chaque entrée d'une liste non ordonnée sera précédée d'une - puce. Les listes de définition ont deux sections pour chaque entrée. - La première est le terme que l'on définit et la seconde sa - définition.</para> - - <para>Les listes ordonnées sont dénotées par l'élément - <sgmltag>ol</sgmltag>, les listes non ordonnées par l'élément - <sgmltag>ul</sgmltag> et les listes de définition par l'élément - <sgmltag>dl</sgmltag> element.</para> - - <para>Les listes ordonnées et non ordonnées contiennent des éléments - de liste, notés avec l'élément <sgmltag>li</sgmltag>. Un élément de - liste peut contenir du texte, ou être décomposé en plusieurs - éléments <sgmltag>p</sgmltag>.</para> - - <para>Les listes de définition contiennent des termes à définir - (<sgmltag>dt</sgmltag>) et leurs définitions - (<sgmltag>dd</sgmltag>). Le terme à définir n'est composé que de - texte. La définition peut comporter d'autres éléments de - blocs.</para> - - <example> - <title><sgmltag>ul</sgmltag> et <sgmltag>ol</sgmltag></title> - - <para>Utilisez :</para> - - <programlisting> -<![ CDATA [<p>Une liste non ordonnée. Les éléments de la liste seront - probablement précédés par des puces.</p> - -<ul> - <li>Premier élément</li> - - <li>Second élément</li> - - <li>Troisième élément</li> -</ul> - -<p>Une liste ordonnée, dont les éléments comportent plusieurs paragraphes. - Chaque élément (note : et non chaque paragraphe) sera numéroté.</p> - -<ol> - <li><p>C'est le premier élément. Il n'a qu'un paragraphe..</p></li> - - <li><p>C'est le premier paragraphe du second élément.</p> - - <p>C'est le second paragraphe du second élément.</p> - - <li><p>C'est le premier et seul paragraphe du troisième élément.</p></li> -</ol>]]></programlisting> - </example> - - <example> - <title>Listes de définition avec <sgmltag>dl</sgmltag></title> - - <para>Utilisez :</para> - - <programlisting> -<![ CDATA [<dl> - <dt>Terme 1</dt> - - <dd><p>Paragraphe 1 de la définition 1.</p></dd> - - <p>Paragraphe 2 de la définition 1.</p></dd> - - <dt>Terme 2</dt> - - <dd><p>Paragraphe 1 de la définition 2.</p></dd> - - <dt>Terme 3</dt> - - <dd>Paragraphe 1 de la définition 3. Remarquez que l'élément <p> n'est - pas obligatoire dans le cas d'un paragraphe unique.</dd> -</dl>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Texte pré-formaté</title> - - <para>Vous pouvez préciser que du texte doit apparaître exactement - comme il est présenté dans le fichier. Cela signifie habituellement - que le texte est affiché en police fixe, que les blancs successifs - sont conservés et que les passages à la ligne dans le texte sont - significatifs.</para> - - <para>Pour cela, il faut mettre ce texte dans un élément - <sgmltag>pre</sgmltag>.</para> - - <example> - <title><sgmltag>pre</sgmltag></title> - - <para>Vous pouvez utiliser <sgmltag>pre</sgmltag> pour marquer le - texte d'un courrier électronique :</para> - - <programlisting> -<![ CDATA [<pre> - From: nik@freebsd.org - To: freebsd-doc@freebsd.org - Subject: Nouvelle documentation disponible - - Une nouvelle version de mon introduction pour les nouveaux - participants au Projet de Documentation de FreeBSD est - disponible à l'adresse suivante : - - <URL:http://www.freebsd.org/~nik/primer/index.html> - - Commentaires souhaités. - - N -</pre>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Tables</title> - - <note> - <para>La plupart des navigateurs en mode texte (comme Lynx) - n'affichent pas très bien les tables. Si vous utilisez ce type de - présentation en tableaux, vous devriez envisager d'utiliser - d'autres marques pour éviter la confusion.</para> - </note> - - <para>Marquez les tableaux avec l'élément <sgmltag>table</sgmltag>. - Un tableau est composé d'une ou plusieurs lignes - (<sgmltag>tr</sgmltag>), chacune contenant une ou plusieurs - cellules (<sgmltag>td</sgmltag>). Chaque cellule peut contenir - d'autres éléments de bloc, des paragraphes ou des listes par - exemple. Elle peut aussi contenir d'autres tables (cet emboîtement - peut se répéter indéfiniment). Si la cellule ne contient qu'un seul - paragraphe, l'élément <sgmltag>p</sgmltag> n'est pas - obligatoire.</para> - - <example> - <title>Emploi simple de <sgmltag>table</sgmltag></title> - - <para>Utilisez :</para> - - <programlisting> -<![ CDATA [<p>C'est une table 2x2 simple.</p> - -<table> - <tr> - <td>Cellule en haut à gauche</td> - - <td>Cellule en haut à droite</td> - </tr> - - <tr> - <td>Cellule en bas à gauche</td> - - <td>Cellule en bas à droite</td> - </tr> -</table>]]></programlisting></example> - - <para>Une cellule peut occuper plusieurs lignes ou colonnes. Pour le - préciser, ajoutez les attributs <literal>rowspan</literal> et/ou - <literal>colspan</literal>, dont les valeurs donnent le nombre de - lignes et de colonnes occupées.</para> - - <example> - <title>Emploi de <literal>rowspan</literal></title> - - <para>Utilisez :</para> - - <programlisting> -<![ CDATA [<p>Une grande cellule à gauche, deux petites cellule à droite.</p> - -<table> - <tr> - <td rowspan="2">Grande et mince</td> - </tr> - - <tr> - <td>Cellule du haut</td> - - <td>Cellule du bas</td> - </tr> -</table>]]></programlisting> - </example> - - <example> - <title>Emploi de <literal>colspan</literal></title> - - <para>Utilisez :</para> - - <programlisting> -<![ CDATA [<p>Une grande cellule en haut, deux petites cellules en dessous.</p> - -<table> - <tr> - <td colspan="2">Cellule du haut</td> - </tr> - - <tr> - <td>Cellule du bas à gauche</td> - - <td>Cellule du bas à droite</td> - </tr> -</table>]]></programlisting> - </example> - - <example> - <title>Emploi de <literal>rowspan</literal> et - <literal>colspan</literal> ensemble</title> - - <para>Use:</para> - - <programlisting> -<![ CDATA [<p>Sur une grille 3x3, la cellule en haut à gauche d'étend sur deux - lignes et deux colonnes. Les autres cellules sont normales.</p> - -<table> - <tr> - <td colspan="2" rowspan="2">Grande cellule en haut à gauche</td> - - <td>Cellule en haut à droite</td> - </tr> - - <tr> - <!-- Comme la grande cellule se prolonge - sur cette colonne, la première cellule - marquée par <td> se trouvera à sa droite --> - - <td>Cellule du milieu à droite</td> - </tr> - - <tr> - <td>Cellule en bas à gauche</td> - - <td>Cellule en bas au milieu</td> - - <td>Cellule en bas à droite</td> - </tr> -</table>]]></programlisting> - </example> - </sect3> - </sect2> - - <sect2> - <title>Eléments</title> - - <sect3> - <title>Information d'accentuation</title> - - <para>Il y a deux niveaux d'accentuation disponibles en HTML, - <sgmltag>em</sgmltag> et <sgmltag>strong</sgmltag>. - <sgmltag>em</sgmltag> marque une accentuation normale et - <sgmltag>strong</sgmltag> une accentuation plus prononcée.</para> - - <para><sgmltag>em</sgmltag> est généralement rendu en italiques et - <sgmltag>strong</sgmltag> en gras. Ce n'est malgré tout pas toujours - le cas, et il ne faut pas se baser là-dessus.</para> - - <example> - <title><sgmltag>em</sgmltag> et <sgmltag>strong</sgmltag></title> - - <para>Utilisez :</para> - - <programlisting> -<![ CDATA [<p><em>Ceci</em> est accentué, et - <strong>cela</strong> l'est encore plus.</p>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Gras et italiques</title> - - <para>HTML comporte des marques pour la présentation, vous pouvez donc - aussi préciser qu'un contenu donné doit apparaître en gras ou en - italiques. Les éléments pour cela sont respectivement - <sgmltag>b</sgmltag> et <sgmltag>i</sgmltag>.</para> - - <example> - <title><sgmltag>b</sgmltag> et <sgmltag>i</sgmltag></title> - - <programlisting> -<![ CDATA [<p><b>Ceci</b> est en gras, tandis que <i>cela</i> est - en italiques.</p>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Texte en police fixe</title> - - <para>S'il y a du texte qui doit être affiché en police fixe (machine - à écrire), servez-vous de <sgmltag>tt</sgmltag> ( pour - “télétype”).</para> - - <example> - <title><sgmltag>tt</sgmltag></title> - - <para>Utilisez :</para> - - <programlisting> -<![ CDATA [<p>L'auteur original de ce document est - Nik Clayton, qui peut être contacté par courrier - électronique à l'adresse : <tt>nik@freebsd.org</tt>.</p>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Taille de police</title> - - <para>Vous pouvez préciser qu'un contenu doit être affiché en police - plus grande ou plus petite. Il y a trois façons de le faire.</para> - - <orderedlist> - <listitem> - <para>Utilisez <sgmltag>big</sgmltag> et <sgmltag>small</sgmltag> - pour encadrer le texte dont vous voulez modifier la taille. Ces - marques peuvent être imbriquées, il est donc possible - d'avoir : <literal><big><big>C'est bien plus - gros</big></big></literal>.</para> - </listitem> - - <listitem> - <para>Servez-vous de <sgmltag>font</sgmltag> avec l'attribut - <literal>size</literal> prenant respectivement les valeurs - <literal>+1</literal> ou <literal>-1</literal>. C'est la même - chose que d'utiliser <sgmltag>big</sgmltag> ou - <sgmltag>small</sgmltag>. Mais cette façon de faire est - obsolète.</para> - </listitem> - - <listitem> - <para>Utilisez <sgmltag>font</sgmltag> avec l'attribut - <literal>size</literal> prenant une valeur de 1 à 7. La taille - de police par défaut est <literal>3</literal>. Cette façon de - faire est aussi obsolète.</para> - </listitem> - </orderedlist> - - <example> - <title><sgmltag>big</sgmltag>, <sgmltag>small</sgmltag> et - <sgmltag>font</sgmltag></title> - - <para>Les trois extraits suivants ont le même résultat :</para> - - <programlisting> -<![ CDATA [<p>Ce texte est <small>un peu plus petit</small>. - Mais celui-là <big>est un peu plus gros</big>.</p> - -<p>Ce texte est <font size="-1">un peu plus petit</font>. - Mais celui-là <font size="+1">est un peu plus gros</font>.</p> - -<p>Ce texte est <font size="2">un peu plus petit</font>. - Mais celui-là <font size="4">est un peu plus gros</font>.</p>]]></programlisting> - </example> - </sect3> - </sect2> - - <sect2> - <title>Liens</title> - - <note> - <para>Les liens font aussi partie du contenu du document.</para> - </note> - - <sect3> - <title>Liens vers d'autres documents sur le WWW</title> - - <para>Pour mettre un lien sur un autre document sur le WWW, il faut - que vous connaissiez l'URL de ce document.</para> - - <para>Ce lien est noté avec <sgmltag>a</sgmltag> et l'attribut - <literal>href</literal> contient l'URL du document cible. Le - lien est le contenu de l'élément, il est habituellement présenté - d'une façon ou d'une autre à l'utilisateur (souligné, couleur - différente, curseur de forme différente quand on passe dessus, et - ainsi de suite).</para> - - <example> - <title>Emploi de <literal><a href="..."></literal></title> - - <para>Utilisez :</para> - - <programlisting> -<![ CDATA [<p>Vous trouverez plus d'informations sur le - <a href="http://www.freebsd.org/">site Web de FreeBSD</a>.</p>]]></programlisting> - </example> - - <para>Ces liens amèneront l'utilisateur au début du document - sélectionné.</para> - </sect3> - - <sect3> - <title>Liens sur d'autres parties des documents</title> - - <para>Pour mettre un lien sur un endroit précis d'un autre (ou du - même) document, il faut que l'auteur de ce document y ait mis des - points d'ancrage sur lequels vous pouvez pointer.</para> - - <para>Les points d'ancrage sont notés avec <sgmltag>a</sgmltag> et - l'attribut <literal>name</literal> au lieu de - <literal>href</literal>.</para> - - <example> - <title>Emploi de <literal><a name="..."></literal></title> - - <para>Utilisez :</para> - - <programlisting> -<![ CDATA [<p><a name="para1">Ce</a> paragraphe peut être référencé - par d'autres liens via le nom <tt>para1</tt>.</p>]]></programlisting> - </example> - - <para>Pour mettre un lien sur une partie nommée d'un document, utilisez - un lien ordinaire, mais ajoutez-y le nom du point d'ancrage précédé - d'un symbole <literal>#</literal>.</para> - - <example> - <title>Lien sur une partie nommée d'un autre document</title> - - <para>Supposons que l'exemple <literal>para1</literal> se trouve - dans un document appelé <filename>foo.html</filename>.</para> - - <programlisting> -<![ CDATA [<p>Vous trouverez plus d'informations au - <a href="foo.html#para1">premier paragraphe</a> de - <tt>foo.html</tt>.</p>]]></programlisting> - </example> - - <para>Si le lien pointe sur un point d'ancrage nommé du même document, - vous pouvez ommettre son URL et ne mettre que le nom du point - d'ancrage (précédé de <literal>#</literal>).</para> - - <example> - <title>Lien sur une partie nommée du même document</title> - - <para>Supposons que l'exemple <literal>para1</literal> fasse partie - de ce document.</para> - - <programlisting> -<![ CDATA [<p>Vous trouverez plus d'informations au - <a href="#para1">premier paragraphe</a> de - ce document.</p>]]></programlisting> - </example> - </sect3> - </sect2> - </sect1> - - <sect1> - <title>DocBook</title> - - <para>DocBook est une DTD créée par le <ulink - url="http://www.oreilly.com/davenport/">Davenport Group</ulink> - 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 <emphasis>ce qu'est</emphasis> quelque chose que - <emphasis>comment</emphasis> il faut le présenter.</para> - - <note> - <title><literal>formel</literal> vs. <literal>informel</literal></title> - - <para>Certains éléments ont deux - versions - <emphasis>formelle</emphasis> et - <emphasis>informelle</emphasis>. Habituellement, la version formelle - de l'élément comporte une titre. La version informelle n'en a - pas.</para> - </note> - - <para>La DTD DocBook est disponible au catalogue des logiciels portés avec - le “méta-logiciel porté” - <filename>textproc/docbook</filename>. Elle est automatiquement - installée par ce dernier.</para> - - <sect2> - <title>Extensions FreeBSD</title> - - <para>Le Projet de Documentation de FreeBSD a ajouté quelques nouveaux - éléments à la DTD DocBook. Ces éléments permettent un marquage plus - précis.</para> - - <para>Dans la suite, quand il sera question d'un élément propre à - FreeBSD, ce sera clairement indiqué.</para> - - <para>Le terme “DocBook” désigne dans ce qui suit la DTD - DocBook avec les extensions FreeBSD.</para> - - <note> - <para>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 - <email>nik@FreeBSD.org</email>.</para> - </note> - - <para>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 - <filename>doc/share/sgml/freebsd.dtd</filename>.</para> - </sect2> - - <sect2> - <title>Identifiant Public Formel - <foreignphrase>Formal - Public Indentifier</foreignphrase>, (FPI)</title> - - <para>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 :</para> - - <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> - </sect2> - - <sect2> - <title>Structure des documents</title> - - <para>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.</para> - - <para>Un livre est organisé <sgmltag>chapter</sgmltag>s. C'est une - obligation. Il peut y avoir des <sgmltag>part</sgmltag>s entre le - livre et le chapitre s'il l'on veut un niveau supplémentaire dans le - découpage.</para> - - <para>Un chapitre peut avoir (ou non) une ou plusieurs sections. Elles - sont désignées par l'élément <sgmltag>sect1</sgmltag>. Si une section - inclue une autre section, utilisez l'élément <sgmltag>sect2</sgmltag>, - et ainsi de suite, jusqu'à <sgmltag>sect5</sgmltag>.</para> - - <para>Le contenu du livre est lui-même dans les chapitres et - sections.</para> - - <para>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 - <sgmltag>sect1</sgmltag> (<sgmltag>sect2</sgmltag> et ainsi de suite) - dont on se sert pour les livres.</para> - - <para>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.</para> - - <para>Les <ulink url="&url.tutorials;">guides - FreeBSD</ulink> sont tous des articles, tandis que ce document, la - <ulink url="&url.faq;">FAQ FreeBSD</ulink>, et le - <ulink url="&url.handbook;">Manuel de Référence FreeBSD</ulink> sont - des livres.</para> - - <sect3> - <title>Commencer un livre</title> - - <para>Le contenu d'un livre est un inclus dans l'élément - <sgmltag>book</sgmltag>. 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.</para> - - <para>Ces informations supplémentaires doivent être inclues dans - l'élément <sgmltag>bookinfo</sgmltag>.</para> - - <example> - <title>Boilerplate??? <sgmltag>book</sgmltag> avec - <sgmltag>bookinfo</sgmltag></title> - - <!-- Can't put this in a marked section because of the - replaceable elements --> - <programlisting><book> - <bookinfo> - <title><replaceable>Mettez le titre ici</replaceable></title> - - <author> - <firstname><replaceable>Votre prénom</replaceable></firstname> - <surname><replaceable>Votre nom de famille</replaceable></surname> - <affiliation> - <address><email><replaceable>Votre adresse de courrier - électronique</replaceable></email></address> - </affiliation> - </author> - - <copyright> - <year><replaceable>1998</replaceable></year> - <holder role="mailto:<replaceable>Votre adresse de courrier - électronique</replaceable>"><replaceable>Votre nom</replaceable></holder> - </copyright> - - <pubdate role="rcs">$Date$</pubdate> - - <releaseinfo>$Id$</releaseinfo> - - <abstract> - <para><replaceable>Résumez ici le contenu du - livre.</replaceable></para> - </abstract> - </bookinfo> - - … - -</book></programlisting> - </example> - </sect3> - - <sect3> - <title>Commencer un article</title> - - <para>Le contenu d'un article est un inclus dans l'élément - <sgmltag>article</sgmltag>. 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.</para> - - <para>Ces informations supplémentaires doivent être inclues dans - l'élément <sgmltag>artheader</sgmltag>.</para> - - <example> - <title>Boilerplate??? <sgmltag>article</sgmltag> avec - <sgmltag>artheader</sgmltag></title> - - <!-- Can't put this in a marked section because of the - replaceable elements --> - <programlisting><article> - <artheader> - <title><replaceable>Mettez le titre ici</replaceable></title> - - <author> - <firstname><replaceable>Votre prénom</replaceable></firstname> - <surname><replaceable>Votre nom de famille</replaceable></surname> - <affiliation> - <address><email><replaceable>Votre adresse de courrier - électronique</replaceable></email></address> - </affiliation> - </author> - - <copyright> - <year><replaceable>1998</replaceable></year> - <holder role="mailto:<replaceable>Votre adresse de courrier - électronique</replaceable>"><replaceable>Votre nom</replaceable></holder> - </copyright> - - <pubdate role="rcs">$Date$</pubdate> - - <releaseinfo>$Id$</releaseinfo> - - <abstract> - <para><replaceable>Résumez ici le contenu de l'article.</replaceable></para> - </abstract> - </artheader> - - … - -</article></programlisting> - </example> - </sect3> - <sect3> - <title>Séparer les chapitres</title> - - <para>Utilisez <sgmltag>chapter</sgmltag> pour marquer vos chapitres. - Chaque chapitre a obligatoirement un <sgmltag>title</sgmltag>. Les - articles n'ont pas de chapitre, ils sont réservés aux livres.</para> - - <example> - <title>Un chapitre</title> - - <programlisting><![ CDATA [<chapter> - <title>Le titre du chapitre</title> - - ... -</chapter>]]></programlisting> - </example> - - <para>Un chapitre ne peut pas être vide, il doit contenir des éléments - en plus du <sgmltag>title</sgmltag>. Si vous voulez inclure un - chapitre vide, ajoutez lui simplement un paragraphe vide.</para> - - <example> - <title>Chapitres vides</title> - - <programlisting><![ CDATA [<chapter> - <title>C'est un chapitre vide</title> - - <para></para> -</chapter>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Sections dans les chapitres</title> - - <para>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 - <sgmltag>sect<replaceable>n</replaceable></sgmltag>. Le - <replaceable>n</replaceable> est le type de section, qui indique son - niveau de profondeur.</para> - - <para>La première <sgmltag>sect<replaceable>n</replaceable></sgmltag> - est <sgmltag>sect1</sgmltag>. Vous pouvez en avoir plus d'une dans - un chapitre. Elles peuvent inclure un ou plusieurs éléments - <sgmltag>sect2</sgmltag>, et ainsi de suite, jusqu'à - <sgmltag>sect5</sgmltag>.</para> - - <example> - <title>Sections dans les chapitres</title> - - <programlisting><![ RCDATA [<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>]]></programlisting> - </example> - - <note> - <para>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.</para> - </note> - </sect3> - - <sect3> - <title>Subdivision en <sgmltag>part</sgmltag>s</title> - - <para>Vous pouvez avoir un niveau d'organisation supplémentaire entre - le <sgmltag>book</sgmltag> et le <sgmltag>chapter</sgmltag> en - définissant une ou plusieurs <sgmltag>part</sgmltag>s. Ce n'est pas - possible dans un <sgmltag>article</sgmltag>.</para> - - <programlisting><![ CDATA [<part> - <title>Introduction</title> - - <chapter> - <title>Resumé</title> - - ... - </chapter> - - <chapter> - <title>Qu'est-ce que FreeBSD ?</title> - - ... - </chapter> - - <chapter> - <title>Historique</title> - - ... - </chapter> -</part>]]></programlisting> - </sect3> - </sect2> - - <sect2> - <title>Eléments de blocs</title> - - <sect3> - <title>Paragraphes</title> - - <para>DocBook connaît trois types de paragraphes : - <sgmltag>formalpara</sgmltag>, <sgmltag>para</sgmltag> et - <sgmltag>simpara</sgmltag>.</para> - - <para>La plupart du temps, des <sgmltag>para</sgmltag>s vous - suffiront. Les <sgmltag>formalpara</sgmltag>s ont un - <sgmltag>title</sgmltag>, et avec les <sgmltag>simpara</sgmltag>s, - certains éléments sont interdits à l'intérieur du paragraphe. - Tenez-vous en aux <sgmltag>para</sgmltag>s.</para> - - <example> - <title><sgmltag>para</sgmltag></title> - - <para>Utilisez :</para> - - <programlisting><![ CDATA [<para>C'est un paragraphe. Il peut contenir - presque n'importe quel autre élément.</para> ]]></programlisting> - - <para>Apparence :</para> - - <para>C'est un paragraphe. Il peut contenir presque n'importe quel - autre élément.</para> - </example> - </sect3> - - <sect3> - <title>Citations en bloc</title> - - <para>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.</para> - - <para>Les citations en blocs peuvent facultativement avoir un titre et - une attribution (ou n'avoir ni titre ni attribution).</para> - - <example> - <title><sgmltag>blockquote</sgmltag></title> - - <para>Utilisez :</para> - - <programlisting><![ CDATA [<para>Un court extrait de la constitution des Etats-Unis :</para> - -<blockquote> - <title>Préambule à 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 à - nous-mêmes et à notre Postérité les bienfaits de la - Liberté, proclamons et établissons cette Constitution des - Etats-Unis d'Amérique.</para> -</blockquote>]]></programlisting> - - <para>Apparence :</para> - - <para>Un court extrait de la constitution des - Etats-Unis :</para> - - <blockquote> - <title>Préambule à 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 à nous-mêmes et - à notre Postérité les bienfaits de la Liberté, proclamons et - établissons cette Constitution des Etats-Unis d'Amérique.</para> - </blockquote> - </example> - </sect3> - - <sect3> - <title>Indications, notes, avertissements, mises en garde, - informations importantes et barres verticales.</title> - - <para>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.</para> - - <para>Selon la nature de l'information, vous utiliserez l'un des - élements <sgmltag>tip</sgmltag>, <sgmltag>note</sgmltag>, - <sgmltag>warning</sgmltag>, <sgmltag>caution</sgmltag> ou - <sgmltag>important</sgmltag>. Ou bien, si l'information est en - rapport avec le texte, mais ne correspond à aucun des cas - précédents, servez-vous de <sgmltag>sidebar</sgmltag>.</para> - - <para>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 :</para> - - <itemizedlist> - <listitem> - <para>Une Note est une information destinée à tous les - lecteurs.</para> - </listitem> - - <listitem> - <para>Un élément Important est une variante de la Note.</para> - </listitem> - - <listitem> - <para>Une <foreignphrase>Caution</foreignphrase> est une - information relative à la perte de données ou dégats logiciels - éventuels.</para> - </listitem> - - <listitem> - <para>Un <foreignphrase>Warning</foreignphrase> est une - information relative aux dégats matériels ou risques - corporels.</para> - </listitem> - </itemizedlist> - - <example> - <title><sgmltag>warning</sgmltag></title> - - <para>Utilisez :</para> - - <programlisting><![ CDATA [<warning> - <para>Installer FreeBSD peut vous donner envie de supprimer - Windows de votre disque dur.</para> -</warning>]]></programlisting> - </example> - - <!-- Need to do this outside of the example --> - - <warning> - <para>Installer FreeBSD peut vous donner envie de supprimer Windows - de votre disque dur.</para> - </warning> - </sect3> - - <sect3> - <title>Listes and procédures</title> - - <para>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.</para> - - <para>Pour cela, servez-vous de <sgmltag>itemizedlist</sgmltag>, - <sgmltag>orderedlist</sgmltag> ou - <sgmltag>procedure</sgmltag><footnote><para>Il y a d'autres types de - listes dans DocBook, mais ils ne nous concernent pas pour le - moment.</para> - </footnote> - </para> - - <para><sgmltag>itemizedlist</sgmltag> et - <sgmltag>orderedlist</sgmltag> sont semblables à leurs contreparties - <sgmltag>ul</sgmltag> et <sgmltag>ol</sgmltag> en HTML. Chacune - comporte un ou plusieurs éléments <sgmltag>listitem</sgmltag>, et - chaque <sgmltag>listitem</sgmltag> contient un ou plusieurs éléments - de blocs. Les élements <sgmltag>listitem</sgmltag> sont analogues - aux marques <sgmltag>li</sgmltag> du HTML. Néanmoins, au contraire - du HTML, ils sont ici obligatoires.</para> - - <para>Une <sgmltag>procedure</sgmltag> est légérement différente. Elle - consiste en <sgmltag>step</sgmltag>s, qui à leur tour sont composés - de <sgmltag>step</sgmltag>s ou <sgmltag>substep</sgmltag>s. Chaque - <sgmltag>step</sgmltag> contient des éléments de blocs.</para> - - <example> - <title><sgmltag>itemizedlist</sgmltag>, - <sgmltag>orderedlist</sgmltag> et - <sgmltag>procedure</sgmltag></title> - - <para>Utilisez :</para> - - <programlisting><![ CDATA [<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>]]></programlisting> - - <para>Apparence :</para> - - <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> - </example> - - <!-- Can't have <procedure> inside <example>, so this is a cheat --> - - <procedure> - <step> - <para>Faites ceci.</para> - </step> - - <step> - <para>Puis cela.</para> - </step> - - <step> - <para>Et maintenant cela.</para> - </step> - </procedure> - </sect3> - - <sect3> - <title>Extraits de fichiers</title> - - <para>Si vous voulez incorporer un extrait de fichier (ou - éventuellement une fichier entier), mettez-le dans un élément - <sgmltag>programlisting</sgmltag>.</para> - - <para>Les blancs et sauts de ligne à l'intérieur de - <sgmltag>programlisting</sgmltag> <emphasis>sont</emphasis> - 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.</para> - - <example> - <title><sgmltag>programlisting</sgmltag></title> - - <para>Utilisez :</para> - - <programlisting><![ CDATA[<para>Quand vous aurez fini, votre programme - ressemblera à cela :</para> - -<programlisting>#include <stdio.h> - -int -main(void) -{ - printf("bonjour, le monde\n"); -}</programlisting>]]></programlisting> - - <para>Notez qu'il faut utiliser les entités correspondantes et non - les signes “supérieur” et “inférieur” à la - ligne <literal>#include</literal>.</para> - - <para>Apparence :</para> - - <para>Quand vous aurez fini votre programme, ressemblera à - cela :</para> - - <programlisting>#include <stdio.h> - -int -main(void) -{ - printf("bonjour, le monde\n"); -}</programlisting> - </example> - - <note> - <para>DocBook dispose d'un mécanisme pour faire référence à des - sections d'un <sgmltag>programlisting</sgmltag> inclus auparavant, - appelé “rappels” (voir - <sgmltag>programlistingco</sgmltag> 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”.</para> - </note> - </sect3> - - <sect3> - <title>Tables</title> - - <para>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.</para> - - <para>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 <sgmltag>table</sgmltag>. Il contient au - moins un élément <sgmltag>tgroup</sgmltag>, dont l'attribut donne - le nombre de colonnes dans ce sous-tableau. Dans le sous-tableau, - vous pouvez ensuite avoir un élément <sgmltag>thead</sgmltag>, qui - contient les élements correspondant aux en-têtes des colonnes, et - un <sgmltag>tbody</sgmltag> qui contient le corps du - tableau.</para> - - <para>Les <sgmltag>thead</sgmltag> et <sgmltag>tbody</sgmltag> - contiennent des éléments <sgmltag>row</sgmltag> - lignes, - qui contiennent à leur tour des éléments <sgmltag>entry</sgmltag>. - Chaque élément <sgmltag>entry</sgmltag> correspond à une cellule du - tableau.</para> - - <example> - <title><sgmltag>informaltable</sgmltag></title> - - <para>Utilisez :</para> - - <programlisting><![ CDATA [<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>]]></programlisting> - - <para>Apparence :</para> - - <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> - </example> - - <para>Si vous ne voulez pas de bordures autour du tableau, vous pouvez - ajouter à l'élément <sgmltag>informaltable</sgmltag> l'attribut - <literal>frame</literal> avec la valeur <literal>none</literal> - (i.e., <literal><informaltable - frame="none"></literal>).</para> - - <example> - <title>Tableaux avec <literal>frame="none"</literal></title> - - <para>Apparence :</para> - - <informaltable frame="none"> - <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> - </example> - </sect3> - - <sect3> - <title>Exemples que l'utilisateur doit suivre</title> - - <para>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.</para> - - <para>Il y a là un certain nombre d'entités et d'éléments qui entrent - en jeu.</para> - - <variablelist> - <varlistentry> - <term><sgmltag>screen</sgmltag></term> - - <listitem> - <para>Tout ce que l'utilisateur voit dans cet exemple est - affiché sur l'écran de l'ordinateur, l'élément suivant est - donc <sgmltag>screen</sgmltag>.</para> - - <para>A l'intérieur de <sgmltag>screen</sgmltag>, les blancs - sont significatifs.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><sgmltag>prompt</sgmltag>, - <literal>&prompt.root;</literal> et - <literal>&prompt.user;</literal></term> - - <listitem> - <para>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 - <sgmltag>prompt</sgmltag>.</para> - - <para>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 - <literal>&prompt.root;</literal> ou - <literal>&prompt.user;</literal> selon le cas. Il n'y a - pas besoin qu'elles soient à l'intérieur de - <sgmltag>prompt</sgmltag>.</para> - - <note> - <para><literal>&prompt.root;</literal> et - <literal>&prompt.user;</literal> sont des extensions - FreeBSD à DocBook, et ne font pas partie de la DTD - originale.</para> - </note> - </listitem> - </varlistentry> - - <varlistentry> - <term><sgmltag>userinput</sgmltag></term> - - <listitem> - <para>Quant il s'agit de texte que l'utilisateur doit taper, - mettez-le dans un élément <sgmltag>userinput</sgmltag>. Il - sera normalement affiché différement.</para> - </listitem> - </varlistentry> - </variablelist> - - <example> - <title><sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag> et - <sgmltag>userinput</sgmltag></title> - - <para>Utilisez :</para> - - <programlisting><![ CDATA [<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>]]></programlisting> - - <para>Apparence:</para> - - <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> - </example> - - <note> - <para>Bien que nous montrions le contenu du fichier - <filename>foo2</filename>, nous n'utilisons - <emphasis>pas</emphasis> la marque - <sgmltag>programlisting</sgmltag>. Réservez - <sgmltag>programlisting</sgmltag> pour les extraits de fichiers - hors du dialogue homme/machine.</para> - </note> - </sect3> - </sect2> - - <sect2> - <title>Eléments en ligne</title> - - <sect3> - <title>Mettre de l'information en valeur</title> - - <para>Si vous voulez mettre en valeur un mot ou une phrase, - servez-vous de <sgmltag>emphasis</sgmltag>. 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.</para> - - <para>Il n'y a aucun moyen de changer la présentation du texte mis en - valeur dans votre document, pas d'équivalent des - <sgmltag>b</sgmltag> et <sgmltag>i</sgmltag>. Si l'information que - vous donnez est importante, envisagez d'utiliser - <sgmltag>important</sgmltag> plutôt que - <sgmltag>emphasis</sgmltag>.</para> - - <example> - <title><sgmltag>emphasis</sgmltag></title> - - <para>Utilisez :</para> - - <programlisting><![ CDATA [<para>FreeBSD est sans aucun doute - <emphasis>le</emphasis> premier système - d'exploitation de type Unix pour - architecture Intel.</para>]]></programlisting> - - <para>Apparence :</para> - - <para>FreeBSD est sans aucun doute - <emphasis>le</emphasis> premier - système d'exploitation de type Unix pour architecture - Intel.</para> - </example> - </sect3> - - <sect3> - <title>Applications, commandes, options et références</title> - - <para>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.</para> - - <para>Vous aurez aussi de temps à autre à lister une ou plusieurs des - options d'une commande.</para> - - <para>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.</para> - - <para>Désignez les noms d'applications avec - <sgmltag>application</sgmltag>.</para> - - <para>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 <sgmltag>citerefentry</sgmltag>. Il contiendra - deux autres éléments, <sgmltag>refentrytitle</sgmltag> et - <sgmltag>manvolnum</sgmltag>. Le contenu de - <sgmltag>refentrytitle</sgmltag> est le nom de la commande, et celui - de <sgmltag>manvolnum</sgmltag> est son numéro de section dans le - manuel.</para> - - <para>Ce peut être fastidieux à taper, aussi a-t-on défini une séries - d'<link - linkend="sgml-primer-general-entities">entités générales</link> - pour faciliter ces références. Chacune de ces entités est de la - forme - <literal>&man.<replaceable>page-de-manuel</replaceable>.<replaceable>section-du-manuel</replaceable>;</literal>.</para> - - <para>Ces entités sont dans le fichier - <filename>doc/share/sgml/man-refs.ent</filename>, qui peut-être - référencé par le FPI :</para> - - <programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting> - - <para>L'introduction de votre documentation ressemblera donc - probalement à :</para> - - <programlisting><!DOCTYPE book PUBLIC - "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [ - -<!ENTITY % man PUBLIC - "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> -%man; - -… - -]></programlisting> - - <para>Servez-vous de <sgmltag>command</sgmltag> quand vous voulez - mettre le nom d'une commande dans le texte en le présentant comme - quelque chose que l'utilisateur doit taper.</para> - - <para>Utilisez <sgmltag>option</sgmltag> pour désigner les options - d'une commande.</para> - - <para>Ce peut être confus, et le bon choix n'est pas toujours évident. - Espérons que les exemples qui suivent éclaircirons les - choses.</para> - - <example> - <title>Applications, commandes et options.</title> - - <para>Utilisez :</para> - - <programlisting><![ CDATA [<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>]]></programlisting> - - <para>Apparence :</para> - - <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 - <citerefentry><refentrytitle>newaliases</refentrytitle> - <manvolnum>8</manvolnum></citerefentry>.</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> - </example> - - <note> - <para>Remarquez comme il est plus facile d'utiliser la notation - <literal>&man.<replaceable>commande</replaceable>.<replaceable>section</replaceable>;</literal>.</para> - </note> - </sect3> - - <sect3> - <title>Fichiers, répertoires, extensions</title> - - <para>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 - <sgmltag>filename</sgmltag>.</para> - - <example> - <title><sgmltag>filename</sgmltag></title> - - <para>Utilisez :</para> - - <programlisting><![ CDATA [<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.sgml</filename>. Il doit aussi - y avoir un <filename>Makefile</filename> et un - certain nombre de fichiers avec l'extension - <filename>.ent</filename>.</para>]]></programlisting> - - <para>Apparence :</para> - - <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.sgml</filename>. Il doit aussi y avoir un - <filename>Makefile</filename> et un certain nombre de fichiers - avec l'extension <filename>.ent</filename>.</para> - </example> - </sect3> - - <sect3> - <title>Fichiers spéciaux de périphériques</title> - - <note> - <title>extension FreeBSD</title> - - <para>Ces éléments font partie des extensions FreeBSD à DocBook et - n'existent pas dans la DTD DocBook d'origine.</para> - </note> - - <para>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 <filename>/dev</filename>, soit le nom sous lequel il est - désigné dans le noyau. Dans ce dernier cas, servez-vous de - <sgmltag>devicename</sgmltag>.</para> - - <para>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 <filename>/dev</filename>, ou bien celles-ci sont - très différentes des noms utilisés dans le noyau.</para> - - <example> - <title><sgmltag>devicename</sgmltag></title> - - <para>Utilisez :</para> - - <programlisting><![ CDATA [<para><devicename>sio</devicename> sert - sous FreeBSD aux communications séries. - <devicename>sio</devicename> correspond - à 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>]]></programlisting> - - <para>Apparence :</para> - - <para><devicename>sio</devicename> sert sous FreeBSD aux - communications séries. <devicename>sio</devicename> correspond à - 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> - </example> - </sect3> - - <sect3> - <title>Machines, domaines, adresses IP, et ainsi de suite</title> - - <note> - <title>extension FreeBSD</title> - - <para>Ces éléments font partie des extensions FreeBSD à DocBook et - n'existent pas dans la DTD DocBook d'origine.</para> - </note> - - <para>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 <sgmltag>hostid</sgmltag> - comme élément, l'attribut <literal>role</literal> servant à - qualifier le type d'information.</para> - - <variablelist> - <varlistentry> - <term>Pas de valeur de l'attribut, ou - <literal>role="hostname"</literal></term> - - <listitem> - <para>Sans valeur de l'attribut (i.e., - <sgmltag>hostid</sgmltag>...<sgmltag>hostid</sgmltag>), - l'information donnée est le seul nom de la machine, - <literal>freefall</literal> ou <literal>wcarchive</literal>, - par exemple. Vous pouvez l'expliciter avec - <literal>role="hostname"</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="domainname"</literal></term> - - <listitem> - <para>C'est ici un nom de domaine, comme - <literal>FreeBSD.org</literal> ou - <literal>ngo.org.uk</literal>. Il n'y a pas de nom de - machine.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="fqdn"</literal></term> - - <listitem> - <para>C'est le nom complet de la - machine - <foreignphrase>Fully Qualified Domain - Name</foreignphrase>, composé du nom de la machine et du nom - de domaine.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="ipaddr"</literal></term> - - <listitem> - <para>On donne alors l'adresse IP, probablement sous forme de - quatre nombres séparés par des points.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="netmask"</literal></term> - - <listitem> - <para>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 <literal>/</literal> suivi d'un - nombre.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>role="mac"</literal></term> - - <listitem> - <para>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.</para> - </listitem> - </varlistentry> - </variablelist> - - <example> - <title><sgmltag>hostid</sgmltag> et <literal>role</literal>s</title> - - <para>Utilisez :</para> - - <programlisting><![ CDATA [<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 à 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 à <hostid - role="mac">08:00:20:87:ef:d0</hostid>.</para>]]></programlisting> - - <para>Apparence :</para> - - <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 à 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 à <hostid - role="mac">08:00:20:87:ef:d0</hostid>.</para> - </example> - </sect3> - - <sect3> - <title>Noms d'utilisateurs</title> - - <note> - <title>extension FreeBSD</title> - - <para>Ces éléments font partie des extensions FreeBSD à DocBook et - n'existent pas dans la DTD DocBook d'origine.</para> - </note> - - <para>Si vous avez besoin de faire référence à un nom d'utilisateur, - comme <literal>root</literal> ou <literal>bin</literal>, servez-vous - de <sgmltag>username</sgmltag>.</para> - - <example> - <title><sgmltag>username</sgmltag></title> - - <para>Utilisez :</para> - - <programlisting><![ CDATA [<para>Pour effectuer la plupart des - tâches d'administration système, - vous aurez besoin d'être - <username>root</username>.</para>]]></programlisting> - - <para>Apparence :</para> - - <para>Pour effectuer la plupart des tâches d'administration système, - vous aurez besoin d'être <username>root</username>.</para> - </example> - </sect3> - - <sect3> - <title>Décrire les <filename>Makefile</filename>s</title> - - <note> - <title>extension FreeBSD</title> - - <para>Ces éléments font partie des extensions FreeBSD à DocBook et - n'existent pas dans la DTD DocBook d'origine.</para> - </note> - - <para>Il y a des éléments pour décrire les composantes d'un - <filename>Makefile</filename>s, <sgmltag>maketarget</sgmltag> et - <sgmltag>makevar</sgmltag>.</para> - - <para><sgmltag>maketarget</sgmltag> désigne une cible définie dans un - <filename>Makefile</filename> qui peut être utilisée en paramètre de - <command>make</command>. <sgmltag>makevar</sgmltag> désigne une - variable qui peut être définie (dans l'environnement, sur la ligne - de commande de <command>make</command> ou dans le - <filename>Makefile</filename>) et affecte le processus .</para> - - <example> - <title><sgmltag>maketarget</sgmltag> et - <sgmltag>makevar</sgmltag></title> - - <para>Utilisez :</para> - - <programlisting><![ CDATA [<para>Il y a deux cibles courantes dans les - <filename>Makefile</filename> : - <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>]]></programlisting> - - <para>Apparence :</para> - - <para>Il y a deux cibles courantes dans les - <filename>Makefile</filename> : <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> - </example> - </sect3> - - <sect3> - <title>Litéraux</title> - - <para>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.</para> - - <para>Il vous suffira parfois de <sgmltag>programlisting</sgmltag> - pour cela. <sgmltag>programlisting</sgmltag> 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.</para> - - <para>Servez-vous dans ces cas-là de - <sgmltag>literal</sgmltag>.</para> - - <example> - <title><sgmltag>literal</sgmltag></title> - - <para>Utilisez :</para> - - <programlisting><![ CDATA [<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>]]></programlisting> - - <para>Apparence :</para> - - <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> - </example> - </sect3> - - <sect3> - <title>Montrer ce que l'utilisateur <emphasis>doit</emphasis> - renseigner</title> - - <para>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.</para> - - <para><sgmltag>replaceable</sgmltag> est prévu pour ces cas-là. - Servez-vous en <emphasis>à l'intérieur</emphasis> d'autres éléments - pour indiquer quels contenus l'utilisateur doit remplacer.</para> - - <example> - <title><sgmltag>replaceable</sgmltag></title> - - <para>Utilisez :</para> - - <programlisting><![ CDATA [<informalexample> - <screen>&prompt.user; <userinput>man - <replaceable>command</replaceable></userinput></screen> -</informalexample>]]></programlisting> - - <para>Apparence :</para> - - <informalexample> - <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> - </informalexample> - - <para><sgmltag>replaceable</sgmltag> peut servir dans de nombreux - autres éléments, dont <sgmltag>literal</sgmltag>. Cet exemple - montre aussi qu'il ne faut mettre <sgmltag>replaceable</sgmltag> - qu'autour du contenu que l'utilisateur <emphasis>doit</emphasis> - fournir. Il faut laisser le reste tel quel.</para> - - <para>Utilisez :</para> - - <programlisting><![ CDATA [<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>]]></programlisting> - - <para>Apparence :</para> - - <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> - </example> - </sect3> - </sect2> - - <sect2> - <title>Liens</title> - - <note> - <para>Les liens sont aussi des éléments en ligne.</para> - </note> - - <sect3> - <title>Mettre des liens vers d'autres parties du même document</title> - - <para>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.</para> - - <para>Chaque élément DocBook possède un attribut - <literal>id</literal>. Vous pouvez utiliser cet attribut pour donner - un nom unique à l'élément.</para> - - <para>C'est cette valeur que vous utiliserez quand vous préciserez - la destination du lien.</para> - - <para>Habituellement, vous mettrez des liens sur des chapitres ou des - sections, vous ajouterez donc un attribut <literal>id</literal> à - ces éléments.</para> - - <example> - <title><literal>id</literal> de chapitres et de section</title> - - <programlisting><![ CDATA [<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>]]></programlisting> - </example> - - <para>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'<literal>id</literal> de la sous-section est construit en le - préfixant de l'<literal>id</literal> du chapitre. Cela aide à - construire des identifiants uniques.</para> - - <para>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 <sgmltag>anchor</sgmltag>. Cet élément n'a - pas de contenu, mais il a un attribut <literal>id</literal>.</para> - - <example> - <title><sgmltag>anchor</sgmltag></title> - - <programlisting><![ CDATA [<para>Ce paragraphe inclut un - <anchor id="para1">lien interne. Il n'apparaît - pas dans le document.</para>]]></programlisting> - </example> - - <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 <literal>id</literal>, vous pouvez - vous servir de <sgmltag>xref</sgmltag> ou - <sgmltag>link</sgmltag>.</para> - - <para>Ces deux éléments ont un attribut <literal>linkend</literal>. - La valeur de cette attribut doit être celle que vous avez utilisée - comme attribut <literal>id</literal> (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).</para> - - <para>Si vous vous servez de <sgmltag>xref</sgmltag>, vous n'avez pas - le contrôle du texte du lien. Il sera généré automatiquement.</para> - - <example> - <title>Se servir de <sgmltag>xref</sgmltag></title> - - <para>Supposons que ce fragment apparaisse quelque part dans un - document qui contienne l'exemple que nous avons donné pour - <literal>id</literal> :</para> - - <programlisting><![ CDATA [<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>]]></programlisting> - - <para>Le texte du lien sera généré automatiquement, et cela - ressemblera à (le texte mis <emphasis>en valeur</emphasis> indique - que c'est cela le lien) :</para> - - <blockquote> - <para>Vous trouverez plus d'information au <emphasis>Chapitre - Un</emphasis>.</para> - - <para>Vous trouverez des informations plus détaillées dans - <emphasis>la section appellée Sous-section 1</emphasis>.</para> - </blockquote> - </example> - - <para>Remarquez que le texte du lien est construit à partir du titre - de la section ou du numéro du chapitre.</para> - - <note> - <para>Cela veut dire que vous <emphasis>ne pouvez pas</emphasis> - utiliser <sgmltag>xref</sgmltag> pour mettre un lien sur - l'attribut <literal>id</literal> d'un élément - <sgmltag>anchor</sgmltag>. L'<sgmltag>anchor</sgmltag> n'a pas de - contenu et <sgmltag>xref</sgmltag> ne pourrait donc pas générer le - texte du lien.</para> - </note> - - <para>Si vous voulez avoir la maîtrise du texte du lien, servez-vous - alors de <sgmltag>link</sgmltag>. Cet élément encadre un contenu qui - sera utilisé comme lien.</para> - - <example> - <title>Utiliser <sgmltag>link</sgmltag></title> - - <para>Supposons que ce fragment apparaisse quelque part dans un - document qui contienne l'exemple que nous avons donné pour - <literal>id</literal> :</para> - - <programlisting><![ CDATA [<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>]]></programlisting> - - <para>Ce qui générera (le texte mis <emphasis>en valeur</emphasis> - indique que c'est cela le lien) :</para> - - <blockquote> - <para>Vous trouverez plus d'information au <emphasis>premier - chapitre</emphasis>.</para> - - <para>Vous trouverez des informations plus détaillées dans - <emphasis>cette</emphasis> section.</para> - - </blockquote> - </example> - - <note> - <para>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.</para> - </note> - - <note> - <para>Vous <emphasis>pouvez</emphasis> vous servir de - <sgmltag>link</sgmltag> pour mettre un lien sur un - <literal>id</literal> ou une <sgmltag>anchor</sgmltag>, puisque - le contenu du <sgmltag>link</sgmltag> définit le texte qui sera - utilisé comme lien.</para> - </note> - </sect3> - - <sect3> - <title>Liens vers d'autres documents sur le WWW</title> - - <para>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 - <sgmltag>ulink</sgmltag>. L'attribut <literal>url</literal> sera - l'URL de la page où pointera le lien, et le contenu du lien sera - utilisé pour que l'utilisateur puisse l'activer.</para> - - <example> - <title><sgmltag>ulink</sgmltag></title> - - <para>Utilisez :</para> - - <programlisting><![ CDATA [<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>]]></programlisting> - - <para>Apparence :</para> - - <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> - </example> - </sect3> - </sect2> - </sect1> - - <sect1> - <title>* LinuxDoc</title> - - <para>LinuxDoc est adapté de la DTD QWERTZ, et a été d'abord utilisé par - le <ulink url="http://sunsite.unc.edu/LDP/">Projet de Documentation de - Linux</ulink>, puis adopté ensuite par celui de FreeBSD.</para> - - <para>La DTD LinuxDoc utilise des marques qui décrivent avant tout - l'apparence du document et non son contenu (i.e., elle décrit à quoi - quelque chose ressemble, et non ce que c'est).</para> - - <para>Et le Projet de Documentation de FreeBSD et celui de Linux sont en - train de migrer de la DTD LinuxDoc à la DTD DocBook.</para> - - <para>La DTD LinuxDoc DTD est disponible au catalogue des logiciels portés, - dans la catégorie <filename>textproc/linuxdoc</filename>.</para> - </sect1> -</chapter> - - -<!-- - Local Variables: - mode: sgml - sgml-declaration: "../chapter.decl" - sgml-indent-data: t - sgml-omittag: nil - sgml-always-quote-attributes: t - sgml-parent-document: ("../book.sgml" "part" "chapter") - End: ---> - |