Renaming the sequencing, with follow-on tasks

tutorial/PRODUCE-TUTORIAL-TOC.xpl

@@ -22,9 +22,10 @@
       <p:directory-list path="source/{ $lesson_key }" max-depth="unbounded" include-filter="_src\.html$"/>
       <p:add-attribute attribute-name="position" attribute-value="{p:iteration-position()}"/>      
 
+      <p:label-elements match="c:file" attribute="path" label="ancestor-or-self::*/@xml:base => string-join('')"/>
    <!-- is there a better way to annotate a directory list with full paths?
         or: make a step out of this and import it -->
-      <p:xslt>
+      <!--<p:xslt>
          <p:with-input port="stylesheet">
             <p:inline expand-text="false">
                <xsl:stylesheet version="3.0">
@@ -39,13 +40,16 @@
                </xsl:stylesheet>
             </p:inline>
          </p:with-input>
-      </p:xslt>
+      </p:xslt>-->
       <p:viewport match="c:file">
          <p:variable name="path" select="/*/@path"/>
          <p:load href="{$path}" message="[PRODUCE-TUTORIAL-TOC] Loading {$path}"/>
+         <p:variable name="track" select="/*/*/@data-track"/>
+
          <p:filter select="descendant::h1[1]"/>
          <p:rename new-name="file"/>
          <p:add-attribute attribute-name="href" attribute-value="{ replace($path,'.*/','') => replace('_src\.html$','.md') }"/>
+         <p:add-attribute attribute-name="track" attribute-value="{ $track }"/>
       </p:viewport>
    </p:for-each>
 
@@ -66,7 +70,7 @@
                </xsl:template>
                <xsl:template match="directory" expand-text="true">
                   <div>
-                     <h3>Lesson unit { format-number(@position,'01') }</h3>
+                     <h3>Lesson set { format-number(@position,'01') } - { @name }</h3>
                      <ul>
                         <xsl:apply-templates/>
                      </ul>
@@ -80,7 +84,8 @@
                <xsl:template match="file" mode="link">
                   <a href="Lesson{ format-number(parent::*/@position,'01') }/{@href}">
                      <xsl:apply-templates/>
-                  </a>
+                  </a>                  
+                  <xsl:text expand-text="true"> ({ upper-case(@track) })</xsl:text>
                </xsl:template>
             </xsl:stylesheet>
          </p:inline>

tutorial/lesson-plan.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <LESSON_PLAN>
-   <Lesson key="setup"/>
-   <Lesson key="unpack"/>            
+   <Lesson key="acquire"/>
+   <Lesson key="walkthrough"/>            
    <Lesson key="oscal-convert"/>
    <Lesson key="practicum"/>            
    <!--

tutorial/outline.md

@@ -68,6 +68,7 @@ For convenience, each lesson unit focuses on a project (as noted).
 
 ### Equipment
 
+
 You will be happy to have a developer's or data analyst's setup:
 
 - Command line with bash or Windows (cmd/Powershell)

tutorial/sequence/Lesson01/setup_101.md → tutorial/sequence/Lesson01/acquire_101.md

@@ -1,6 +1,6 @@
 
 
-> *Warning:* this Markdown file will be rewritten under continuous deployment (CD): edit the source in [/tutorial/source/setup/setup_101_src.html](../../../tutorial/source/setup/setup_101_src.html).
+> *Warning:* this Markdown file will be rewritten under continuous deployment (CD): edit the source in [/tutorial/source/acquire/acquire_101_src.html](../../../tutorial/source/acquire/acquire_101_src.html).
 > 
 > Save this file elsewhere to create a persistent copy (for example, for purposes of annotation).
 
