Yay, segmentedlists for everyone!

1 files changed, 158 insertions, 133 deletions

diff --git a/en_US/module-struct.xml b/en_US/module-struct.xml
index 8e67b91..400df6b 100644
--- a/en_US/module-struct.xml
+++ b/en_US/module-struct.xml
@@ -41,48 +41,62 @@
     |
     `-- Makefile]]></computeroutput></screen>
     </example>
-    <formalpara>
-      <title>Primary language directory (required)</title>
-      <para>This is the only directory absolutely required. It is named for the
-	original language of the document, such as <filename
-	  class="directory">en_US</filename> (US English).  The primary language
-	does not have to be US English; all languages are supported.  This
-	directory contains all the XML source for the actual document, as well
-	as XML source for document-specific
-	<firstterm>entities</firstterm><footnote>
-	  <para>Think of an XML entity as a predefined snippet of information.
-	    It can represent a chunk of XML source, or simply a word or
-	    character. If the information changes, it need be replaced only
-	    once, in the definition, to fix all usage.</para>
-	</footnote>.
-      </para>
-    </formalpara>
-    <formalpara>
-      <title>Graphics directory (optional)</title>
-      <para>The <filename class="directory">figs/</filename> directory is an
-	optional directory where graphics for the document should be stored. If
-	graphics are screenshots that are particular to a language, the
-	<filename class="directory">figs/</filename> directory can and should be
-	stored in a language directory.</para>
-    </formalpara>
-    <formalpara>
-      <title>Translation (PO) directory (optional)</title> 
-      <para>The <filename class="directory">po/</filename> directory contains
-	specially formatted files created and used by translators. The &FDP;
-	build tools use these files to create translated versions of documents.
-	The translated documents are not stored in CVS; they are created as
-	needed from these PO files.</para>
-    </formalpara>
-    <formalpara>
-      <title>Makefile (required)</title>
-      <para>The <filename>Makefile</filename> controls the build process. Its
-	content is discussed in <xref linkend="ex-makefile"/>.</para>
-    </formalpara>
-    <formalpara>
-      <title><filename>rpm-info.xml</filename> (required)</title>
-      <para>The <filename>rpm-info.xml</filename> file contains document
-	specific metadata</para>
-    </formalpara>
+    <segmentedlist id="sg-module-contents">
+      <title>CVS Module Contents</title>
+      <segtitle>Component</segtitle>
+      <segtitle>Type</segtitle>
+      <segtitle>Usage Notes</segtitle>
+      <seglistitem>
+	<seg>Primary language directory</seg>
+	<seg>required</seg>
+	<seg>This is the only directory absolutely required. It is named
+	  for the original language of the document, such as <filename
+	    class="directory">en_US</filename> (US English).  The
+	  primary language does not have to be US English; all languages
+	  are supported.  This directory contains all the XML source for
+	  the actual document, as well as XML source for
+	  document-specific <firstterm>entities</firstterm><footnote>
+	    <para>Think of an XML entity as a predefined snippet of
+	      information. It can represent a chunk of XML source, or
+	      simply a word or character. If the information changes, it
+	      need be replaced only once, in the definition, to fix all
+	      usage.</para>
+	  </footnote>.</seg>
+      </seglistitem>   
+      <seglistitem>
+	<seg>Graphics directory</seg>
+	<seg>optional</seg>
+	<seg>The <filename class="directory">figs/</filename> directory
+	  is an optional directory where graphics for the document
+	  should be stored. If graphics are screenshots that are
+	  particular to a language, the <filename
+	    class="directory">figs/</filename> directory can and should
+	  be stored in a language directory.</seg>
+      </seglistitem>
+      <seglistitem>
+	<seg>Translation (PO) directory</seg>
+	<seg>optional</seg> 
+	<seg>The <filename class="directory">po/</filename> directory
+	  contains specially formatted files created and used by
+	  translators. The &FDP; build tools use these files to create
+	  translated versions of documents. The translated documents are
+	  not stored in CVS; they are created as needed from these PO
+	  files.</seg>
+      </seglistitem>
+      <seglistitem>
+	<seg>Makefile</seg>
+	<seg>required</seg>
+	<seg>The <filename>Makefile</filename> controls the build
+	  process. Its content is discussed in <xref
+	    linkend="ex-makefile"/>.</seg>
+      </seglistitem>
+      <seglistitem>
+	<seg><filename>rpm-info.xml</filename></seg>
+	<seg>required</seg>
+	<seg>The <filename>rpm-info.xml</filename> file contains
+	  document specific metadata</seg>
+      </seglistitem>
+    </segmentedlist>
   </section>
   <section id="ch-getting-files-build-system">
     <title>The Document Build System</title>
@@ -109,7 +123,7 @@
       <example id="ex-makefile">
 	<title>Sample Document Makefile</title>
 	<programlisting><![CDATA[DOCBASE         = example-doc
-PRI_LANG      	= en_US
+PRI_LANG        = en_US
 OTHERS          = de pt
 DOC_ENTITIES    = doc-entities
 
@@ -125,48 +139,54 @@ include ../docs-common/Makefile.common]]></programlisting>
 	such as the <command>XMLFILES_template</command> stanza.  An
 	explanation for this template appears a few paragraphs
 	below.</para>
-      <formalpara>
-	<title><systemitem class="macro">DOCBASE</systemitem></title>
-	<para>This variable contains the name for the main (parent) XML
-	  document. Follow convention by naming your document after the
-	  module name.</para>
-      </formalpara>
-      <formalpara>
-	<title><systemitem class="macro">PRI_LANG</systemitem></title>
-	<para>This variable contains the ISO code for the original
-	  version of the document, such as
-	  <systemitem>en_US</systemitem>.</para>
-      </formalpara>
-      <formalpara>
-	<title><systemitem class="macro">OTHERS</systemitem></title>
-	<para>This variable contains a listing of ISO codes for any
-	  other versions into which the document has been translated.
-	  The module must contain a <filename
-	    class="directory">po/</filename> directory and a PO file for
-	  any indicated additional languages.</para>
-      </formalpara>
-      <formalpara>
-      <title><systemitem class="macro">DOC_ENTITIES</systemitem></title>
-      <para>This variable contains a listing of any files containing
-	entity definitions.  The &FDP; uses a special XML format to
-	record document-specific entities, so they can be translated and
-	built on the fly like any other XML document.  An example is
-	shown later in this guide. <!-- need xref here --></para>
-      </formalpara>
-      <formalpara>
-	<title><systemitem
-	    class="macro">XMLFILES_template</systemitem></title>
-	<para>This template allows the build tools to work with the
-	  document in multiple languages once it is translated.  The
-	  <systemitem class="macro">${1}</systemitem> marking is a
-	  variable used to substitute the appropriate language.  This
-	  template is not terribly complicated.  For a new module,
-	  duplicate this section exactly except for the actual
-	  filenames. Prepend the text <systemitem
-	    class="macro">${1}/</systemitem>, in place of the language
-	  code directory name, to each filename in your document.
-	</para>
-      </formalpara>
+      <segmentedlist id="sg-makefile-variables">
+	<title>Makefile Variables</title>
+	<segtitle>Variable</segtitle>
+	<segtitle>Explanation</segtitle>
+	<seglistitem>
+	  <seg><systemitem class="macro">DOCBASE</systemitem></seg>
+	  <seg>This variable contains the name for the main (parent) XML
+	    document. Follow convention by naming your document after
+	    the module name.</seg>
+	</seglistitem>
+	<seglistitem>
+	  <seg><systemitem class="macro">PRI_LANG</systemitem></seg>
+	  <seg>This variable contains the ISO code for the original
+	    version of the document, such as
+	    <systemitem>en_US</systemitem>.</seg>
+	</seglistitem>
+	<seglistitem>
+	  <seg><systemitem class="macro">OTHERS</systemitem></seg>
+	  <seg>This variable contains a listing of ISO codes for any
+	    other versions into which the document has been translated.
+	    The module must contain a <filename
+	      class="directory">po/</filename> directory and a PO file
+	    for any indicated additional languages.</seg>
+	</seglistitem>
+	<seglistitem>
+	  <seg><systemitem class="macro">DOC_ENTITIES</systemitem></seg>
+	  <seg>This variable contains a listing of any files containing
+	    entity definitions.  The &FDP; uses a special XML format to
+	    record document-specific entities, so they can be translated
+	    and built on the fly like any other XML document.  An
+	    example is shown later in this guide. <!-- need xref here
+	    --></seg>
+	</seglistitem>
+	<seglistitem>
+	  <seg><systemitem
+	      class="macro">XMLFILES_template</systemitem></seg>
+	  <seg>This template allows the build tools to work with the
+	    document in multiple languages once it is translated.  The
+	    <systemitem class="macro">${1}</systemitem> marking is a
+	    variable used to substitute the appropriate language.  This
+	    template is not terribly complicated.  For a new module,
+	    duplicate this section exactly except for the actual
+	    filenames. Prepend the text <systemitem
+	      class="macro">${1}/</systemitem>, in place of the language
+	    code directory name, to each filename in your document.
+	  </seg>
+	</seglistitem>
+      </segmentedlist>
       <important>
 	<title>Files Exempt From Listing</title>
 	<para>Do not include the document-specific entities XML file or
@@ -233,54 +253,59 @@ include ../docs-common/Makefile.common]]></programlisting>
       To render the <abbrev>XML</abbrev> document into another format,
       use one of the following <command>make</command> targets:
     </para>
-    <formalpara>
-      <title><systemitem class="macro">html</systemitem></title>
-      <para>This target builds the "chunked" <abbrev>HTML</abbrev>
-	document for each defined translation.  Output is placed in a
-	separate directory named <filename class="directory"><systemitem
-	    class="macro">${DOCBASE}</systemitem>-<systemitem
-	    class="macro">${LANG}</systemitem>/</filename>. Each
-	document section is a separate file within that
-	directory.</para>
-    </formalpara>
-    <formalpara>
-      <title><systemitem
-	  class="macro">html-nochunks</systemitem></title>
-      <para>This target builds the "non-chunked" <abbrev>HTML</abbrev>
-	document for each defined translation. Output is placed in a
-	single file: <filename><systemitem
-	    class="macro">${DOCBASE}</systemitem>-<systemitem
-	    class="macro">${LANG}</systemitem>.html</filename>; no other
-	files are created.</para>
-    </formalpara>
-    <formalpara>
-      <title><systemitem class="macro">pdf</systemitem></title>
-      <para>This target builds only the <abbrev>PDF</abbrev> document
-	for all document languages. <abbrev>PDF</abbrev> production is
-	currently erratic and may not work for your document.</para>
-    </formalpara>
-    <formalpara>
-      <title><systemitem class="macro">tarball</systemitem></title>
-      <para>This target builds only the <command>tar(1)</command>
-	archive for all document languages.</para>
-    </formalpara>
-    <formalpara>
-      <title><systemitem class="macro">all</systemitem></title>
-      <para>This target builds all targets listed above.</para>
-    </formalpara>
-    <formalpara>
-      <title><systemitem class="macro">clean</systemitem></title>
-      <para>This target deletes any temporary, or generated files, but
-	does <emphasis>not</emphasis> erase any <abbrev>HTML</abbrev>,
-	<abbrev>PDF</abbrev>, or archive files.</para>
-    </formalpara>
-    <formalpara>
-      <title><systemitem class="macro">distclean</systemitem></title>
-      <para>This target erases all <abbrev>HTML</abbrev>,
-	<abbrev>PDF</abbrev>, and archive files.  This target
-	automatically invokes the <filename>clean</filename> target as
-	well.</para>
-    </formalpara>
+    <segmentedlist>
+      <title>Build Targets</title>
+      <segtitle>Target</segtitle>
+      <segtitle>Explanation</segtitle>
+      <seglistitem>
+	<seg><systemitem class="macro">html</systemitem></seg>
+	<seg>This target builds the "chunked" <abbrev>HTML</abbrev>
+	  document for each defined translation.  Output is placed in a
+	  separate directory named <filename
+	    class="directory"><systemitem
+	      class="macro">${DOCBASE}</systemitem>-<systemitem
+	      class="macro">${LANG}</systemitem>/</filename>. Each
+	  document section is a separate file within that
+	  directory.</seg>
+      </seglistitem>
+      <seglistitem>
+	<seg><systemitem class="macro">html-nochunks</systemitem></seg>
+	<seg>This target builds the "non-chunked" <abbrev>HTML</abbrev>
+	  document for each defined translation. Output is placed in a
+	  single file: <filename><systemitem
+	      class="macro">${DOCBASE}</systemitem>-<systemitem
+	      class="macro">${LANG}</systemitem>.html</filename>; no
+	  other files are created.</seg>
+      </seglistitem>
+      <seglistitem>
+	<seg><systemitem class="macro">pdf</systemitem></seg>
+	<seg>This target builds only the <abbrev>PDF</abbrev> document
+	  for all document languages. <abbrev>PDF</abbrev> production is
+	  currently erratic and may not work for your document.</seg>
+      </seglistitem>
+      <seglistitem>
+	<seg><systemitem class="macro">tarball</systemitem></seg>
+	<seg>This target builds only the <command>tar(1)</command>
+	  archive for all document languages.</seg>
+      </seglistitem>
+      <seglistitem>
+	<seg><systemitem class="macro">all</systemitem></seg>
+	<seg>This target builds all targets listed above.</seg>
+      </seglistitem>
+      <seglistitem>
+	<seg><systemitem class="macro">clean</systemitem></seg>
+	<seg>This target deletes any temporary, or generated files, but
+	  does <emphasis>not</emphasis> erase any <abbrev>HTML</abbrev>,
+	  <abbrev>PDF</abbrev>, or archive files.</seg>
+      </seglistitem>
+      <seglistitem>
+	<seg><systemitem class="macro">distclean</systemitem></seg>
+	<seg>This target erases all <abbrev>HTML</abbrev>,
+	  <abbrev>PDF</abbrev>, and archive files.  This target
+	  automatically invokes the <filename>clean</filename> target as
+	  well.</seg>
+      </seglistitem>
+    </segmentedlist>
     <section>
       <title>Adding or Changing Targets</title>
       <para>