Rearranging project resources, with tutorial updates

testing/xproc3-house-rules.sch

@@ -87,6 +87,8 @@
    <sch:let name="resource-fileset-path" value="( (tokenize($fileset-relPath,'/')  [position() ne last()] ! '../') => string-join('') ) || $resource-repoPath"/>
    <sch:let name="fileset-resource-path" value="( (tokenize($resource-repoPath,'/')[position() ne last()] ! '../') => string-join('') ) || $fileset-relPath"/>
 
+   <sch:let name="okay-ns-prefixes" value="'','p','c','ox','xml','xsl','x','xs','html','svrl','xvrl','cprt'"/>
+
    <sch:pattern>
       <sch:rule context="/*">
          <!--<sch:report test="false()">
@@ -100,7 +102,7 @@
          </sch:report>-->
 
          <sch:assert sqf:fix="sqf-exempt-from-houserules-check" role="warning" test="base-uri(.) = $listed-uris or exists(p:documentation[contains(.,'HALL PASS') and contains(.,'HOUSE RULES')])">file <sch:value-of select="$filename"/> isn't listed in validation set maintained in <sch:value-of select="$fileset-resource-path"/> - should it be?</sch:assert>
-         <sch:let name="unexpected-prefixes" value="in-scope-prefixes(.)[not(.=('','p','c','ox','xml','xsl','x','xs','html','svrl','xvrl'))]"/>
+         <sch:let name="unexpected-prefixes" value="in-scope-prefixes(.)[not(.=$okay-ns-prefixes)]"/>
          <sch:report test="$unexpected-prefixes => exists()">This repo is keeping a list of recognized namespace prefixes, which does not include <sch:value-of select="$unexpected-prefixes => string-join(', ')"/></sch:report>
          <sch:assert sqf:fix="sqf-make-version-3"   test="@version = '3.0'">Expecting XProc 3.0, not <sch:value-of select="@version"/></sch:assert>
       </sch:rule>

tutorial/source/oscal-convert/oscal-convert_350_src.html

@@ -50,5 +50,21 @@ <h2>Namespace fixup and namespace cleanup steps</h2>
             is a common remedy for <em>inflamed namespaces</em>, a condition that happens to XML that has been handled
             recklessly by too many handlers with too many namespaces. Also, <code>p:namespace-rename</code>.</p>
       </section>
+      <section>
+         <h2>Namespace tips and tricks XXX</h2>
+         <section>
+            <h3>Coining new namespaces</h3>
+         </section>
+         <section>
+            <h3>On-the-fly namespace declarations</h3>
+         </section>
+         <section>
+            <h3>Overloading prefixes</h3>
+         </section>
+         <section>
+            <h3>Matching with namespace wildcard</h3>
+            <p>For example, <code>match="*:p"</code> will match any <code>p</code> element in any namespace.</p>
+         </section>
+      </section>
    </body>
 </html>

tutorial/source/walkthrough/walkthrough_101_src.html

@@ -85,7 +85,7 @@ <h2>A closer look</h2>
          <ul>
             <li><a href="../../../smoketest/TEST-XPROC3.xpl">smoketest/TEST-XPROC3.xpl</a> amounts to an XProc <q>Hello
                   World</q>. In that spirit, feel free to write your own version. (You get another chance to do this <a
-                  href="walkthrough_102_src.html">real soon now</a>.)</li>
+                  href="walkthrough_102_src.html" class="LessonUnit">real soon now</a>.)</li>
             <li><a href="../../../smoketest/TEST-XSLT.xpl">smoketest/TEST-XSLT.xpl</a> tests Saxon, an XSLT/XQuery
                transformation engine. XSLT and XQuery are related technologies (different languages, same data model)
                developed with XML processing in mind, but in recent years generalized to a wider range of data
@@ -151,7 +151,7 @@ <h3>TEST-XSLT</h3>
                results in the console. This time the result is not just the XML given in the pipeline, but that XML as
                modified by the transformation.</p>
             <p>If your pipeline execution can't process the XSLT (perhaps Saxon is not installed, or the XSLT itself has
-               a problem) you will get an error to say so.</p>
+               a problem) you will get an error saying so.</p>
             <p>Errors in XProc are reported by the Morgana engine using XML syntax. Among other things, this means they
                can be captured and processed in pipelines.</p>
          </section>
@@ -212,25 +212,28 @@ <h2>A not-so-simple pipeline</h2>
             predictable interface.</p>
          <p>Next, take a look at a more complex example, the prototype pipeline <a
                href="../../PRODUCE-PROJECTS-ELEMENTLIST.xpl">PRODUCE-PROJECTS-ELEMENTLIST.xpl</a>. Like the setup and
