Edit, update, and simplify the structure chapter.

Reviewed by:	bps and Allan Jude on IRC

1 files changed, 95 insertions, 92 deletions

diff --git a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml
index 7a688264b4..c4ebeb7d60 100644
--- a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml
+++ b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml
@@ -32,12 +32,10 @@
 -->
 
 <chapter id="structure">
-  <title>Structuring Documents Under <filename>doc/</filename></title>
+  <title>Documentation Directory Structure</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>
+  <para>Files and directories in the <filename class="directory">doc/</filename> tree follow a structure
+    meant to:</para>
 
   <orderedlist>
     <listitem>
@@ -58,50 +56,57 @@
   </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
+    documents in many different languages and
+    encodings.  It is important that
+    the documentation tree structure does not enforce any particular defaults or
     cultural preferences.</para>
 
   <sect1 id="structure-top">
-    <title>The Top Level, <filename>doc/</filename></title>
+    <title>The Top Level, <filename class="directory">doc/</filename></title>
 
     <para>There are two types of directory under
-      <filename>doc/</filename>, each with very specific directory
+      <filename class="directory">doc/</filename>, each with very specific directory
       names and meanings.</para>
 
-    <segmentedlist>
-      <segtitle>Directory</segtitle>
+    <informaltable pgwide="1" frame="none">
+      <tgroup cols="2">
+	<thead>
+	  <row>
+	    <entry>Directory</entry>
+	    <entry>Usage</entry>
+	  </row>
+	</thead>
 
-      <segtitle>Meaning</segtitle>
+	<tbody>
+	  <row>
+	    <entry valign="top"><filename class="directory">share</filename></entry>
 
-      <seglistitem>
-	<seg><filename>share/</filename></seg>
-
-	<seg>Contains files that are not specific to the various
+	    <entry>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/xml</filename>.</seg>
-      </seglistitem>
+	  infrastructure are in <filename class="directory">share/mk</filename>, while
+	  the additional <acronym>XML</acronym> support files (such as the &os;
+	  extended DocBook <acronym>DTD</acronym>) are in
+	  <filename class="directory">share/xml</filename>.</entry>
+	  </row>
 
-      <seglistitem>
-	<seg><filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename></seg>
+	  <row>
+	    <entry valign="top"><filename class="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename></entry>
 
-	<seg>One directory exists for each available translation and
+	    <entry>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
+	  <filename class="directory">en_US.ISO8859-1/</filename> and
+	  <filename class="directory">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>
+	  future headaches when a translation team wants to provide
+	  documentation in the same language but in more than one
+	  encoding.  This also avoids
+	  problems that might be caused by a future switch to Unicode.</entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </informaltable>
   </sect1>
 
   <sect1 id="structure-locale">
@@ -113,51 +118,58 @@
       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>
+    <informaltable pgwide="1" frame="none">
+      <tgroup cols="2">
+	<thead>
+	  <row>
+	    <entry>Directory</entry>
+	    <entry>Usage</entry>
+	  </row>
+	</thead>
 
-      <seglistitem>
-	<seg><filename>articles</filename></seg>
+	<tbody>
+	  <row>
+	    <entry valign="top"><filename class="directory">articles</filename></entry>
 
-	<seg>Documentation marked up as a DocBook
+	    <entry>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>
+	  as one <acronym>XHTML</acronym> file.</entry>
+	  </row>
 
-      <seglistitem>
-	<seg><filename>books</filename></seg>
+	  <row>
+	    <entry valign="top"><filename>books</filename></entry>
 
-	<seg>Documentation marked up as a DocBook
+	    <entry>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
+	  large <acronym>XHTML</acronym> 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>
+	      of linked, smaller files.</entry>
+	  </row>
 
-      <seglistitem>
-	<seg><filename>man</filename></seg>
+	  <row>
+	    <entry valign="top"><filename class="directory">man</filename></entry>
 
-	<seg>For translations of the system manual pages.  This
+	    <entry>For translations of the system manual pages.  This
 	  directory will contain one or more
