Add a variablelist example to the Lists and Procedures section, and

give it and the <procedure> entry separate examples.

en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml

@@ -829,11 +829,11 @@
 	accomplish a particular goal.</para>
 
       <para>To do this, use <tag>itemizedlist</tag>,
-	<tag>orderedlist</tag>, or
+	<tag>orderedlist</tag>, <tag>variablelist</tag>, or
 	<tag>procedure</tag><footnote><para>There are other
 	    types of list element in DocBook, but we are not
 	    concerned with those at the
-	    moment.</para></footnote></para>
+	    moment.</para></footnote>.</para>
 
       <para><tag>itemizedlist</tag> and
 	<tag>orderedlist</tag> are similar to their
@@ -845,16 +845,9 @@
 	analogous to <acronym>HTML</acronym>'s <tag>li</tag>
 	tags.  However, unlike HTML, they are required.</para>
 
-      <para><tag>procedure</tag> is slightly different.  It
-	consists of <tag>step</tag>s, which may in turn
-	consists of more <tag>step</tag>s or
-	<tag>substep</tag>s.  Each <tag>step</tag>
-	contains block elements.</para>
-
       <example>
-	<title><tag>itemizedlist</tag>,
+	<title><tag>itemizedlist</tag> and
-	  <tag>orderedlist</tag>, and
+	  <tag>orderedlist</tag></title>
-	  <tag>procedure</tag></title>
 
 	<para>Usage:</para>
 
@@ -876,21 +869,7 @@
   <tag class="starttag">listitem</tag>
     <tag class="starttag">para</tag>This is the second ordered item.<tag class="endtag">para</tag>
   <tag class="endtag">listitem</tag>
-<tag class="endtag">orderedlist</tag>
+<tag class="endtag">orderedlist</tag></programlisting>
-
-<tag class="starttag">procedure</tag>
-  <tag class="starttag">step</tag>
-    <tag class="starttag">para</tag>Do this.<tag class="endtag">para</tag>
-  <tag class="endtag">step</tag>
-
-  <tag class="starttag">step</tag>
-    <tag class="starttag">para</tag>Then do this.<tag class="endtag">para</tag>
-  <tag class="endtag">step</tag>
-
-  <tag class="starttag">step</tag>
-    <tag class="starttag">para</tag>And now do this.<tag class="endtag">para</tag>
-  <tag class="endtag">step</tag>
-<tag class="endtag">procedure</tag></programlisting>
 
 	<para>Appearance:</para>
 
@@ -913,6 +892,97 @@
 	    <para>This is the second ordered item.</para>
 	  </listitem>
 	</orderedlist>
+      </example>
+
+      <para xml:id="docbook-markup-varlist">An alternate and often
+	useful way of presenting information is the
+	<tag>variablelist</tag>.  These are lists where each entry has
+	a term and a description.  They are well suited for many types
+	of descriptions, and present information in a form that is
+	often easier for the reader than sections and
+	subsections.</para>
+
+      <para>A <tag>variablelist</tag> has a <tag>title</tag>, and then
+	pairs of <tag>term</tag> and <tag>listitem</tag>
+	entries.</para>
+
+      <example xml:id="docbook-markup-variablelist-example">
+	<title><tag>variablelist</tag></title>
+
+	<para>Usage:</para>
+
+	<programlisting><tag class="starttag">variablelist</tag>
+  <tag class="starttag">varlistentry</tag>
+    <tag class="starttag">term</tag>Parallel<tag class="endtag">varlistentry</tag>
+
+    <tag class="starttag">listitem</tag>
+      <tag class="starttag">para</tag>In parallel communications, groups of bits arrive
+	at the same time over multiple communications
+	channels.<tag class="endtag">para</tag>
+    <tag class="endtag">listitem</tag>
+  <tag class="endtag">varlistentry</tag>
+
+  <tag class="starttag">varlistentry</tag>
+    <tag class="starttag">term</tag>Serial<tag class="endtag">varlistentry</tag>
+
+    <tag class="starttag">listitem</tag>
+      <tag class="starttag">para</tag>In serial communications, bits arrive one at a
+	time over a single communications
+	channel.<tag class="endtag">para</tag>
+    <tag class="endtag">listitem</tag>
+  <tag class="endtag">varlistentry</tag>
+<tag class="endtag">variablelist</tag></programlisting>
+
+	<para>Appearance:</para>
+
+	<variablelist>
+	  <varlistentry>
+	    <term>Parallel</term>
+
+	    <listitem>
+	      <para>In parallel communications, groups of bits arrive
+		at the same time over multiple communications
+		channels.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>Serial</term>
+
+	    <listitem>
+	      <para>In serial communications, bits arrive one at a
+		time over a single communications channel.</para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+      </example>
+
+      <para>A <tag>procedure</tag> shows a series of
+	<tag>step</tag>s, which may in turn
+	consist of more <tag>step</tag>s or
+	<tag>substep</tag>s.  Each <tag>step</tag>
+	contains block elements.</para>
+
+      <example>
+	<title><tag>procedure</tag></title>
+
+	<para>Usage:</para>
+
+	<programlisting><tag class="starttag">procedure</tag>
+  <tag class="starttag">step</tag>
+    <tag class="starttag">para</tag>Do this.<tag class="endtag">para</tag>
+  <tag class="endtag">step</tag>
+
+  <tag class="starttag">step</tag>
+    <tag class="starttag">para</tag>Then do this.<tag class="endtag">para</tag>
+  <tag class="endtag">step</tag>
+
+  <tag class="starttag">step</tag>
+    <tag class="starttag">para</tag>And now do this.<tag class="endtag">para</tag>
+  <tag class="endtag">step</tag>
+<tag class="endtag">procedure</tag></programlisting>
+
+	<para>Appearance:</para>
 
 	<procedure>
 	  <step>