Le Manuel de Référence (et ses traductions) sont dans le
sous-répertoire
doc/langue/handbook
des archives CVS principales. langue
est le
code ISO pour la langue, en
, pour l'Anglais,
ja
pour le Japonais, et ainsi de suite.
Il y a un certain nombre de fichiers et répertoires dans le
répertoire handbook
.
L'organisation du Manuel de Référence sera peut-être modifiée avec
le temps, et le présent document peut ne pas être en phase avec ces
changements. Si vous avez des questions sur la façon dont le Manuel de
Référence est organisé, contactez s'il vous plaît le Projet de
Documentation de FreeBSD, <doc@FreeBSD.ORG>
.
Le Makefile
décrit les règles utilisées pour
convertir le Manuel de Référence à partir du source (DocBook) dans
plusieurs formats cibles (dont HTML, PostScript, et texte).
Le Makefile
est décrit plus en détail à la
Section 7.4, « * Conversion du Manuel dans d'autres formats ».
C'est la racine du Manuel de Référence. Il contient la déclaration DOCTYPE du Manuel, ainsi que les éléments qui décrivent sa structure.
handbook.xml
utilise des entités paramètres
pour charger les fichiers d'extensions .ent
. Ces
fichiers (décrits plus loin) définissent à leur tour des
entités générales
qui sont elles-mêmes employées dans le reste du Manuel.
Chaque chapitre du manuel est composé d'un fichier
chapter.xml
dans un sous-répertoire séparé pour
chaque chapitre. Chaque répertoire prend le nom de l'attribut
id
de l'élément chapter
.
Si par exemple, un des chapitres contient :
<chapter id="kernelconfiguration"> ... </chapter>
il s'appelera alors chapter.xml
dans le
répertoire kernelconfiguration
. Habituellement,
il y aura un seul fichier pour tout le chapitre.
A la génération de la version HTML du Manuel, on obtiendra un
kernelconfiguration.html
. C'est dû à la valeur
du id
, et non au nom du répertoire.
Dans les versions précédentes du Manuel, ces fichiers étaient dans
le même répertoire que handbook.xml
, avec le
même nom que l'attribut id
de l'élément
chapter
du fichier. Ils ont été déplacés dans des
répertoires séparés en prévision des évolutions à venir du Manuel. Il
sera en particulier bientôt possible d'inclure des images dans chaque
chapitre. Il est donc plus logique que celles-ci soient rangées dans
un répertoire où se trouve aussi le texte du chapitre plutôt que de
mettre le texte de chaque chapitre, et donc toutes les images dans un
même répertoire. Il y aurait fatalement des conflits de nom, alors
qu'il est plus facile de travailler avec plusieurs répertoires
contenant quelques fichiers qu'avec un seul répertoire dans lequel il
y a beaucoup de fichiers.
Un bref coup d'oeil montre qu'il y a de nombreux répertoires avec
chacun un fichier chapter.xml
dont
basics/chapter.xml
,
introduction/chapter.xml
et
printing/chapter.xml
.
Les noms des chapitres et/ou répertoires ne doivent pas faire réference à leur place dans le Manuel. Cet ordre peut changer quand le contenu du Manuel est réorganisé ; ce type de réorganisation ne devrait (normalement) pas entraîner de modification des noms des fichiers (à moins que des chapitres entiers ne changent de niveau dans la hiérarchie).
Chaque fichier chapter.xml
n'est pas un
document SGML intégral. Ils n'ont en particulier pas de déclaration
DOCTYPE en tête du fichier.
C'est dommage pour deux raisons :
Il n'est pas possible de les traiter comme des fichiers SGML et de les convertir en HTML, RTF, PS et autres formats de la même manière que le Manuel. Cela vous oblige à recompiler tout le Manuel chaque fois que vous voulez vérifier les effets d'une modification d'un seul chapitre.
Le sgml-mode
d'Emacs ne peut pas s'en
servir pour déterminer quelle DTD utiliser, ce qui fait perdre les
bénéfices de fonctionnalités utiles du
sgml-mode
(complétion des éléments, validation
automatique, et ainsi de suite).
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>.