@@ -67,12 +67,12 @@ Since almost any pipeline will use XSLT and since we do use the latest version (
 
 The top-level README and setup notes also describe testing your installation. Do this next.
 
-You know things are working in your XProc when either or both of two things are happening:
+You know things are working in your XProc when two things are happening:
 
 * On the console, notifications show up with reassuring messages announcing progress
-* When you expect files to be produced, they appear, or are updated, as expected
+* When you expect files to be produced for you, they appear, or are updated, as expected
 
-Both of those will occur with this lesson. The files produced by downloading scripts are written into the project `lib` directory, as documented. Refresh or restore by deleting the downloaded files and running the pipelines to acquire them again.
+Both of those will occur with this lesson. The files produced by downloading pipelines are written into the project `lib` directory, as documented. Refresh or restore by deleting the downloaded files and running the pipelines to acquire them again.
 
 Note: you need a live Internet connection for your `http` requests to go through.
 
@@ -82,13 +82,13 @@ When you can run all the smoke tests without ugly tracebacks, this lesson is com
 
 Within this project as a whole, and within its subprojects, everything is done with XProc 3.0, meaning everything can be done using a single script, which invokes an XProc processor to read and execute a pipeline. This simplicity is at the center of the argument for XProc. 
 
-Effectively (and much more could be said about the processing stack, dependency management and so forth) what this means is that XProc offers the user and the developer (in either or both roles) with focused and concentrated points of control or points of adjustment. In the field – where software is deployed and used – things almost never just “drop in”. User interfaces, APIs, dependencies and platform quirks: all these constrain what users can do, and even developers are rarely free to just mess around, as it might be thought of.
+Effectively (and much more could be said about the processing stack, dependency management and so forth) what this means is that XProc offers the user and the developer (in either or both roles) with focused and concentrated points of control or points of adjustment. In the field – where software is deployed and used – things almost never just “drop in”. User interfaces, APIs, dependencies and platform quirks: all these constrain what users can do, and even developers are rarely free to experiment and explore.
 
 To the extent this is the case, this project only works if things are actually simple enough to pick up, use, learn and adapt.
 
 `xp3.sh` and `xp3.bat` represent attempts at this. Each of them (on its execution platform) enables a user to run, without further configuration, the [Morgana XProcIIIse](https://www.xml-project.com/morganaxproc-iiise.html) processor on any XProc 3.0 pipeline, assuming the appropriate platform for each (`bash` in the case of the shell script, Windows batch command syntax for the `bat` file). Other platforms supporting Java (and hence Morgana with its libraries) could be provided with similar scripts.
 
-Such a script itself must be “vanilla” and generic: it simply invokes the processor with the designated pipeline, and stands back. The logic of operations is entirely encapsulated in the XProc pipeline designated. XProc 3.0 is both scalable and flexible enough to open a wide range of possibilities for data processing, both XML-based and using other formats such as JSON and plain text. It is the intent of this project not to explore and map this space – which is vast – but to show off enough XProc and related logic (XSLT, XSpec) to show how this exploration can be done. We are an outfitter at the beginning of what we hope will be a long and profitable voyage.
+Such a script itself must be “vanilla” and generic: it simply invokes the processor with the designated pipeline, and stands back. The logic of operations is entirely encapsulated in the XProc pipeline designated. XProc 3.0 is both scalable and flexible enough to open a wide range of possibilities for data processing, both XML-based and using other formats such as JSON and plain text. It is the intent of this project not to explore and map this space – which is vast – but to show off enough XProc and related logic (XSLT, XSpec) to show how this exploration can be done. We are an outfitter at the beginning of what we hope will be many profitable voyages to places we have never been.
 
 ### Tweaks
 

tutorial/sequence/Lesson01/setup_102.md → tutorial/sequence/Lesson01/acquire_102.md

@@ -1,6 +1,6 @@
 
 
-> *Warning:* this Markdown file will be rewritten under continuous deployment (CD): edit the source in [/tutorial/source/setup/setup_102_src.html](../../../tutorial/source/setup/setup_102_src.html).
+> *Warning:* this Markdown file will be rewritten under continuous deployment (CD): edit the source in [/tutorial/source/acquire/acquire_102_src.html](../../../tutorial/source/acquire/acquire_102_src.html).
 > 
 > Save this file elsewhere to create a persistent copy (for example, for purposes of annotation).
 
@@ -33,20 +33,20 @@ The key to understanding both groups is to know that once the initial [Setup
 
 Specifically, the pipelines can acquire resources from the Internet, save them locally, and perform unarchiving (unzipping). Having been downloaded, each library provides software that the pipeline engine (Morgana) can use to do more.
 
-Accordingly, the first group of pipelines (in the [lib](../../../lib/readme.md) directory has a single purpose, namely (together and separately) to download software for Morgana.
+Accordingly, the first group of pipelines (in the [lib](../../../lib/readme.md) directory has a single purpose, namely (together and separately) to download software to augment Morgana's feature set.
 
 * [lib/GRAB-SAXON.xpl](../../../lib/GRAB-SAXON.xpl)
 * [lib/GRAB-SCHXSLT.xpl](../../../lib/GRAB-SCHXSLT.xpl)
 * [lib/GRAB-XSPEC.xpl](../../../lib/GRAB-XSPEC.xpl)
 
-The second group of pipelines also has a single purpose, namely to exercise and test the capabilities provided by the software downloaded by the first group.
+Pipelines in a second group work similarly in that each one exercises and tests capabilities provided by software downloaded by a member of the first group.
 
 * [smoketest/TEST-XPROC3.xpl](../../../smoketest/TEST-XPROC3.xpl) tests MorganaXProc-III
 * [smoketest/TEST-XSLT.xpl](../../../smoketest/TEST-XSLT.xpl) tests Saxon
 * [smoketest/TEST-SCHEMATRON.xpl](../../../smoketest/TEST-SCHEMATRON.xpl) tests SchXSLT
 * [smoketest/TEST-XSPEC.xpl](../../../smoketest/TEST-XSPEC.xpl) tests XSpec
 
-Take a look at these files. It may be helpful to envision the XML syntax as a set of nested frames with labels and connectors.
+Take a look at these files. It may be helpful (for those getting used to it) to envision the XML syntax as a set of nested frames with labels and connectors.
 
 Try more than one way of looking at the XProc source code: in the Github repository, on your file system, in a plain text editor, in an XML editor.
 

tutorial/sequence/Lesson01/setup_599.md → tutorial/sequence/Lesson01/acquire_599.md

@@ -1,6 +1,6 @@
 
 
-> *Warning:* this Markdown file will be rewritten under continuous deployment (CD): edit the source in [/tutorial/source/setup/setup_599_src.html](../../../tutorial/source/setup/setup_599_src.html).
+> *Warning:* this Markdown file will be rewritten under continuous deployment (CD): edit the source in [/tutorial/source/acquire/acquire_599_src.html](../../../tutorial/source/acquire/acquire_599_src.html).
 > 
 > Save this file elsewhere to create a persistent copy (for example, for purposes of annotation).
 
@@ -15,3 +15,11 @@ MorganaXProc-III is implemented in Scala, and Saxon is built in Java, but otherw
 Which is it, and what are the determining variables that tell you XProc is a good fit? How much of this is due to the high-level, abstracted nature of [4GLs](https://en.wikipedia.org/wiki/Fourth-generation_programming_language) including both XSLT 3.1 and XProc 3.0? Prior experience with XML-based systems and the problem domains in which they work well is probably a factor. How much are the impediments technical, and how much are they due to culture?
 
 The next lesson unit includes more information on where to learn about XProc and how to become familiar not only with its uses in connection with OSCAL, but in general.
+
+## Declarative markup in action
+
+Considerable care is taken in developing these demonstrations to see to it that the technologies on which we depend, notably XProc and XSLT but not limited to these, are both nominally and actually conformant to externally specified standard technologies, i.e. XProc and XSLT respectively (as well as others), and reliant to the greatest possible extent on well-documented and accessible runtimes.
+
+It is a tall order to ask that any code base should be both easy to integrate and use with others, and at the same time, functionally complete and self-sufficient. Of these two, we are lucky to get one. Because the world is complex, we are always throwing in one or another new dependency, along with new rule sets. Here, we work by making everything transparent as possible (so nothing is downloaded behind the scenes, for example) while also documenting as thoroughly as we can, including with code comments.
+
+Can any code base be self-explanatory in any meaningful sense? Doubtful. But one can try and leave tracks and markers, at least.