Skip site navigation (1)Skip section navigation (2)
Date:      Mon, 21 May 2012 14:21:17 +0000 (UTC)
From:      Warren Block <wblock@FreeBSD.org>
To:        doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org
Subject:   svn commit: r38868 - head/en_US.ISO8859-1/books/fdp-primer/structure
Message-ID:  <201205211421.q4LELHLh061406@svn.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: wblock
Date: Mon May 21 14:21:16 2012
New Revision: 38868
URL: http://svn.freebsd.org/changeset/doc/38868

Log:
  Whitespace-only fixes, wrap long lines and correct indentation.
  Translators, please ignore.

Modified:
  head/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml

Modified: head/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml	Mon May 21 13:11:29 2012	(r38867)
+++ head/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml	Mon May 21 14:21:16 2012	(r38868)
@@ -33,14 +33,15 @@
 <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>
+  <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>
+      <para>Make it easy to automate converting the document to other
+	formats.</para>
     </listitem>
 
     <listitem>
@@ -50,21 +51,23 @@
     </listitem>
 
     <listitem>
-      <para>Make it easy to decide where in the tree new documentation should
-	be placed.</para>
+      <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>
+  <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>
+    <para>There are two types of directory under
+      <filename>doc/</filename>, each with very specific directory
+      names and meanings.</para>
 
     <segmentedlist>
       <segtitle>Directory</segtitle>
@@ -73,39 +76,41 @@
 
       <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 SGML support
-	  files (such as the FreeBSD extended DocBook DTD) are in
+
+	<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 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
+
+	<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>
+	  <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>
+      <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>
+      documentation is split into up to three more categories at
+      this level, indicated by the different directory names.</para>
 
     <segmentedlist>
       <segtitle>Directory</segtitle>
@@ -114,43 +119,47 @@
 
       <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 HTML file.</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 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 into chapters.  Normally
-	  available as both one large HTML 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>
+
+	<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 HTML 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>
+
+	<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
+      <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>
+    <para>This section contains specific notes about particular
+      documents managed by the FDP.</para>
 
     <sect2>
       <title>The Handbook</title>
@@ -159,52 +168,55 @@
 
       <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>,
+
+      <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>
+	  <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 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>
+
+	  <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
+
+	  <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>
+	      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
+	    <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>
@@ -212,69 +224,75 @@
 	<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>
+	  <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>
-	  
+	  <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
+	  <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 HTML 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 SGML 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>,
+
+	  <para>When the HTML 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 SGML 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>
+	    <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 SGML 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 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 has had on just
-	    one chapter.</para>
+
+	  <para>Each <filename>chapter.sgml</filename> file will not
+	    be a complete SGML 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 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 has had on just one
+	    chapter.</para>
 	</sect4>
       </sect3>
     </sect2>



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201205211421.q4LELHLh061406>