aboutsummaryrefslogtreecommitdiff
path: root/en/tutorials/docproj-primer/the-handbook/chapter.sgml
diff options
context:
space:
mode:
authorNik Clayton <nik@FreeBSD.org>1999-04-20 20:59:59 +0000
committerNik Clayton <nik@FreeBSD.org>1999-04-20 20:59:59 +0000
commitc4ab126805b0ecf8d200daba8990ddaac649b18f (patch)
tree17449c394290549d27f07d8049ae25ae811bb03f /en/tutorials/docproj-primer/the-handbook/chapter.sgml
parent8bdee18bd8c6ee8c3846276f21b651b1ed393420 (diff)
downloaddoc-c4ab126805b0ecf8d200daba8990ddaac649b18f.tar.gz
doc-c4ab126805b0ecf8d200daba8990ddaac649b18f.zip
My primer for people new to the Doc. Proj. Incomplete, but should be
enough for most people, and gets it into the repository, making it easier for others to add to as necessary. This has not (yet) been turned on in the upper level Makefile or listed on the web site yet, I want to get some more feedback from readers first. It should be "made visible" later this week.
Notes
Notes: svn path=/head/; revision=4718
Diffstat (limited to 'en/tutorials/docproj-primer/the-handbook/chapter.sgml')
-rw-r--r--en/tutorials/docproj-primer/the-handbook/chapter.sgml280
1 files changed, 280 insertions, 0 deletions
diff --git a/en/tutorials/docproj-primer/the-handbook/chapter.sgml b/en/tutorials/docproj-primer/the-handbook/chapter.sgml
new file mode 100644
index 0000000000..9b860d2e7f
--- /dev/null
+++ b/en/tutorials/docproj-primer/the-handbook/chapter.sgml
@@ -0,0 +1,280 @@
+<!-- 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.
+-->
+
+<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="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="parameter-entities">parameter entities</link> to load in
+ the files with the <filename>.ent</filename> extension. These files
+ (described later) then define <link linkend="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:
+-->
+