path: root/en_US.ISO_8859-1/books/fdp-primer/structure/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.

     $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/structure/chapter.sgml,v 1.2 1999/09/06 06:52:42 peter Exp $
-->

<chapter id="structure">
  <title>Structuring documents under <filename>doc/</filename></title>

  <para>The <filename>doc/</filename> tree is organised in a particular
    fashion, and the documents that are part of the FDP are in turn organised
    in a particular fashion.  The aim is to make it simple to add new
    documentation in to the tree and;</para>

  <orderedlist>
    <listitem>
      <para>be easy to automate converting the document to other formats</para>
    </listitem>

    <listitem>
      <para>promote consistency between the different documentation
	organisations, 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>
    <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>
      <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 categorise the information.  For example, the files that
	  comprise the &man.make.1; infrastructure are in
	  <filename>share/mk</filename>, while the additional SGML 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.ISO_8859-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>
    <title>The
      <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename> directories</title>

    <para>These directories contain the documents themselves.  The
	documentation is split in to up to three more categories at this
	level, indicated by the different directory names.</para>

    <segmentedlist>
      <seglistitem>
	<seg><filename>articles</filename></seg>
	
	<seg>Documentation marked up as a DocBook <sgmltag>article</sgmltag> 
	  (or equivalent).  Reasonably short, and broken up in to sections.
	  Normally only available as one HTML 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 in to chapters.  Normally
	  available as both one large HTML file (for people with fast
	  connections, or who want to print it easily from their 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 much translation has been accomplished by that translation
      team.</para>
  </sect1>
  
  <sect1>
    <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 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>
  
      <sect3>
	<title>Physical organisation</title>
	
	<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>
	
	<sect4>
	  <title><filename>Makefile</filename></title>
	  
	  <para>The <filename>Makefile</filename> defines some variables that
	    affect how the SGML 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="sgml-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="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>
	</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="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>book.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 as
	        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>
	</sect4>
      </sect3>
    </sect2>
  </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:
-->