Clarifications in comments

projects/usds-playbook-import/OSCAL-PLAYBOOK.xpl

@@ -3,12 +3,9 @@
    xmlns:ox="http://csrc.nist.gov/ns/oscal-xproc3" type="ox:OSCAL-PLAYBOOK" name="OSCAL-PLAYBOOK">
 
 
-   <!-- This pipeline delivers an error if the file designated in $source-html-file is not found -
-        Run the pipeline GRAB-PLAYBOOK.xpl to restore it. -->
-
-   <!-- Set an output port to see outputs in the console or to redirect them -->
-   <!--<p:output port="result" sequence="true"  serialization="map{ 'indent': true() }"
-   pipe="@snapshot"/>-->
+   <!-- This pipeline delivers errors if either of the files designated as
+        $source-html-file or $schema-file is not found -
+        Run pipelines GRAB-RESOURCES.xpl and GRAB-PLAYBOOK.xpl to restore them. -->
 
    <!-- subpipeline starts here -->
 

projects/usds-playbook-import/readme.md

@@ -22,24 +22,26 @@ Three pipelines share the load, mainly for transparency. A pipeline acquires and
 
 A single integrated pipeline would be straightforward -- and could avoid all local caching -- but harder to diagnose when the source data moves or disappears.
 
-### Pipeline [GRAB-PLAYBOOK.xpl](GRAB-PLAYBOOK.xpl)
-
-- Pulls a copy of the Digital Services Playbook (an HTML resource) from the Internet
-- [Saves it locally](archive/playbook-source.html) in the 'archive' folder
-
-This can be adapted to cache any page from the Internet.
-
 ### Pipeline [GRAB-RESOURCES.xpl](GRAB-RESOURCES.xpl)
 
 - Pulls a copy of the OSCAL XSD Schema
 - Stores it locally in `lib`
 
 You can skip this step if you wire [the next pipeline](OSCAL-PLAYBOOK.xpl) to find a schema at a different location, or skip OSCAL validation.
 
+### Pipeline [GRAB-PLAYBOOK.xpl](GRAB-PLAYBOOK.xpl)
+
+Run this pipeline only if you need to compare to or replace the provided copy.
+
+- Pulls a copy of the Digital Services Playbook (an HTML resource) from the Internet
+- [Saves it locally](archive/playbook-source.html) in the 'archive' folder
+
+This pipeline can be adapted to cache any page from the Internet. Use it responsibly!
+
 ### Pipeline [OSCAL-PLAYBOOK.xpl](OSCAL-PLAYBOOK.xpl)
 
-- Reads file cached in the last operation (with errors when it is missing)
-- Converts into clean semantic tagging (ad hoc)
+- Reads file cached in the last operation (producing an error when it is missing)
+- Converts into clean semantic tagging (ad hoc) using XSLT
 - Validates this against [a schema](src/playbook.rnc) that codifies expectations
 - Converts into an OSCAL catalog, with fresh timestamp and UUID
 - Validates as an OSCAL Catalog against the OSCAL XSD schema