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.
Ces langages sont riches en éléments et il est parfois difficile de savoir lequel 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.
Ce n'est pas 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,
<freebsd-doc@freebsd.org>
.
Dans la suite de ce document, quand on décrira des éléments, en ligne 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.
HTML, l'HyperText Markup Language - Langage de Marquage de l'Hypertexte - est le langage de prédilection du World Wide Web. Vous trouverez plus d'informations sur <URL:http://www.w3.org/>.
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.
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 stricte et relâchée).
Les DTDs HTML existent au catalogue des logiciels portés dans
textproc/html
. Elles sont automatiquement
installées par le méta-port
textproc/docproj
.
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.
La plupart des documents HTML du site Web de FreeBSD respectent strictement la version relâchée de HTML 4.0 :
Un document HTML est habituellement composé de deux sections. La première section, appelée head - 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 body - corps, contient ce qui sera affiché.
Ces sections sont dénotées par les éléments
head
et body
respectivement. Ces
éléments appartiennent à l'élément de premier niveau
html
.
Le titre du document
</title>
</head>
<body>
…
</body>
</html>HTML vous permet d'avoir jusqu'à six niveaux de titres différents dans votre document.
Le titre le plus gros et le plus visible est
h1
, puis h2
, jusqu'à
h6
.
Le contenu de l'élément est le texte du titre.
h1
, h2
, etc.Utilisez :
Une page HTML doit normalement avoir un titre de premier niveau
(h1
). Il peut contenir plusieurs titres de second
niveau (h2
), et à leur tour, de nombreux titres
de troisième niveau. Chaque élément
h
doit appartenir à
un même élément de niveau supérieur. Il faut éviter de sauter d'un
cran dans la numérotation.n
hn
Use:
HTML n'a qu'un seul élément paragraphe,
p
.
p
Utilisez :
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.
blockquote
Utilisez :
Il y a trois types de listes que vous pouvez afficher : ordonnée, non ordonnée et de définition.
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.
Les listes ordonnées sont dénotées par l'élément
ol
, les listes non ordonnées par l'élément
ul
et les listes de définition par l'élément
dl
element.
Les listes ordonnées et non ordonnées contiennent des éléments
de liste, notés avec l'élément li
. Un élément de
liste peut contenir du texte, ou être décomposé en plusieurs
éléments p
.
Les listes de définition contiennent des termes à définir
(dt
) et leurs définitions
(dd
). Le terme à définir n'est composé que de
texte. La définition peut comporter d'autres éléments de
blocs.
ul
et ol
Utilisez :
dl
Utilisez :
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.
Pour cela, il faut mettre ce texte dans un élément
pre
.
pre
Vous pouvez utiliser pre
pour marquer le
texte d'un courrier électronique :
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.
Marquez les tableaux avec l'élément table
.
Un tableau est composé d'une ou plusieurs lignes
(tr
), chacune contenant une ou plusieurs
cellules (td
). 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 p
n'est pas
obligatoire.
table
Utilisez :
Une cellule peut occuper plusieurs lignes ou colonnes. Pour le
préciser, ajoutez les attributs rowspan
et/ou
colspan
, dont les valeurs donnent le nombre de
lignes et de colonnes occupées.
rowspan
Utilisez :
colspan
Utilisez :
rowspan
et
colspan
ensembleUse:
Il y a deux niveaux d'accentuation disponibles en HTML,
em
et strong
.
em
marque une accentuation normale et
strong
une accentuation plus prononcée.
em
est généralement rendu en italiques et
strong
en gras. Ce n'est malgré tout pas toujours
le cas, et il ne faut pas se baser là-dessus.
em
et strong
Utilisez :
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
b
et i
.
S'il y a du texte qui doit être affiché en police fixe (machine
à écrire), servez-vous de tt
( pour
“télétype”).
tt
Utilisez :
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.
Utilisez big
et small
pour encadrer le texte dont vous voulez modifier la taille. Ces
marques peuvent être imbriquées, il est donc possible
d'avoir : <big><big>C'est bien plus
gros</big></big>
.
Servez-vous de font
avec l'attribut
size
prenant respectivement les valeurs
+1
ou -1
. C'est la même
chose que d'utiliser big
ou
small
. Mais cette façon de faire est
obsolète.
Utilisez font
avec l'attribut
size
prenant une valeur de 1 à 7. La taille
de police par défaut est 3
. Cette façon de
faire est aussi obsolète.
big
, small
et
font
Les trois extraits suivants ont le même résultat :
Les liens font aussi partie du contenu du document.
Pour mettre un lien sur un autre document sur le WWW, il faut que vous connaissiez l'URL de ce document.
Ce lien est noté avec a
et l'attribut
href
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).
<a href="...">
Utilisez :
Ces liens amèneront l'utilisateur au début du document sélectionné.
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 lesquels vous pouvez pointer.
Les points d'ancrage sont notés avec a
et
l'attribut name
au lieu de
href
.
<a name="...">
Utilisez :
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 #
.
Supposons que l'exemple para1
se trouve
dans un document appelé foo.html
.
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 #
).
Supposons que l'exemple para1
fasse partie
de ce document.
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>.