From 82e7bc62d3eeae2608768dda79d8a80e50fbf107 Mon Sep 17 00:00:00 2001
From: Norman Walsh <ndw@nwalsh.com>
Date: Wed, 31 Jul 2024 12:25:04 +0100
Subject: [PATCH] Editorial pass on file steps

---
 step-file/src/main/xml/specification.xml | 51 ++++++++++++++----------
 1 file changed, 31 insertions(+), 20 deletions(-)

diff --git a/step-file/src/main/xml/specification.xml b/step-file/src/main/xml/specification.xml
index f2a5005..455f53b 100644
--- a/step-file/src/main/xml/specification.xml
+++ b/step-file/src/main/xml/specification.xml
@@ -91,6 +91,9 @@ mechanisms.</para>
 access them, or they may be ignored by some or all steps.</para>
 </section>
 
+<section xml:id="library">
+<title>Step library</title>
+
   <section xml:id="c.directory-list">
     <title>p:directory-list</title>
     
@@ -175,12 +178,12 @@ access them, or they may be ignored by some or all steps.</para>
     included this way, none of their other entires are included unless they match
     an include filter.</para>
 
-    <example xml:id="ex.c.directory-list">
-      <title>Sample Directory List Output for a Single File</title>
-      <para>For a file <literal>a/a/b/file.txt</literal> below the initial directory 
-        <literal>/home/jane</literal>, this output will be produced, omitting content that might be present in the 
-        intermediate directories:</para>
-      <literallayout>&lt;c:directory xml:base="file:///home/jane/" name="jane">
+    <para>For a file <literal>a/a/b/file.txt</literal> below the initial
+    directory <literal>/home/jane</literal>, this output will be produced,
+    omitting content that might be present in the intermediate
+    directories:</para>
+
+      <programlisting language="xml">&lt;c:directory xml:base="file:///home/jane/" name="jane">
   &lt;c:directory xml:base="a/" name="a">
     &lt;c:directory xml:base="a/" name="a">
       &lt;c:directory xml:base="b/" name="b">
@@ -188,8 +191,8 @@ access them, or they may be ignored by some or all steps.</para>
       &lt;/c:directory>
     &lt;/c:directory>
   &lt;/c:directory>
-&lt;/c:directory></literallayout>
-    </example>
+&lt;/c:directory></programlisting>
+
     <para>If the <option>exclude-filter</option> pattern matches the slash-augmented relative path, the entry (and all of
       its content in case of a directory) is excluded in the output.</para>
     <para>If both options are
@@ -260,7 +263,7 @@ access them, or they may be ignored by some or all steps.</para>
       <tag>c:directory</tag>, it must end in a trailing slash. This way, users will always be able to compute the
       absolute URI for any of these elements by applying <code>fn:base-uri()</code> to it.</para>
     
-    <section xml:id="dir-list-details">
+    <simplesect xml:id="dir-list-details">
       <title>Directory list details</title>
       
       <para>If <option>detailed</option> is false, then only the
@@ -312,7 +315,7 @@ access them, or they may be ignored by some or all steps.</para>
       <para><impl>Any other attributes on
         <tag>c:file</tag>, <tag>c:directory</tag>, or <tag>c:other</tag>
         are <glossterm>implementation-defined</glossterm></impl>, but they <rfc2119>must</rfc2119> be in a namespace.</para>
-    </section>
+    </simplesect>
     
     <simplesect>
       <title>Document properties</title>
@@ -320,13 +323,6 @@ access them, or they may be ignored by some or all steps.</para>
         the resulting document has a <property>base-uri</property>. Its value is identical to the top-level
         element’s <tag class="attribute">xml:base</tag> attribute, that is, to the directory’s URI.</para>
     </simplesect>
-
-<simplesect>
-<title>Errata, April 2024</title>
-<para>Editorial clarifications. Fixed a grammatical error in the description of
-include filters. Improved the description of include filter processing.</para>
-</simplesect>
-
   </section>
   
   <section xml:id="c.file-copy">
@@ -389,7 +385,7 @@ include filters. Improved the description of include filter processing.</para>
     </listitem>
   </itemizedlist>
 
-  <section xml:id="recursive-copy">
+  <simplesect xml:id="recursive-copy">
     <title>Copying directories</title>
 
   <para>If <option>href</option> identifies a directory and
@@ -412,7 +408,7 @@ include filters. Improved the description of include filter processing.</para>
       </para>
     </listitem>
   </itemizedlist>
-  </section>
+  </simplesect>
 
   <simplesect>
     <title>Document properties</title>
@@ -553,8 +549,10 @@ include filters. Improved the description of include filter processing.</para>
   <para>The following attributes are standard on a returned <tag>c:file</tag> or <tag>c:directory</tag> element. All
     attributes are optional and must be absent if not applicable. Additional implementation-defined attributes may be
     present, but they must be in a namespace.</para>
-  <informaltable>
+  <informaltable pgwide="1">
     <tgroup cols="3">
+      <colspec colwidth="1in"/>
+      <colspec colwidth="1in"/>
       <thead>
         <row>
           <entry>Attribute</entry>
@@ -890,6 +888,7 @@ or exists and cannot be accessed.</error></para>
   apart from <property>content-type</property>. In particular, it has no <property>base-uri</property>.</para>
   </simplesect>
 </section>
+</section>
 
 <section xmlns="http://docbook.org/ns/docbook" xml:id="errors">
 <title>Step Errors</title>
@@ -941,6 +940,18 @@ failure causes the entire pipeline to fail.</para>
   </xi:fallback>
 </xi:include>
 
+<appendix xml:id="changelog">
+<title>Change log</title>
+
+<para>This appendix catalogs recent non-editorial changes.</para>
+
+<orderedlist>
+<listitem>
+<para>Improved the description of include filter processing in <tag>p:directory-list</tag>.</para>
+</listitem>
+</orderedlist>
+</appendix>
+
 <xi:include href="ancillary.xml"/>
 
 </specification>