Le Manuel de Référence est rédigé en conformité avec la DTD DocBook étendue de FreeBSD. Le Manuel de Référence est un book DocBook. Il est ensuite divisé en parts, qui contiennent elles-mêmes plusieurs chapters. Les chapters sont eux-mêmes composés de sections (sect1) et sous-sections (sect2, sect3) et ainsi de suite. 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 . 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.sgml 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.sgml 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 : ... ]]> il s'appelera alors chapter.sgml 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.sgml, 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.sgml dont basics/chapter.sgml, introduction/chapter.sgml et printing/chapter.sgml. 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.sgml 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). Respectez s'il vous plaît les conventions de style ci-dessous pour garder aux sources du Manuel une consistance malgré les nombreuses personnes qui interviennent dessus. Les marques doivent être en minuscules <para> et non <PARA>. Le texte dans les contextes SGML est normalement en majuscules, <!ENTITY…> ou <!DOCTYPE…> et non <!entity…> ou <!doctype…>. Chaque fichier est indenté à partir de la colonne 0, quel que soit le niveau d'indentation dans le fichier où il est inclus. Chaque marque de début augmente l'indentation de 2 blancs et chaque marque de fin la décrémente d'autant. Le contenu des éléments doit être indenté de 2 blancs s'il court sur plusieurs lignes. A titre d'exemple, voici à quoi ressemble le source de cette section : Chaque fichier est indenté à partir de la colonne 0, quel que soit le niveau d'indentation dans le fichier où il est inclus. Chaque marque de début augmente l'indentation de 2 blancs et chaque marque de fin la décrémente d'autant. Le contenu des éléments doit être indenté de 2 blancs s'il court sur plusieurs lignes. ... ]]> Si vous vous servez d'Emacs ou Xemacs pour éditer les fichiers, le sgml-mode doit être chargé automatiquement, et les variables Emacs locales en fin de chaque fichier doivent mettre ces indentations en pratique. Quand vous intégrez des modifications, ne faites pas en même temps de modification de contenu et de présentation des sources. Cela pour que les équipes de traductions du Manuel puissent rapidement voir les modifications de contenu que vous avez intégrées, sans avoir à se demander si une ligne a changé de contenu ou simplement de présentation. Si vous avez par exemple ajouté deux phrases à un paragraphe, de sorte que les lignes du paragraphe débordent maintenant des 80 colonnes, intégrez d'abord la modification avec les lignes trop longues. Puis corrigez ensuite ce problème, en précisant qu'il ne s'agit que d'une modification de présentation, dont les équipes de traduction n'ont pas à se soucier.