305 lines
11 KiB
XML
305 lines
11 KiB
XML
<?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.Big5/</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>
|