From f2d03744e75177c45f16aa25bb5c12503412533a Mon Sep 17 00:00:00 2001
From: Norman Walsh <ndw@nwalsh.com>
Date: Wed, 31 Jul 2024 12:15:24 +0100
Subject: [PATCH 1/2] Editorial pass on p:run

---
 step-run/src/main/xml/specification.xml | 120 +++++++++++++-----------
 1 file changed, 64 insertions(+), 56 deletions(-)

diff --git a/step-run/src/main/xml/specification.xml b/step-run/src/main/xml/specification.xml
index d056e5f..aa7e729 100644
--- a/step-run/src/main/xml/specification.xml
+++ b/step-run/src/main/xml/specification.xml
@@ -11,8 +11,8 @@
 <info>
 <title>XProc 3.0: dynamic pipeline execution</title>
 <!-- defaults to date formatted <pubdate>2014-12-18</pubdate> -->
-<copyright><year>2018</year><year>2019</year><year>2020</year>
-<holder>the Contributors to the XProc 3.0 Standard Step Library
+<copyright><year>2018</year><year>2019</year><year>2020</year><year>2024</year>
+<holder>the Contributors to the XProc 3.x Standard Step Library
 specifications</holder>
 </copyright>
 
@@ -157,60 +157,68 @@ invocation will fail, for example). Options that are provided by <tag>p:run-opti
 if the dynamically executed pipeline implicitly or explicitly declares a primary output port with 
 a different name than implicitly or explicitly specified in the <tag>p:run</tag> invocation.</error></para>
 