-            smoke-test pipelines, this is a standalone pipeline: when this plan (<q>step</q> or pipeline) is executed,
-            the processor will acquires inputs, produce results and write those results to the file system. The output
-            it generates is stored as <a href="../../sequence/element-directory.md">element-directory.md</a>, a Markdown
-            file (find the <code>p:store</code> step).</p>
-         <p>The result is a reference resource encoded in Markdown: an index of XProc elements used in pipelines
-            described in this tutorial, which can be reposted back into the repository or viewed with any Markdown
+            smoke-test pipelines, this is a standalone pipeline (requiring no runtime bindings or settings): when this
+            plan (<q>step</q> or pipeline) is executed, the processor will acquires inputs, produce results and write
+            those results to the file system. The output it generates is stored as <a
+               href="../../sequence/element-directory.md">element-directory.md</a>, a Markdown file (find the
+               <code>p:store</code> step).</p>
+         <p>The result is a reference resource encoded in Markdown: an index of XProc elements used in pipelines in this
+            repository. As Markdown, this result can be reposted back into the repository or viewed with any Markdown
             viewing application. The index lists XProc elements, that is the core of the XProc vocabulary: for any XProc
-            element used anywhere, the listing shows the pipelines where it appears. Following the index, the resource
-            also shows a list of (repository) project folders in an order corresponding to their treatment (if any) in
-            this tutorial, with their XProc files and whatever XProc elements appear <i>first</i> (within the entire
-            sequence up to to point) within that file. Among other uses this is helpful for assessing coverage of
-            lessons.</p>
+            element used anywhere among the projects listed, the listing shows the pipelines where it appears. Following
+            the index, the resource also shows a list of (repository) project folders in a prescribed order, with their
+            XProc files and whatever XProc elements appear <i>first</i> (within the entire sequence up to to point)
+            within that file. Among other uses this is helpful for assessing coverage of tutorial lessons as it offers a
+            (semi) <i>ordered</i> survey of the elements.</p>
          <p>For example, looking up <code>p:store</code> you can see all the pipelines that contain this common step. Or
-            looking at the <code>oscal-convert</code> listing you can see the XProc steps introduced in that lesson.</p>
-         <p>Delete or rename this result file and run the pipeline to confirm it functions properly.</p>
+            looking at the <code>oscal-convert</code> listing you can see the XProc steps appearing first in that
+            project folder.</p>
+         <p>To confirm proper functioning, run the pipeline again after deleting or renaming the Markdown result
+            file.</p>
          <p>Consider also what other kinds of indexing might be useful. When you modify XProc or add new XProc pipelines
             to the project folders, consider running this pipeline again to update the indexes.</p>
          <p>Open the file and inspect it to get a sense of how it works. The XML syntax is verbose, but not really all
-            that frightening. The pipeline is described in more detail in the <a href="walkthrough_102_src.html"
+            that frightening. Practice helps! The pipeline is also considered in the <a href="walkthrough_102_src.html"
                class="LessonUnit">102 Lesson unit</a> segment.</p>
          <section>
             <h3>PRODUCE-PROJECTS-ELEMENTLIST</h3>
@@ -248,11 +251,11 @@ <h3>PRODUCE-PROJECTS-ELEMENTLIST</h3>
                   produced in this second analytical phase, showing how once the files are surveyed, more than one
                   analysis is possible.</li>
                <li>In particular, the index to <q>first use</q> is not simple. A great deal of the complexity of
-                  detailed operations has been off loaded into XSLT transformation code, which in this pipeline can be
+                  detailed operations has been off-loaded into XSLT transformation code, which in this pipeline can be
                   seen embedded in the XProc, indeed occupying the greater part of the XML in the file. (About two
-                  thirds of the element count: you can usually recognize XSLT by the conventional <code>xsl:</code> or
-                     <code>xslt:</code> element prefix.) This pipeline also has an XSLT (at the end) called from an
-                  external file, toward the end. XProc can do it either way, and each has its advantages.</li>
+                  thirds of the element count: you can usually recognize XSLT by the conventional <code>xsl:</code>
+                  element prefix.) This pipeline also has an XSLT called from an external file (toward the end). XProc
+                  can provide XSLT either way, and each has its advantages.</li>
                <li>One good thing about seeing the XSLT here is you can get a good sense of what it looks like, whether
                   embedded or kept externally. XSLT is <a href="walkthrough_401_src.html" class="LessonUnit">not
                      essential to XProc</a>, but it very much expands its practical capabilities.</li>

tutorial/source/walkthrough/walkthrough_401_src.html

@@ -53,33 +53,31 @@ <h2>XSLT: XSL (XML Stylesheet Language) Transformations</h2>
             model is both broadly applicable, and workable in a range of environments including client software or
             within encapsulated, secure software configurations and deployments.</p>
          <p>If your XSLT is strong enough, you don't need XProc, or not much. But as a functional language, XSLT is best
