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
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
|
<!-- 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.
$FreeBSD$
-->
<chapter id="structure">
<title>Structuring Documents Under <filename>doc/</filename></title>
<para>The <filename>doc/</filename> tree is organized in a particular
fashion, and the documents that are part of the FDP are in turn organized
in a particular fashion. The aim is to make it simple to add new
documentation into the tree and:</para>
<orderedlist>
<listitem>
<para>Make it easy to automate converting the document to other formats.</para>
</listitem>
<listitem>
<para>Promote consistency between the different documentation
organizations, to make it easier to switch between working on
different documents.</para>
</listitem>
<listitem>
<para>Make it easy to decide where in the tree new documentation should
be placed.</para>
</listitem>
</orderedlist>
<para>In addition, the documentation tree has to accommodate documentation
that could be in many different languages and in many different
encodings. It is important that the structure of the documentation tree
does not enforce any particular defaults or cultural preferences.</para>
<sect1 id="structure-top">
<title>The Top Level, <filename>doc/</filename></title>
<para>There are two types of directory under <filename>doc/</filename>,
each with very specific directory names and meanings.</para>
<segmentedlist>
<segtitle>Directory</segtitle>
<segtitle>Meaning</segtitle>
<seglistitem>
<seg><filename>share/</filename></seg>
<seg>Contains files that are not specific to the various translations
and encodings of the documentation. Contains subdirectories to
further categorize the information. For example, the files that
comprise the &man.make.1; infrastructure are in
<filename>share/mk</filename>, while the additional SGML support
files (such as the FreeBSD extended DocBook DTD) are in
<filename>share/sgml</filename>.</seg>
</seglistitem>
<seglistitem>
<seg><filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename></seg>
<seg>One directory exists for each available translation and encoding
of the documentation, for example
<filename>en_US.ISO8859-1/</filename> and
<filename>zh_TW.Big5/</filename>. The names are long, but by fully
specifying the language and encoding we prevent any future headaches
should a translation team want to provide the documentation in the
same language but in more than one encoding. This also completely
isolates us from any problems that might be caused by a switch to
Unicode.</seg>
</seglistitem>
</segmentedlist>
</sect1>
<sect1 id="structure-locale">
<title>The
<filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename> Directories</title>
<para>These directories contain the documents themselves. The
documentation is split into up to three more categories at this
level, indicated by the different directory names.</para>
<segmentedlist>
<segtitle>Directory</segtitle>
<segtitle>Contents</segtitle>
<seglistitem>
<seg><filename>articles</filename></seg>
<seg>Documentation marked up as a DocBook <sgmltag>article</sgmltag>
(or equivalent). Reasonably short, and broken up into sections.
Normally only available as one HTML file.</seg>
</seglistitem>
<seglistitem>
<seg><filename>books</filename></seg>
<seg>Documentation marked up as a DocBook <sgmltag>book</sgmltag> (or
equivalent). Book length, and broken up into chapters. Normally
available as both one large HTML file (for people with fast
connections, or who want to print it easily from a browser) and
as a collection of linked, smaller files.</seg>
</seglistitem>
<seglistitem>
<seg><filename>man</filename></seg>
<seg>For translations of the system manual pages. This directory will
contain one or more
<filename>man<replaceable>n</replaceable></filename> directories,
corresponding to the sections that have been translated.</seg>
</seglistitem>
</segmentedlist>
<para>Not every
<filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> directory will contain all of these directories. It depends
on how much translation has been accomplished by that translation
team.</para>
</sect1>
<sect1 id="structure-document">
<title>Document Specific Information</title>
<para>This section contains specific notes about particular documents
managed by the FDP.</para>
<sect2>
<title>The Handbook</title>
<subtitle><filename>books/handbook/</filename></subtitle>
<para>The Handbook is written to comply with the FreeBSD DocBook
extended DTD.</para>
<para>The Handbook is organized as a DocBook <sgmltag>book</sgmltag>.
It is then divided into <sgmltag>part</sgmltag>s, each of which may
contain several <sgmltag>chapter</sgmltag>s.
<sgmltag>chapter</sgmltag>s are further subdivided into sections
(<sgmltag>sect1</sgmltag>) and subsections (<sgmltag>sect2</sgmltag>,
<sgmltag>sect3</sgmltag>) and so on.</para>
<sect3>
<title>Physical Organization</title>
<para>There are a number of files and directories within the
<filename>handbook</filename> directory.</para>
<note>
<para>The Handbook's organization may change over time, and this
document may lag in detailing the organizational changes. If you
have any questions about how the Handbook is organized, please
contact the &a.doc;.</para>
</note>
<sect4>
<title><filename>Makefile</filename></title>
<para>The <filename>Makefile</filename> defines some variables that
affect how the SGML source is converted to other formats, and
lists the various source files that make up the Handbook. It then
includes the standard <filename>doc.project.mk</filename> file, to
bring in the rest of the code that handles converting documents
from one format to another.</para>
</sect4>
<sect4>
<title><filename>book.sgml</filename></title>
<para>This is the top level document in the Handbook. It contains
the Handbook's <link
linkend="sgml-primer-doctype-declaration">DOCTYPE
declaration</link>, as well as the elements that describe the
Handbook's structure.</para>
<para><filename>book.sgml</filename> uses <link
linkend="sgml-primer-parameter-entities">parameter
entities</link> to load in the files with the
<filename>.ent</filename> extension. These files (described later)
then define <link linkend="sgml-primer-general-entities">general
entities</link> that are used throughout the rest of the
Handbook.</para>
</sect4>
<sect4>
<title><filename><replaceable>directory</replaceable>/chapter.sgml</filename></title>
<para>Each chapter in the Handbook is stored in a file called
<filename>chapter.sgml</filename> in a separate directory from the
other chapters. Each directory is named after the value of the
<literal>id</literal> attribute on the <sgmltag>chapter</sgmltag>
element.</para>
<para>For example, if one of the chapter files contains:</para>
<programlisting><![ CDATA [
<chapter id="kernelconfig">
...
</chapter>]]></programlisting>
<para>Then it will be called <filename>chapter.sgml</filename> in
the <filename>kernelconfig</filename> directory. In
general, the entire contents of the chapter will be held in this
file.</para>
<para>When the HTML version of the Handbook is produced, this will
yield <filename>kernelconfig.html</filename>. This is
because of the <literal>id</literal> value, and is not related to
the name of the directory.</para>
<para>In earlier versions of the Handbook the files were stored in
the same directory as <filename>book.sgml</filename>, and named
after the value of the <literal>id</literal> attribute on the
file's <sgmltag>chapter</sgmltag> element.
Now, it is possible to include images in each
chapter. Images for each Handbook chapter are stored within
<filename class="directory">share/images/books/handbook</filename>.
Note that localized version of these images should be placed in the same
directory as the SGML sources for each chapter.
Namespace collisions would be inevitable, and it is
easier to work with several directories with a few files in them
than it is to work with one directory that has many files in
it.</para>
<para>A brief look will show that there are many directories with
individual <filename>chapter.sgml</filename> files, including
<filename>basics/chapter.sgml</filename>,
<filename>introduction/chapter.sgml</filename>, and
<filename>printing/chapter.sgml</filename>.</para>
<important>
<para>Chapters and/or directories should not be named in a fashion
that reflects their ordering within the Handbook. This ordering
might change as the content within the Handbook is reorganized;
this sort of reorganization should not (generally) include the
need to rename files (unless entire chapters are being promoted
or demoted within the hierarchy).</para>
</important>
<para>Each <filename>chapter.sgml</filename> file will not be a
complete SGML document. In particular, they will not have their
own DOCTYPE lines at the start of the files.</para>
<para>This is unfortunate as
it makes it impossible to treat these as generic SGML
files and simply convert them to HTML, RTF, PS, and other
formats in the same way the main Handbook is generated. This
<emphasis>would</emphasis> force you to rebuild the Handbook
every time you want to see the effect a change has had on just
one chapter.</para>
</sect4>
</sect3>
</sect2>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../book.sgml" "part" "chapter")
End:
-->
|