path: root/en/tutorials/docproj-primer/the-handbook/chapter.sgml

<!-- 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.4 1999-07-28 20:06:03 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>&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:
-->