1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
|
<?xml version="1.0" encoding="ISO8859-1" standalone="no"?>
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$Id: chapter.sgml,v 1.1 2000-06-12 15:46:54 gioria Exp $
-->
<chapter id="the-handbook">
<title>* Le Manuel de Référence</title>
<sect1>
<title>Organisation logique</title>
<para>Le Manuel de Référence est rédigé en conformité avec la DTD DocBook
étendue de FreeBSD.</para>
<para>Le Manuel de Référence est un <sgmltag>book</sgmltag> DocBook. Il
est ensuite divisé en <sgmltag>part</sgmltag>s, qui contiennent
elles-mêmes plusieurs <sgmltag>chapter</sgmltag>s. Les
<sgmltag>chapter</sgmltag>s sont eux-mêmes composés de sections
(<sgmltag>sect1</sgmltag>) et sous-sections
(<sgmltag>sect2</sgmltag>, <sgmltag>sect3</sgmltag>) et ainsi de
suite.</para>
</sect1>
<sect1>
<title>Organisation physique</title>
<para>Le Manuel de Référence (et ses traductions) sont dans le
sous-répertoire
<filename>doc/<replaceable>langue</replaceable>/handbook</filename>
des archives CVS principales. <replaceable>langue</replaceable> est le
code ISO pour la langue, <literal>en</literal>, pour l'Anglais,
<literal>ja</literal> pour le Japonais, et ainsi de suite.</para>
<para>Il y a un certain nombre de fichiers et répertoires dans le
répertoire <filename>handbook</filename>.</para>
<note>
<para>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, <email>doc@FreeBSD.ORG</email>.</para>
</note>
<sect2>
<title><filename>Makefile</filename></title>
<para>Le <filename>Makefile</filename> 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).</para>
<para>Le <filename>Makefile</filename> est décrit plus en détail à la
<xref linkend="the-handbook-converting"/>.</para>
</sect2>
<sect2>
<title><filename>handbook.sgml</filename></title>
<para>C'est la racine du Manuel de Référence. Il contient la
<link linkend="sgml-primer-doctype-declaration">déclaration
DOCTYPE</link> du Manuel, ainsi que les éléments qui décrivent sa
structure.</para>
<para><filename>handbook.sgml</filename> utilise des <link
linkend="sgml-primer-parameter-entities">entités paramètres</link>
pour charger les fichiers d'extensions <filename>.ent</filename>. Ces
fichiers (décrits plus loin) définissent à leur tour des
<link linkend="sgml-primer-general-entities">entités générales</link>
qui sont elles-mêmes employées dans le reste du Manuel.</para>
</sect2>
<sect2>
<title><filename><replaceable>répertoire</replaceable>/chapter.sgml</filename></title>
<para>Chaque chapitre du manuel est composé d'un fichier
<filename>chapter.sgml</filename> dans un sous-répertoire séparé pour
chaque chapitre. Chaque répertoire prend le nom de l'attribut
<literal>id</literal> de l'élément <sgmltag>chapter</sgmltag>.</para>
<para>Si par exemple, un des chapitres contient :</para>
<programlisting><![ CDATA [
<chapter id="kernelconfiguration">
...
</chapter>]]></programlisting>
<para>il s'appelera alors <filename>chapter.sgml</filename> dans le
répertoire <filename>kernelconfiguration</filename>. Habituellement,
il y aura un seul fichier pour tout le chapitre.</para>
<para>A la génération de la version HTML du Manuel, on obtiendra un
<filename>kernelconfiguration.html</filename>. C'est dû à la valeur
du <literal>id</literal>, et non au nom du répertoire.</para>
<para>Dans les versions précédentes du Manuel, ces fichiers étaient dans
le même répertoire que <filename>handbook.sgml</filename>, avec le
même nom que l'attribut <literal>id</literal> de l'élément
<sgmltag>chapter</sgmltag> 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.</para>
<para>Un bref coup d'oeil montre qu'il y a de nombreux répertoires avec
chacun un fichier <filename>chapter.sgml</filename> dont
<filename>basics/chapter.sgml</filename>,
<filename>introduction/chapter.sgml</filename> et
<filename>printing/chapter.sgml</filename>.</para>
<important>
<para>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).</para>
</important>
<para>Chaque fichier <filename>chapter.sgml</filename> n'est pas un
document SGML intégral. Ils n'ont en particulier pas de déclaration
DOCTYPE en tête du fichier.</para>
<para>C'est dommage pour deux raisons :</para>
<itemizedlist>
<listitem>
<para>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 <emphasis>oblige</emphasis> à
recompiler tout le Manuel chaque fois que vous voulez vérifier les
effets d'une modification d'un seul chapitre.</para>
</listitem>
<listitem>
<para>Le <literal>sgml-mode</literal> 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
<literal>sgml-mode</literal> (complétion des éléments, validation
automatique, et ainsi de suite).</para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1>
<title>Guide de style</title>
<para>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.</para>
<sect2>
<title>Majuscules et minuscules</title>
<para>Les marques doivent être en minuscules
<literal><para></literal> et <emphasis>non</emphasis>
<literal><PARA></literal>.</para>
<para>Le texte dans les contextes SGML est normalement en majuscules,
<literal><!ENTITY…></literal> ou
<literal><!DOCTYPE…></literal> et
<emphasis>non</emphasis> <literal><!entity…></literal>
ou <literal><!doctype…></literal>.</para>
</sect2>
<sect2>
<title>Indentation</title>
<para>Chaque fichier est indenté à partir de la colonne 0,
<emphasis>quel que soit</emphasis> le niveau d'indentation dans le
fichier où il est inclus.</para>
<para>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.</para>
<para>A titre d'exemple, voici à quoi ressemble le source de cette
section :</para>
<programlisting>
<![ CDATA [+--- C'est la colonne 0
<chapter>
<title>...</title>
<sect1>
<title>...</title>
<sect2>
<title>Indentation</title>
<para>Chaque fichier est indenté à partir de la colonne 0,
<emphasis>quel que soit</emphasis> le niveau d'indentation dans le
fichier où il est inclus.</para>
<para>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.</para>
...
</sect2>
</sect1>
</chapter>]]></programlisting>
<para>Si vous vous servez d'<application>Emacs</application> ou
<application>Xemacs</application> pour éditer les fichiers, le
<literal>sgml-mode</literal> doit être chargé automatiquement, et les
variables Emacs locales en fin de chaque fichier doivent mettre ces
indentations en pratique.</para>
</sect2>
<sect2>
<title>Modifications de présentation des sources</title>
<para>Quand vous intégrez des modifications, <emphasis>ne faites pas en
même temps de modification de contenu et de présentation des
sources</emphasis>.</para>
<para>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.</para>
<para>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.</para>
</sect2>
</sect1>
<sect1 id="the-handbook-converting">
<title>* Conversion du Manuel dans d'autres formats</title>
<para></para>
</sect1>
</chapter>
|