A new chapter that explains the structure of the doc/ tree and how

documentation is placed under it.  Replaces the empty FAQ section and the
only partly completed Handbook section.  This is because the information
in here applies to all the documentation under doc/, not just the Handbook.

Move the style guide information out of the-handbook/chapter.sgml and in
to writing-style/chapter.sgml.  It doesn't really belong here either, but
we don't have a general style chapter (yet).

Update Makefile to know about this, and use the doc.project.mk file.

Update book.sgml to know about the new chapter.

Remove the old chapters.

1 files changed, 299 insertions, 0 deletions

diff --git a/en_US.ISO_8859-1/books/fdp-primer/structure/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/structure/chapter.sgml
new file mode 100644
index 0000000000..0fcb999857
--- /dev/null
+++ b/en_US.ISO_8859-1/books/fdp-primer/structure/chapter.sgml
@@ -0,0 +1,299 @@
+<!-- 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.1 1999-09-03 17:22:38 nik 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 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>
+	</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:
+-->
+