aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO_8859-1/books/fdp-primer/the-handbook/chapter.sgml
diff options
context:
space:
mode:
Diffstat (limited to 'en_US.ISO_8859-1/books/fdp-primer/the-handbook/chapter.sgml')
-rw-r--r--en_US.ISO_8859-1/books/fdp-primer/the-handbook/chapter.sgml282
1 files changed, 0 insertions, 282 deletions
diff --git a/en_US.ISO_8859-1/books/fdp-primer/the-handbook/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/the-handbook/chapter.sgml
deleted file mode 100644
index c494990ff9..0000000000
--- a/en_US.ISO_8859-1/books/fdp-primer/the-handbook/chapter.sgml
+++ /dev/null
@@ -1,282 +0,0 @@
-<!-- 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.6 1999-08-29 16:08:43 jhb 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>freebsd-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>&lt;para&gt;</literal>,
- <emphasis>not</emphasis> <literal>&lt;PARA&gt;</literal>.</para>
-
- <para>Text that appears in SGML contexts is generally written in upper
- case, <literal>&lt!ENTITY&hellip;&gt;</literal>, and
- <literal>&lt;!DOCTYPE&hellip;&gt;</literal>, <emphasis>not</emphasis>
- <literal>&lt;!entity&hellip;&gt;</literal> and
- <literal>&lt;!doctype&hellip;&gt;</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:
--->
-