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.
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.
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
<nik@FreeBSD.org>
.
Les extensions FreeBSD ne font pas (actuellement) partie du
catalogue des logiciels portés. Elles sont inclues dans les sources du
Projet de Documentation et se trouvent dans
doc/share/xml/freebsd.dtd
.
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 :
DocBook vous permet de structurer votre documentation de différentes façons. Le Projet de Documentation de FreeBSD utilise deux types de documents de base, le livre et l'article.
Un livre est organisé en chapter
s. C'est une
obligation. Il peut y avoir des part
s entre le
livre et le chapitre si l'on veut un niveau supplémentaire dans le
découpage.
Un chapitre peut avoir (ou non) une ou plusieurs sections. Elles
sont désignées par l'élément sect1
. Si une section
inclue une autre section, utilisez l'élément sect2
,
et ainsi de suite, jusqu'à sect5
.
Le contenu du livre est lui-même dans les chapitres et sections.
Un article est plus simple qu'un livre, et n'a pas de chapitres.
Au lieu de cela, le contenu d'un article est organisé en une ou
plusieurs sections, à l'aide des mêmes éléments
sect1
(sect2
et ainsi de suite)
dont on se sert pour les livres.
Il vous faudra manifestement choisir le type de document à utiliser selon la nature du document que vous rédigez. Les articles sont bien adaptés pour des documents qui n'ont pas besoin d'être décomposés en chapitres, et qui sont, relativement parlant, assez court - jusqu'à 20-25 pages. Les livres eux conviennent aux documents qui peuvent être découpés en plusieurs chapitres, avec éventuellement des annexes, et autres composants.
Les guides FreeBSD sont tous des articles, tandis que ce document, la FAQ FreeBSD, et le Manuel de Référence FreeBSD sont des livres.
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
.
book
avec
bookinfo
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>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
.
article
avec
artheader
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>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.
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.
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
sect
. Le
n
n
est le type de section, qui indique son
niveau de profondeur.
La première sect
est n
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
.
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.
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
.
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.
para
Utilisez :
Apparence :
C'est un paragraphe. Il peut contenir presque n'importe quel autre élément.
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).
blockquote
Utilisez :
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 |
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.
warning
Utilisez :
Installer FreeBSD peut vous donner envie de supprimer Windows de votre disque dur.
Vous aurez souvent besoin de lister des informations ou d'indiquer à l'utilisateur les différentes étapes nécessaires pour effectuer une tâche donnée.
Pour cela, servez-vous de itemizedlist
,
orderedlist
ou
procedure
[3]
itemizedlist
et
orderedlist
sont semblables à leurs contreparties
ul
et ol
en HTML. Chacune
comporte un ou plusieurs éléments listitem
, et
chaque listitem
contient un ou plusieurs éléments
de blocs. Les élements listitem
sont analogues
aux marques li
du HTML. Néanmoins, au contraire
du HTML, ils sont ici obligatoires.
Une procedure
est légérement différente. Elle
consiste en step
s, qui à leur tour sont composés
de step
s ou substep
s. Chaque
step
contient des éléments de blocs.
itemizedlist
,
orderedlist
et
procedure
Utilisez :
Apparence :
C'est le premier élément de la liste.
C'est le second élément de la liste.
C'est le premier élément de la liste ordonnée.
C'est le second élément de la liste ordonnée.
Faites ceci.
Puis cela.
Et maintenant cela.
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.
programlisting
Utilisez :
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 :
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”.
Au contraire d'HTML, vous n'avez pas besoin d'utiliser les tables pour des questions de présentation, puisque les feuilles de style s'en chargent. Les tables servent uniquement pour les données en tableaux.
Brièvement (voyez la documentation de DocBook pour plus de
détails), une table (qui peut-être formelle ou informelle) est
constituée d'un élément table
. Il contient au
moins un élément tgroup
, dont l'attribut donne
le nombre de colonnes dans ce sous-tableau. Dans le sous-tableau,
vous pouvez ensuite avoir un élément thead
, qui
contient les éléments correspondant aux en-têtes des colonnes, et
un tbody
qui contient le corps du
tableau.
Les thead
et tbody
contiennent des éléments row
- lignes,
qui contiennent à leur tour des éléments entry
.
Chaque élément entry
correspond à une cellule du
tableau.
informaltable
Utilisez :
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">
).
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 |
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
.
&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.
screen
, prompt
et
userinput
Utilisez :
Apparence:
%
ls -1
foo1
foo2
foo3
%
ls -1 | grep foo2
foo2
%
su
Password:
#
cat foo2
C'est le fichier 'foo2'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.
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
.
emphasis
Utilisez :
Apparence :
FreeBSD est sans aucun doute le premier système d'exploitation de type Unix pour architecture Intel.
Il vous arrivera souvent de désigner des applications ou des commandes quand vous rédigerez quelque chose pour le Manuel de Référence. Distinguer les unes des autres est simple : une application est un ensemble de (ou éventuellement un seul) programmes dédiés à une tâche particulière. Une commande est le nom d'un programme que l'utilisateur peut exécuter.
Vous aurez aussi de temps à autre à lister une ou plusieurs des options d'une commande.
Pour finir, il arrivera souvent que vous vouliez indiquer en même temps que la commande, son numéro de section dans les pages de manuel, au format “commande(numéro)” habituel dans les documentations Unix.
Désignez les noms d'applications avec
application
.
Si vous voulez lister une commande avec son numéro de section
dans le manuel (ce qui sera la plupart du temps le cas), l'élément
DocBook pour cela est citerefentry
. Il contiendra
deux autres éléments, refentrytitle
et
manvolnum
. Le contenu de
refentrytitle
est le nom de la commande, et celui
de manvolnum
est son numéro de section dans le
manuel.
Ce peut être fastidieux à taper, aussi a-t-on défini une séries
d'entités générales
pour faciliter ces références. Chacune de ces entités est de la
forme
&man.
.page-de-manuel
.section-du-manuel
;
Ces entités sont dans le fichier
doc/share/xml/man-refs.ent
, qui peut-être
référencé par le FPI :
L'introduction de votre documentation ressemblera donc probalement à :
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.
Utilisez :
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
.
Remarquez comme il est plus facile d'utiliser la notation
&man.
.commande
.section
;
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
.
filename
Utilisez :
Apparence :
Vous trouverez le source SGML du Manuel de Référence en
Anglais dans /usr/doc/en/handbook/
. Le
fichier principal, dans ce répertoire, s'appelle
handbook.xml
. Il doit aussi y avoir un
Makefile
et un certain nombre de fichiers
avec l'extension .ent
.
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.
devicename
Utilisez :
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
.
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.
role="hostname"
Sans valeur de l'attribut (i.e.,
hostid
...hostid
),
l'information donnée est le seul nom de la machine,
freefall
ou wcarchive
,
par exemple. Vous pouvez l'expliciter avec
role="hostname"
.
role="domainname"
C'est ici un nom de domaine, comme
FreeBSD.org
ou
ngo.org.uk
. Il n'y a pas de nom de
machine.
role="fqdn"
C'est le nom complet de la machine - Fully Qualified Domain Name, composé du nom de la machine et du nom de domaine.
role="ipaddr"
On donne alors l'adresse IP, probablement sous forme de quatre nombres séparés par des points.
role="netmask"
C'est un masque de sous-réseau, qui peut être donné comme
quatre nombres séparés par des points, un chaîne en
hexadécimal ou un /
suivi d'un
nombre.
role="mac"
C'est une adresse Ethernet MAC, exprimée par un séries de valeurs hexadécimales sur deux positions séparées par des deux-points.
hostid
et role
sUtilisez :
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
.
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
.
username
Utilisez :
Apparence :
Pour effectuer la plupart des tâches d'administration système,
vous aurez besoin d'être root
.
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
Makefile
s, 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 .
maketarget
et
makevar
Utilisez :
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
.
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
.
literal
Utilisez :
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.
Il arrivera souvent que vous vouliez montrer à l'utilisateur ce qu'il doit faire, faire référence à un fichier, à une ligne de commande, ou autre, dans lesquels l'utilisateur ne pourra pas purement et simplement copier les examples que vous lui donnez, mais devra y renseigner lui-même certaines informations.
replaceable
est prévu pour ces cas-là.
Servez-vous en à l'intérieur d'autres éléments
pour indiquer quels contenus l'utilisateur doit remplacer.
replaceable
Utilisez :
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 :
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.
Les liens sont aussi des éléments en ligne.
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.
id
de chapitres et de sectionVous 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
.
anchor
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.
xref
Supposons que ce fragment apparaisse quelque part dans un
document qui contienne l'exemple que nous avons donné pour
id
:
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.
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.
link
Supposons que ce fragment apparaisse quelque part dans un
document qui contienne l'exemple que nous avons donné pour
id
:
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.
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.
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.
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.
ulink
Utilisez :
Apparence :
Vous pouvez bien sûr cessez de lire ce document, et aller au lieu de cela sur la page Web de FreeBSD.
Ce document, ainsi que d'autres peut être téléchargé sur ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/
Pour toutes questions à propos de FreeBSD, lisez la
documentation avant de contacter
<questions@FreeBSD.org>.
Pour les questions sur cette documentation, contactez
<doc@FreeBSD.org>.