-            used in a functionally pure way that does not interact with the system: no <q>side effects</q>. This is
-            related to its definitions of conformant processing (X inputs produce Y outputs) and the determinism, based
-            in mathematical formalisms, that underlies this idea of conformance. However one cost of mathematical purity
-            is that operations that do interact with stateful externalities – things such as reading and writing files –
-            are not in XSLT's <q>comfort zone</q>. It easily defines what a new structure A' should look like for any
-            given structure A. But how A is first acquired or what we do once we have determined A', is less clear, and
-            left up to the processor to handle, as an interface, starting with an XSLT transformation's nominal
-               <em>source</em> and (primary) <em>result</em>. Often, this gap has been bridged by extended functionality
-            provided by leading processors. Does your processor read and parse XML files off the file system? Can it be
-            connected to upstream processes in different ways? Can it use HTTP <code>GET</code> and <code>PUT</code>?
-            The answer may be Yes to any or all of these. Throughout its history, XSLT in later versions was also
-            extended in this direction, with features such as the <code>collection()</code> function,
-               <code>xsl:result-document</code>, <code>doc-available()</code> and other features we don't need if we are
-            using XProc.</p>
-         <p>Then too, XSLT is commonly run from scripts, in web hosting environments, and indeed from XQuery. Or you
-            might be able to configure your desktop software (Editor or IDE) to run your XSLT, or indeed acquire
-            specialized software just for reading and filtering collections or managing sets of file outputs in
-            XSLT-based workflows.</p>
-         <p>It is difficult not to think, however, that a gentler approach is also possible to the range of problems
-            related to making XSLT accessible in any environment – one that offers the feature set and flexibility we
-            need, but with less overhead, especially with regard to routine chores like designating sets of inputs and
+            used in a functionally pure, <q>stateless</q> way that does not interact with the system: no <q>side
+               effects</q>. This is related to its definitions of conformant processing (X inputs produce Y outputs) and
+            the determinism, based in mathematical formalisms, that underlies its idea of conformance. However one cost
+            of mathematical purity is that operations that do interact with stateful externalities – things such as
+            reading and writing files – are not in XSLT's <q>comfort zone</q>. It easily defines what a new structure A'
+            should look like for any given structure A. But how A is first acquired or what we do once we have
+            determined A', is less clear, and left up to the processor to handle, as an interface, starting with an XSLT
+            transformation's nominal <em>source</em> and (primary) <em>result</em>. Often, this gap has been bridged by
+            extended functionality in processors. Does your processor read and parse XML files off the file system? Can
+            it be connected to upstream data producers in different ways? Can it use HTTP <code>GET</code> and
+               <code>PUT</code>? The answer may be Yes to any or all of these. Throughout its history, XSLT in later
+            versions was also extended in this direction, with features such as the <code>collection()</code> function,
+               <code>xsl:result-document</code>, <code>doc-available()</code> and other features we may not need if we
+            are using XProc.</p>
+         <p>XSLT is commonly run from scripts, in web hosting environments and XQuery databases. Or you might be able to
+            configure your desktop software (Editor or IDE) to run your XSLT, or acquire specialized software just for
+            reading and filtering collections or managing sets of file outputs in XSLT-based workflows.</p>
+         <p>Yet XProc may offer a gentler approach, while it enables XSLT on the one hand when needed, while on the
+            other enables us largely to do without it, offering both a useful feature set and the flexibility we need,
+            but with less overhead, especially with regard to routine chores like designating sets of inputs and
             outputs, or sequencing operations. The principle of Least Power may well apply here: it saves our present
             and our future selves effort if we can arrange and manage to do things less. XProc lets us do less.</p>
-         <p>XProc lets us use XSLT when we must, but also keeps routine and simple things both simple and consistent,
-            without requiring much overhead. But it adapts itself well to new requirements as they become more
-            complicated. Ultimately, it spares the XSLT developer the problem of having to design, build and test
-            something like XProc.</p>
+         <p>XProc lets us use XSLT when we must, but also keeps routine and simple things both simple and consistent.
+            And it adapts itself well to new requirements as they become more complicated. Ultimately, it spares the
+            XSLT developer the problem of having to design, build and test something like XProc.</p>
          <section>
             <h3>Running XSLT without XProc</h3>
             <p>As a standard and an externally-specified technology, XSLT can in principle be implemented on any
@@ -91,6 +89,21 @@ <h3>Running XSLT without XProc</h3>
             <p>Download and run Saxon to apply XSLT to XML and other inputs, without XProc.</p>
          </section>
       </section>
+      <section>
+         <h2>Using XSLT in XProc: avoiding annoyances XXX</h2>
+         <p>If you are an experienced XSLT user, congratulations! The power XProc puts into your hands is everything you
+            might think and hope.</p>
+         <p>There are a couple of small but potentially annoying considerations when embedding XSLT literals in your
+            XProc code. They do not apply when your XSLT is called from out of line, acquired by binding to an input
+            port or even <code>p:load</code>. If you acquire and even manipulate your XSLT without including literal
+            XSLT code in your XProc, that eliminates the syntax-level clashes at the roots of both these problems.</p>
+         <section>
+            <h3>Text and attribute value syntax in embedded XSLT</h3>
+         </section>
+         <section>
+            <h3>Namespaces in and for your XSLT</h3>
+         </section>
+      </section>
       <section>
          <h2>Learning XSLT the safer way</h2>
          <p>If setting out to learn XSLT, pause to read the following list of things to which you should give early