aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml
blob: 9d0635be5ddedcac078c57f0225bf1fff8d72a32 (plain) (blame)
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
295
296
297
298
299
300
301
302
303
304
305
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- 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 xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="structure">
  <title>Documentation Directory Structure</title>

  <para>Files and directories in the
    <filename>doc/</filename> tree follow a
    structure meant to:</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 must accommodate
    documents in many different languages and encodings.  It is
    important that the documentation tree structure does not enforce
    any particular defaults or cultural preferences.</para>

  <sect1 xml: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>

    <informaltable pgwide="1" frame="none">
      <tgroup cols="2">
	<thead>
	  <row>
	    <entry>Directory</entry>
	    <entry>Usage</entry>
	  </row>
	</thead>

	<tbody>
	  <row>
	    <entry valign="top">
	      <filename>share</filename></entry>

	    <entry>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 <acronym>XML</acronym> support files
	      (such as the &os; extended DocBook
	      <acronym>DTD</acronym>) are in <filename>share/xml</filename>.</entry>
	  </row>

	  <row>
	    <entry valign="top"><filename
		class="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename></entry>

	    <entry>One directory exists for each available translation
	      and encoding of the documentation, for example
	      <filename>en_US.ISO8859-1/</filename>
	      and <filename>zh_TW.UTF-8/</filename>.
	      The names are long, but by fully specifying the language
	      and encoding we prevent any future headaches when a
	      translation team wants to provide documentation in the
	      same language but in more than one encoding.  This also
	      avoids problems that might be caused by a future switch
	      to Unicode.</entry>
	  </row>
	</tbody>
      </tgroup>
    </informaltable>
  </sect1>

  <sect1 xml: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>

    <informaltable pgwide="1" frame="none">
      <tgroup cols="2">
	<thead>
	  <row>
	    <entry>Directory</entry>
	    <entry>Usage</entry>
	  </row>
	</thead>

	<tbody>
	  <row>
	    <entry valign="top">
	      <filename>articles</filename></entry>

	    <entry>Documentation marked up as a DocBook
	      <tag>article</tag> (or equivalent).  Reasonably
	      short, and broken up into sections.  Normally only
	      available as one <acronym>XHTML</acronym> file.</entry>
	  </row>

	  <row>
	    <entry valign="top"><filename>books</filename></entry>

	    <entry>Documentation marked up as a DocBook
	      <tag>book</tag> (or equivalent).  Book length,
	      and broken up into chapters.  Normally available as both
	      one large <acronym>XHTML</acronym> file (for people with
	      fast connections, or who want to print it easily from a
	      browser) and as a collection of linked, smaller
	      files.</entry>
	  </row>

	  <row>
	    <entry valign="top">
	      <filename>man</filename></entry>

	    <entry>For translations of the system manual pages.  This
	      directory will contain one or more <filename role="directory">man<replaceable>n</replaceable></filename>
	      directories, corresponding to the sections that have
	      been translated.</entry>
	  </row>
	</tbody>
      </tgroup>
    </informaltable>

    <para>Not every <filename role="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename>
      directory will have all of these subdirectories.  It depends
      on how much translation has been accomplished by that
      translation team.</para>
  </sect1>

  <sect1 xml: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 in DocBook <acronym>XML</acronym>
	using the &os; DocBook extended <acronym>DTD</acronym>.</para>

      <para>The Handbook is organized as a DocBook
	<tag>book</tag>.  The book is divided into
	<tag>part</tag>s, each of which contains several
	<tag>chapter</tag>s.  <tag>chapter</tag>s are
	further subdivided into sections (<tag>sect1</tag>)
	and subsections (<tag>sect2</tag>,
	<tag>sect3</tag>) 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.  Post questions about Handbook organization to
	    &a.doc;.</para>
	</note>

	<sect4>
	  <title><filename>Makefile</filename></title>

	  <para>The <filename>Makefile</filename> defines some
	    variables that affect how the <acronym>XML</acronym>
	    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>,
	    to bring in the rest of the code that handles converting
	    documents from one format to another.</para>
	</sect4>

	<sect4>
	  <title><filename>book.xml</filename></title>

	  <para>This is the top level document in the Handbook.  It
	    contains the Handbook's <link linkend="xml-primer-doctype-declaration">DOCTYPE
	      declaration</link>, as well as the elements that
	    describe the Handbook's structure.</para>

	  <para><filename>book.xml</filename> uses <link linkend="xml-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="xml-primer-general-entities">general
	      entities</link> that are used throughout the rest of the
	    Handbook.</para>
	</sect4>

	<sect4>
	  <title><filename role="directory"><replaceable>directory</replaceable>/chapter.xml</filename></title>

	  <para>Each chapter in the Handbook is stored in a file
	    called <filename>chapter.xml</filename> in a separate
	    directory from the other chapters.  Each directory is
	    named after the value of the <literal>id</literal>
	    attribute on the <tag>chapter</tag>
	    element.</para>

	  <para>For example, if one of the chapter files
	    contains:</para>

	  <programlisting><tag class="starttag">chapter id="kernelconfig"</tag>
...
<tag class="endtag">chapter</tag></programlisting>

	  <para>Then it will be called
	    <filename>chapter.xml</filename> in the
	    <filename>kernelconfig</filename> directory.  In general,
	    the entire contents of the chapter are in this one
	    file.</para>

	  <para>When the <acronym>XHTML</acronym> 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.xml</filename>, and named after the value
	    of the <literal>id</literal> attribute on the file's
	    <tag>chapter</tag> element.  Now, it is possible
	    to include images in each chapter.  Images for each
	    Handbook chapter are stored within <filename>share/images/books/handbook</filename>.
	    The localized version of these images should be
	    placed in the same directory as the <acronym>XML</acronym>
	    sources for each chapter.  Namespace collisions are
	    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.xml</filename> files,
	    including <filename>basics/chapter.xml</filename>,
	    <filename>introduction/chapter.xml</filename>, and
	    <filename>printing/chapter.xml</filename>.</para>

	  <important>
	    <para>Do not name chapters or directories after
	      their ordering within the Handbook.  This ordering can
	      change as the content within the Handbook is
	      reorganized.  Reorganization should be possible without
	      renaming files, unless entire chapters are being
	      promoted or demoted within the hierarchy.</para>
	  </important>

	  <para>The <filename>chapter.xml</filename> files are not
	    complete <acronym>XML</acronym> documents that can be
	    built individually.  They can only be built
	    as parts of the whole Handbook.</para>
	</sect4>
      </sect3>
    </sect2>
  </sect1>
</chapter>