282 lines
11 KiB
Text
282 lines
11 KiB
Text
<!-- 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.5 1999-07-30 20:51:00 nik Exp $
|
|
-->
|
|
|
|
<chapter id="the-handbook">
|
|
<title>* The Handbook</title>
|
|
|
|
<sect1>
|
|
<title>Logical structure</title>
|
|
|
|
<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>
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>Physical organisation</title>
|
|
|
|
<para>The Handbook (and its translations) are in the
|
|
<filename>doc/<replaceable>language</replaceable>/handbook</filename>
|
|
subdirectory of the main CVS
|
|
repository. <replaceable>language</replaceable> corresponds to the ISO
|
|
language code for that translation, <literal>en</literal> for English,
|
|
<literal>ja</literal> for Japanese, and so on.</para>
|
|
|
|
<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
|
|
FreeBSD Documentation Project, <email>doc@FreeBSD.ORG</email>.</para>
|
|
</note>
|
|
|
|
<sect2>
|
|
<title><filename>Makefile</filename></title>
|
|
|
|
<para>The <filename>Makefile</filename> defines the rules that are used
|
|
to convert the Handbook from its source form (DocBook) to a number of
|
|
other target formats (including HTML, PostScript, and plain
|
|
text).</para>
|
|
|
|
<para>A more detailed description of the <filename>Makefile</filename>
|
|
is in <xref linkend="the-handbook-converting">.</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title><filename>handbook.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>handbook.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>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<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>handbook.sgml</filename>, and named after
|
|
the value of the <literal>id</literal> attribute on the file's
|
|
<sgmltag>chapter</sgmltag> element. Moving them in to 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 reorganistion 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
|
|
line at the start of the file.</para>
|
|
|
|
<para>This is unfortunate for two reasons;</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>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 as had on just one
|
|
chapter.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Emacs' <literal>sgml-mode</literal> can not use it to
|
|
determine the DTD to use, losing useful benefits of
|
|
<literal>sgml-mode</literal> (element completion, automatic
|
|
validation, and so on).</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>Style guide</title>
|
|
|
|
<para>To keep the source for the Handbook consistent when many different
|
|
people are editing it, please follow these style conventions.</para>
|
|
|
|
<sect2>
|
|
<title>Letter case</title>
|
|
|
|
<para>Tags are entered in lower case, <literal><para></literal>,
|
|
<emphasis>not</emphasis> <literal><PARA></literal>.</para>
|
|
|
|
<para>Text that appears in SGML contexts is generally written in upper
|
|
case, <literal><!ENTITY…></literal>, and
|
|
<literal><!DOCTYPE…></literal>, <emphasis>not</emphasis>
|
|
<literal><!entity…></literal> and
|
|
<literal><!doctype…></literal>.</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Indentation</title>
|
|
|
|
<para>Each file starts with indentation set at column 0,
|
|
<emphasis>regardless</emphasis> of the indentation level of the file
|
|
which might contain this one.</para>
|
|
|
|
<para>Every start tag increases the indentation level by 2 spaces, and
|
|
every end tag decreases the indentation level by 2 spaces. Content
|
|
within elements should be indented by two spaces if the content runs
|
|
over more than one line.</para>
|
|
|
|
<para>For example, the source for this section looks something
|
|
like;</para>
|
|
|
|
<programlisting>
|
|
<![ CDATA [+--- This is column 0
|
|
V
|
|
<chapter>
|
|
<title>...</title>
|
|
|
|
<sect1>
|
|
<title>...</title>
|
|
|
|
<sect2>
|
|
<title>Indentation</title>
|
|
|
|
<para>Each file starts with indentation set at column 0,
|
|
<emphasis>regardless</emphasis> of the indentation level of the file
|
|
which might contain this one.</para>
|
|
|
|
<para>Every start tag increases the indentation level by 2 spaces, and
|
|
every end tag decreases the indentation level by 2 spaces. Content
|
|
within elements should be indented by two spaces if the content runs
|
|
over more than one line.</para>
|
|
|
|
...
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>]]></programlisting>
|
|
|
|
<para>If you use <application>Emacs</application> or
|
|
<application>Xemacs</application> to edit the files then
|
|
<literal>sgml-mode</literal> should be loaded automatically, and the
|
|
Emacs local variables at the bottom of each file should enforce these
|
|
styles.</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>White space changes</title>
|
|
|
|
<para>When committing changes, <emphasis>do not commit changes to the
|
|
content at the same time as changes to the
|
|
formatting</emphasis>.</para>
|
|
|
|
<para>This is so that the teams that convert the Handbook to other
|
|
languages can quickly see what content has actually changed in your
|
|
commit, without having to decide whether a line has changed because of
|
|
the content, or just because it has been refilled.</para>
|
|
|
|
<para>For example, if you have added two sentances to a paragraph, such
|
|
that the line lengths on the paragraph now go over 80 columns, first
|
|
commit your change with the too-long line lengths. Then fix the line
|
|
wrapping, and commit this second change. In the commit message for
|
|
the second change, be sure to indicate that this is a whitespace-only
|
|
change, and that the translation team can ignore it.</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="the-handbook-converting">
|
|
<title>Converting the Handbook to other formats</title>
|
|
|
|
<para></para>
|
|
</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:
|
|
-->
|
|
|