-	  <filename>man<replaceable>n</replaceable></filename>
+	  <filename class="directory">man<replaceable>n</replaceable></filename>
 	  directories, corresponding to the sections that have been
-	  translated.</seg>
-      </seglistitem>
-    </segmentedlist>
+	      translated.</entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </informaltable>
 
     <para>Not every
-      <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename>
-      directory will contain all of these directories.  It depends on
+      <filename class="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename>
+      directory will contain all of these subdirectories.  It depends on
       how much translation has been accomplished by that translation
       team.</para>
   </sect1>
 
   <sect1 id="structure-document">
-    <title>Document Specific Information</title>
+    <title>Document-Specific Information</title>
 
     <para>This section contains specific notes about particular
       documents managed by the FDP.</para>
@@ -167,12 +179,12 @@
 
       <subtitle><filename>books/handbook/</filename></subtitle>
 
-      <para>The Handbook is written to comply with the FreeBSD DocBook
+      <para>The Handbook is written in DocBook <acronym>XML</acronym> using the &os; 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>book</sgmltag>.  The book is divided into
+	<sgmltag>part</sgmltag>s, each of which contains several
 	<sgmltag>chapter</sgmltag>s.  <sgmltag>chapter</sgmltag>s are
 	further subdivided into sections (<sgmltag>sect1</sgmltag>)
 	and subsections (<sgmltag>sect2</sgmltag>,
@@ -187,18 +199,18 @@
 	<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>
+	    changes.  Post questions about Handbook
+	    organization to &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
+	    variables that affect how the <acronym>XML</acronym> 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
+	    <filename>doc.project.mk</filename>, to bring in the
 	    rest of the code that handles converting documents from
 	    one format to another.</para>
 	</sect4>
@@ -223,7 +235,7 @@
 	</sect4>
 
 	<sect4>
-	  <title><filename><replaceable>directory</replaceable>/chapter.xml</filename></title>
+	  <title><filename class="directory"><replaceable>directory</replaceable>/chapter.xml</filename></title>
 
 	  <para>Each chapter in the Handbook is stored in a file
 	    called <filename>chapter.xml</filename> in a separate
@@ -235,10 +247,9 @@
 	  <para>For example, if one of the chapter files
 	    contains:</para>
 
-	  <programlisting><![CDATA[
-<chapter id="kernelconfig">
+	  <programlisting><sgmltag class="starttag">chapter id="kernelconfig"</sgmltag>
 ...
-</chapter>]]></programlisting>
+<sgmltag class="endtag">chapter</sgmltag></programlisting>
 
 	  <para>Then it will be called
 	    <filename>chapter.xml</filename> in the
@@ -246,12 +257,12 @@
 	    the entire contents of the chapter will be held in this
 	    file.</para>
 
-	  <para>When the XHTML version of the Handbook is produced,
+	  <para>When the <acronym>XHTML</acronym> 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
+	  <para>In earlier versions of the Handbook, the files were
 	    stored in the same directory as
 	    <filename>book.xml</filename>, and named after the value
 	    of the <literal>id</literal> attribute on the file's
@@ -259,8 +270,8 @@
 	    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
+	    Note that the localized version of these images should be
+	    placed in the same directory as the <acronym>XML</acronym> 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
@@ -273,27 +284,19 @@
 	    <filename>printing/chapter.xml</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>
+	    <para>Do not name chapters or directories after
+	      their ordering within the
+	      Handbook.  This ordering can change as the content
+	      within the Handbook is reorganized.
+	      Reorganization should be possible without
+	      renaming files, unless entire chapters are being
+	      promoted or demoted within the hierarchy.</para>
 	  </important>
 
-	  <para>Each <filename>chapter.xml</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>
+	  <para>The <filename>chapter.xml</filename> files are not
+	    complete <acronym>XML</acronym> documents. They cannot be
+	    individually rendered to output formats, but must be built
+	    as part of the Handbook.</para>
 	</sect4>
       </sect3>
     </sect2>