<!-- 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 organised in a particular
fashion, and the documents that are part of the FDP are in turn organised
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
organisations, 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 categorise 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 organised 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 organisation</title>
<para>There are a number of files and directories within the
<filename>handbook</filename> directory.</para>
<note>
<para>The Handbook's organisation may change over time, and this
document may lag in detailing the organisational changes. If you
have any questions about how the Handbook is organised, 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="kernelconfiguration">
...
</chapter>]]></programlisting>
<para>then it will be called <filename>chapter.sgml</filename> in
the <filename>kernelconfiguration</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>kernelconfiguration.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. Moving them into
separate directories prepares for future plans for the Handbook.
Specifically, it will soon be possible to include images in each
chapter. It makes more sense for each image to be stored in a
directory with the text for the chapter than to try and keep the
text for all the chapters, and all the images, in one large
directory. 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 reorganised;
this sort of reorganisation 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:
-->