Update docs and samples

doc/guide/appendices/cli-v1vsv2.xml

@@ -26,7 +26,7 @@
     </p>
 
     <listing xml:id="listing-v1-manifest">
-      <caption>Example of version 1 project manifest</caption>
+      <title>Example of version 1 project manifest</title>
     <program language="xml">
       <input>
       <![CDATA[
@@ -74,7 +74,7 @@
     </listing>
 
     <listing xml:id="listing-v2-manifest">
-      <caption>Example of version 2 project manifest</caption>
+      <title>Example of version 2 project manifest</title>
     <program language="xml">
       <input>
       <![CDATA[
@@ -117,7 +117,7 @@
     </p>
 
     <listing xml:id="listing-v2-manifest-simple">
-      <caption>Simplified project manifest in version 2 format</caption>
+      <title>Simplified project manifest in version 2 format</title>
     <program language="xml">
       <input>
       <![CDATA[

doc/guide/appendices/editors.xml

@@ -267,7 +267,7 @@
         <p>Configuration is achieved via a <q>hidden</q> file at the top of your home directory, namely <c>.aspell.conf</c>.  A Mac will try to keep you away from hidden files, which are the ones whose name begins with a period.  Let SublimeText give you an assist here.  In <xref ref="aspell-configuration"/> we show a first run at a useful configuration file.  You <em>definitely</em> want to add the <init>SGML</init> filter, since this is what tells Aspell that you are working on <init>XML</init> files<fn><init>SGML</init> is the precursor of <init>XML</init>.</fn>, so that all element names, attributes, etc. will not be checked.  The remainder is a suggested list of <pretext/> elements to skip.  Suggestions for additions are welcome here.</p>
 
         <listing xml:id="aspell-configuration">
-            <caption>Aspell Configuration File</caption>
+            <title>Aspell Configuration File</title>
 
             <program>
                 <input>

doc/guide/author/processing.xml

@@ -377,7 +377,7 @@
             </p>
 
             <listing xml:id="cli-project-manifest-example">
-                <caption>Example of a very simple project manifest.</caption>
+                <title>Example of a very simple project manifest.</title>
             <program language="xml">
                 <input>
                 <![CDATA[
@@ -561,7 +561,7 @@
             </p>
 
             <listing xml:id="listing-v2-executables">
-                <caption>Example of version 2 executables file</caption>
+                <title>Example of version 2 executables file</title>
                 <program language="xml">
                   <input>
                   <![CDATA[

doc/guide/author/topics.xml

@@ -2311,7 +2311,7 @@ displayed line, and there are no <c>\\</c>s.  Use <c>\amp</c> to mark the alignm
                         ]]>
                         </input>
                     </program>
-                    <caption>Possible structures for using <tag>mathcmp</tag> within a <tag>test</tag>. The <tag>de-expression</tag> would be replaced by any valid construction as described for the <tag>setup</tag>.</caption>
+                    <title>Possible structures for using <tag>mathcmp</tag> within a <tag>test</tag>. The <tag>de-expression</tag> would be replaced by any valid construction as described for the <tag>setup</tag>.</title>
                 </listing>
 
                 <p>Compound logical structures are created using the <tag>logic</tag> element in the place of a comparison. To specify which operation is being used, the <attr>op</attr> attribute is set to one of <attr>op="and"</attr>, <attr>op="or"</attr>, or <attr>op="not"</attr>. The operations are considered <m>n</m>-ary, meaning that the contents should be one or more comparison elements, which might include additional logic. The <attr>op="and"</attr> will evaluate as true when <em>all</em> of the children comparisons evaluate as true. The <attr>op="or"</attr> will evaluate as true when <em>at least one</em> of the children comparisons evaluates as true. The <attr>op="not"</attr> is technically implemented as the negation of <attr>op="and"</attr>, and so will evaluate as true when <em>at least one</em> of the children comparisons evaluates as <em>false</em>. In the absence of any <tag>logic</tag>, there is always an implicit <attr>op="and"</attr> so that any sequence of comparisons within a single <tag>test</tag>, all comparisons are required to evaluate as true.</p>
@@ -3442,7 +3442,7 @@ displayed line, and there are no <c>\\</c>s.  Use <c>\amp</c> to mark the alignm
 
             <p>A <tag>console</tag> is a transcript of an interactive session in a terminal or console at a command-line.  It is a sequence of the following elements, in this order, possibly repeated many times as a group: <tag>input</tag>, and <tag>output</tag>.  The <tag>output</tag> is optional.  The content of these two elements is treated as verbatim text (see <xref ref="overview-verbatim-literal"/>), subject to all the exceptions for exceptional characters (see <xref ref="overview-exceptional-characters"/>).  A <attr>prompt</attr> attribute on the <tag>input</tag> can be supplied to provide a system prompt distinct from the actual commands.  The default prompt is a dollar sign followed by a space.  If it is more convenient <attr>prompt</attr> may be supplied on the <tag>console</tag>, to be used in each enclosed <tag>input</tag>.  If you do not want any prompts at all, just use an empty value for <attr>prompt</attr>.</p>
 
-            <p>A <tag>program</tag> or <tag>console</tag> may be wrapped in a <tag>listing</tag>, see <xref ref="topic-listing"/>.  This will behave similar to a <tag>figure</tag>, with the <tag>caption</tag> displayed below, and a number assigned.  So, in particular, if your program or console is important enough to cross-reference, it is an enclosing <tag>listing</tag> that serves as the target.</p>
+            <p>A <tag>program</tag> or <tag>console</tag> may be wrapped in a <tag>listing</tag>, see <xref ref="topic-listing"/>.  This will behave similar to a <tag>figure</tag>, with the <tag>title</tag> displayed above, and a number assigned.  So, in particular, if your program or console is important enough to cross-reference, it is an enclosing <tag>listing</tag> that serves as the target.</p>
 
             <p>The <attr>language</attr> attribute may be used to get some degree of language-specific syntax highlighting and/or interactive behavior.  We will eventually provide a table of attribute values here.  They are always lowercase, and a good first guess is likely to succeed.</p>
 
@@ -3921,7 +3921,7 @@ displayed line, and there are no <c>\\</c>s.  Use <c>\amp</c> to mark the alignm
 
     <section xml:id="topic-listing">
         <title>Program Listings</title>
-        <p>A <tag>listing</tag> is really a specialized type of <tag>figure</tag>, whose purpose is to hold computer code.  Just like a figure, it has a <tag>caption</tag> and <tag>title</tag> which behave identically.  However, the enclosed planar content is limited to a <tag>program</tag> or <tag>console</tag> (see <xref ref="topic-program-console"/>).</p>
+        <p>A <tag>listing</tag> is really a specialized type of <tag>figure</tag>, whose purpose is to hold computer code.  It has an optional <tag>title</tag> which is rendered above the listing.  However, the enclosed planar content is limited to a <tag>program</tag> or <tag>console</tag> (see <xref ref="topic-program-console"/>).</p>
     </section>
 
     <section xml:id="topic-named-list">