-    <section xml:id="example-run">
-      <title>Example</title>
-      <example xml:id="ex.c.run">
-        <title>Dynamic Execution of a Transformation/Validation Pipeline</title>
-        <programlisting language="xml">&lt;p:declare-step xmlns:p="http://www.w3.org/ns/xproc"
-  xmlns:c="http://www.w3.org/ns/xproc-step"
-  xmlns:xs="http://www.w3.org/2001/XMLSchema" version="3.0" 
-  name="sample-run-invocation">
-  &lt;p:variable name="xsl-params" select="map{'foo': 'bar'}" 
-    as="map(xs:QName, item()*)"/>
-  &lt;p:variable name="assert-valid" select="false()" as="xs:boolean"/>
-  &lt;p:variable name="mode" as="xs:QName?" select="()"/>
-  &lt;p:variable name="template" as="xs:QName?" select="()"/>
-  &lt;p:run name="runme">
-    &lt;p:with-input href="transform-n-validate.xpl"/>
-    &lt;p:run-option name="mode" select="$mode"/>
-    &lt;p:run-option name="template" select="$template"/>
-    &lt;p:run-option name="xslt-parameters" select="$xsl-params"/>
-    &lt;p:run-option name="assert-valid" select="$assert-valid"/>
-    &lt;p:run-input port="source" href="my.xml" primary="true"/>
-    &lt;p:run-input port="stylesheet" href="my.xsl"/>
-    &lt;p:run-input port="xsd" href="my.xsd"/>
-    &lt;p:output port="result" primary="true"/>
-    &lt;p:output port="report"/>
-  &lt;/p:run>
-&lt;/p:declare-step></programlisting>
-        <para>with this pipeline in <filename>transform-n-validate.xpl</filename>:</para>
-        <programlisting language="xml">&lt;p:declare-step xmlns:p="http://www.w3.org/ns/xproc"
-  xmlns:c="http://www.w3.org/ns/xproc-step"
-  xmlns:xs="http://www.w3.org/2001/XMLSchema" version="3.0" 
-  name="transform-n-validate">
-  &lt;p:input port="source" primary="true" sequence="true"/>
-  &lt;p:input port="stylesheet"/>
-  &lt;p:input port="xsd"/>
-  &lt;p:option name="assert-valid" as="xs:boolean" select="false()"/>
-  &lt;p:option name="xslt-parameters" as="map(xs:QName, item()*)?"/>
-  &lt;p:option name="mode" as="xs:QName?"/>
-  &lt;p:option name="template" as="xs:QName?"/>
-  &lt;p:output port="result" primary="true"/>
-  &lt;p:output port="report" pipe="report@xsdval"/>
-  &lt;p:xslt>
-    &lt;p:with-option name="initial-mode" select="$mode"/>
-    &lt;p:with-option name="template-name" select="$template"/>
-    &lt;p:with-option name="parameters" select="$xslt-parameters"/>
-    &lt;p:with-input port="stylesheet" pipe="stylesheet"/>
-  &lt;/p:xslt>
-  &lt;p:validate-with-xml-schema name="xsdval">
-    &lt;p:with-option name="assert-valid" select="$assert-valid"/>
-    &lt;p:with-input port="schema" pipe="xsd@transform-n-validate"/>
-  &lt;/p:validate-with-xml-schema>
-&lt;/p:declare-step></programlisting>
-      </example>
-      
-    </section>
+<section xml:id="example-run">
+<title>Example</title>
+
+<para>The following pipeline shows how <tag>p:run</tag> might be used.</para>
+
+<programlisting language="xml"><![CDATA[<p:declare-step xmlns:p="http://www.w3.org/ns/xproc"
+                xmlns:xs="http://www.w3.org/2001/XMLSchema"
+                version="3.0" 
+                name="sample-run-invocation">
+  <p:variable name="xsl-params" select="map{'foo': 'bar'}" 
+              as="map(xs:QName, item()*)"/>
+  <p:variable name="assert-valid" select="false()" as="xs:boolean"/>
+  <p:variable name="mode" as="xs:QName?" select="()"/>
+  <p:variable name="template" as="xs:QName?" select="()"/>
+
+  <p:run name="runme">
+    <p:with-input href="transform-n-validate.xpl"/>
+    <p:run-option name="mode" select="$mode"/>
+    <p:run-option name="template" select="$template"/>
+    <p:run-option name="xslt-parameters" select="$xsl-params"/>
+    <p:run-option name="assert-valid" select="$assert-valid"/>
+    <p:run-input port="source" href="my.xml" primary="true"/>
+    <p:run-input port="stylesheet" href="my.xsl"/>
+    <p:run-input port="xsd" href="my.xsd"/>
+    <p:output port="result" primary="true"/>
+    <p:output port="report"/>
+  </p:run>
+</p:declare-step>]]></programlisting>
+
+<para>With this pipeline in <filename>transform-n-validate.xpl</filename>, the preceding
+step has the effect of running the pipeline with the dynamically constructed options.</para>
+
+<programlisting language="xml"><![CDATA[<p:declare-step xmlns:p="http://www.w3.org/ns/xproc"
+                xmlns:xs="http://www.w3.org/2001/XMLSchema"
+                version="3.0" 
+                name="transform-n-validate">
+  <p:input port="source" primary="true" sequence="true"/>
+  <p:input port="stylesheet"/>
+  <p:input port="xsd"/>
+  <p:option name="assert-valid" as="xs:boolean" select="false()"/>
+  <p:option name="xslt-parameters" as="map(xs:QName, item()*)?"/>
+  <p:option name="mode" as="xs:QName?"/>
+  <p:option name="template" as="xs:QName?"/>
+  <p:output port="result" primary="true"/>
+  <p:output port="report" pipe="report@xsdval"/>
+
+  <p:xslt>
+    <p:with-option name="initial-mode" select="$mode"/>
+    <p:with-option name="template-name" select="$template"/>
+    <p:with-option name="parameters" select="$xslt-parameters"/>
+    <p:with-input port="stylesheet" pipe="stylesheet"/>
+  </p:xslt>
+
+  <p:validate-with-xml-schema name="xsdval">
+    <p:with-option name="assert-valid" select="$assert-valid"/>
+    <p:with-input port="schema" pipe="xsd@transform-n-validate"/>
+  </p:validate-with-xml-schema>
+</p:declare-step>]]></programlisting>
+
+<para>In practice, <tag>p:run</tag> might be more often used with dynamically constructed
+pipelines.</para>
+</section>
   
 <section>
 <title>Document properties</title>

From 5fa4e9242ea58de4afeb0936779c9bc6e6540894 Mon Sep 17 00:00:00 2001
From: Norman Walsh <ndw@nwalsh.com>
Date: Thu, 1 Aug 2024 09:00:32 +0100
Subject: [PATCH 2/2] There are no implementation-dependent features

---
 step-run/src/main/xml/conformance.xml | 7 -------
 1 file changed, 7 deletions(-)

diff --git a/step-run/src/main/xml/conformance.xml b/step-run/src/main/xml/conformance.xml
index 01035c8..13720e8 100644
--- a/step-run/src/main/xml/conformance.xml
+++ b/step-run/src/main/xml/conformance.xml
@@ -32,11 +32,4 @@ how <glossterm role='unwrapped'>implementation-defined</glossterm> features are
 <?implementation-defined-features?>
 </section>
 
-<section xml:id="implementation-dependent">
-<title>Implementation-dependent features</title>
-
-<para>The following features are implementation-dependent:</para>
-
-<?implementation-dependent-features?>
-</section>
 </appendix>