7.2. Organisation physique

7.2.1. Makefile

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.

7.2.2. handbook.xml

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.

7.2.3. répertoire/chapter.xml

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.

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).