path: root/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml

<?xml version="1.0" encoding="ISO8859-1" standalone="no"?>
<!-- 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 organized in a
    particular fashion, and the documents that are part of the FDP are
    in turn organized 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
	organizations, 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 categorize the information.  For
	  example, the files that comprise the &man.make.1;
	  infrastructure are in <filename>share/mk</filename>, while
	  the additional XML 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 XHTML 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 XHTML 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 organized 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 Organization</title>

	<para>There are a number of files and directories within the
	  <filename>handbook</filename> directory.</para>

	<note>
	  <para>The Handbook's organization may change over time, and
	    this document may lag in detailing the organizational
	    changes.  If you have any questions about how the Handbook
	    is organized, 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 XML 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="xml-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="xml-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="xml-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="kernelconfig">
...
</chapter>]]></programlisting>

	  <para>Then it will be called
	    <filename>chapter.sgml</filename> in the
	    <filename>kernelconfig</filename> directory.  In general,
	    the entire contents of the chapter will be held in this
	    file.</para>

	  <para>When the XHTML version of the Handbook is produced,
	    this will yield <filename>kernelconfig.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.  Now, it is possible
	    to include images in each chapter.  Images for each
	    Handbook chapter are stored within <filename
	      class="directory">share/images/books/handbook</filename>.
	    Note that localized version of these images should be
	    placed in the same directory as the XML sources for each
	    chapter.  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 reorganized; this sort of
	      reorganization 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 XML 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 XML 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>