Many tutorial draft improvements #23

wendellpiez · 2025-01-03T20:01:42Z

Committer Notes

Many glitches in exposition corrected, with some polishing.

Responding to @galm feedback (thanks!)

All Submissions:

Follow Contributing guidelines
Make no changes duplicating or conflicting with other open Pull Requests
Pass all CI/CD checks

Changes to Core Features:

The Issue history, discussions and new documentation provide context for new features -- everything is reasonably self-explanatory and linked
New tests and examples are included
File listings have been updated for validation and XSpec under CI/CD
Readme and TESTING documents have been updated

github-actions · 2025-01-03T20:02:57Z

XSpec Test Results

18 tests ±0 18 ✅ ±0 0s ⏱️ ±0s
7 suites ±0 0 💤 ±0
4 files ±0 0 ❌ ±0

Results for commit fb80add. ± Comparison against base commit bb76ea1.

♻️ This comment has been updated with latest results.

… namespaces.

wendellpiez · 2025-01-31T16:10:43Z

The tutorial is still very much a draft publication thanks!

wendellpiez · 2025-01-31T17:36:34Z

NB this commit includes some HTML XProc 'sketches' i.e. XProc step declarations rendered via HTML grids into 'stepwise' patterns.

For example: https://html-preview.github.io/?url=https://github.com/usnistgov/oscal-xproc3/blob/18e785550ad45bf964458483db026ed0d9ca8ec3/projects/xproc-doc/sketches/PROVE-XSD-VALIDATIONS-sketch.html

This is a sketch of the PROVE-XSD-VALIDATIONS pipeline in the repository.

This doesn't yet show the connections between steps - I'm thinking about that.

galtm

I didn't look at all the files in this large PR, but I looked at the files where you were responding to my feedback. Thanks! I'll try to look at some of the new material, too, but whenever you are otherwise ready to merge this PR, don't wait for me.

galtm · 2025-01-31T16:33:30Z

TESTING.md


-Additional ideas:
+Files to be tested using Schematron or XSpec executable are listed in the FILESET pipelines:


Great. This is a good place to mention the FILESET pipelines.

galtm · 2025-01-31T16:36:54Z

projects/oscal-import/USArmy_FM6-22/OSCAL-WEBPUB_FM_6-22.xpl

+
+   <p:store href="www/FM_6-22-fulltext.html" serialization="map{ 'method': 'html' }" message="[OSCAL-WEBPUB_FM_6-22] p:store: www/FM_6-22-fulltext.html ..."/>
+
+   <!-- implicit p:sink as we start with new source port -->


Useful comment

galtm · 2025-01-31T16:43:54Z

projects/oscal-import/USDS-2024_Playbook/GRAB-RESOURCES.xpl

+      <!-- NB - A Schematron error comes back as soon as this is out of line with /*/@type i.e. the file name
+           - starting the @message with { $prefix } silences the error, but please reset $prefix -->


I don't understand this comment. What does it mean to reset $prefix?

galtm · 2025-01-31T16:50:49Z

setup-xmlcalabash.sh

+VERSION=3.0.0-alpha14
+RELEASES=https://github.com/xmlcalabash/xmlcalabash3/releases/download
+
+# Acquiring, for example, https://github.com/xmlcalabash/xmlcalabash3/releases/download/3.0.0-alpha9/xmlcalabash-3.0.0-alpha5.zip


I know this is just an example, but I think you meant to make the alpha numbers the same instead of 9 vs. 5.

galtm · 2025-01-31T16:55:30Z

tutorial/readme.md

@@ -59,7 +59,7 @@ If for any reason you can't run XProc or Java, post us an Issue and the dev team

 ### Observer Track

-For everyone including the "hands off" researchers including subject experts, managers and programmers who want to see how XProc works and understand its capabilities, without planning to develop XProc pipelines or write code.
+This track is for everyone but most especially for researchers including subject experts, managers and developers who want to see how XProc works and understand its capabilities, but who do not plan to build XProc pipelines or write code. Maybe you need to understand it so you can help develop and test against requirements.


I like the new sentence you added at the end.

galtm · 2025-01-31T16:57:05Z

tutorial/readme.md

-The biggest challenge to developers coming to XProc will often be in how much XML, XPath, XQuery, or XSLT do you know. Even developers who have no prior exposure to the XML stack should be able to use the Maker track to test and develop skills. Those who do have prior experience will, it is hoped, find it to be an accelerant, while XProc itself is a launchpad. It should be possible to start from zero.
+XProc is intimately tied to XML (syntax), XDM (data model), XPath (for queries and pattern-matching) and a host of related 'X' technologies developed over decades at W3C and elsewhere. Those who have prior experience with XML and XSLT will find much that is familiar along with what is new, but even developers who are not XML specialists should be able to use the Maker track to test and develop skills. If XML is the rocket, your data is the fuel and XProc is the launchpad. It should be possible to start from zero, and with a model rocket.

-The expectation is that unlike Observers, Makers will be interested in tracebacks and error messages - and will wish sometimes to produce them deliberately - if only out of curiosity and need-to-know. As a Maker, you are confident that you can put things back well enough or that any damage is well contained.
+The expectation is that unlike Observers, Makers will be interested in tracebacks and error messages, and will wish sometimes to produce them deliberately if only to see what happens. As a Maker, you are confident that you can put things back well enough or that any damage is well contained.


Nice changes here.

galtm · 2025-01-31T17:01:52Z

tutorial/sequence/Lesson01/acquire_102.md

@@ -25,15 +25,25 @@ You will also need a programmer's plain text editor, XML/XSLT editor or IDE (int

 Same as [Setup 101](acquire_101.md).

+Also see [the set of XProc worksheets](../../worksheets/) collected so far for this tutorial.
+
+## Step Zero: XProc steps


This new step zero is great! It clarifies things that were so mysterious to me when I looked at XProc code before learning the mental model.

galtm · 2025-01-31T17:03:16Z

tutorial/sequence/Lesson01/acquire_599.md

-Because it is now centered on *pipelines* built out of combining capabilities of *steps* (which may be black boxes), as much as on files and software packages, dependency management when using XProc is different from other technologies including Java and NodeJS – how so?
+Dependency management when using XProc is different from other technologies including Java and Javascript/NodeJS – how so? Because it is now centered on *pipelines* built out of combining capabilities of *steps* (which may be black boxes), as much as on files and software packages. Arguably, XProc blurs the distinction between code you write, and libraries you use, in a useful way – while presenting its own challenges.


Clearer now.

wendellpiez · 2025-01-31T21:08:17Z

Thanks for the quick feedback @galtm, see next commit.

Many improvements responding to galtm feedback (thanks!)

0af5455

wendellpiez changed the title ~~Many improvements~~ Many tutorial draft improvements Jan 3, 2025

wendellpiez added 27 commits January 3, 2025 15:10

Missed one.

2b84988

Addresses usnistgov#22

2cdd898

Adding XML Calabash scripting for testing

eb8338a

Improving runtime processor report XPL

e8df93a

Reverting to XML Calabash version alpha9, for now

d67ce73

Further touchups for XML Calabash

24bd7bf

Further touchups

a86606d

Further XML Calabash alignment

1799339

Further touchup to PROCESSOR-REPORT.xpl

1cf072a

Several improvements and enhancements to tutorial segments

cf4981e

Relaxed naming rule on locally defined pipelines

2aea7c6

Small US Digital Service Playbook conversion to OSCAL (demo)

93fff63

Small update

9de1a60

More updates to USDS Playbook import

597374a

Playbook conversion improvements; lesson mods to tutorial coverage of…

ce6b501

… namespaces.

Clarifications in comments

3ab7d80

More touchups; providing missing file for CI/CD

6baa5dd

Further touchups and comments

c979b4d

Further touchups and commenting/clarification

ec14419

WIP on next tutorial lesson sequence

8d31440

Tightening some XProc

ee7e39b

Sketching XProc as HTML Grid

6a40e9f

Adding resources

fe9d074

More stuff including edits and new resources

dc1e6de

Projects renamed and grouped more intelligibly.

76c5ee8

Fixing broken links in Schematron testing of pipelines

6825c9f

More reorganization including renaming for clarity

9ff635a

wendellpiez added 2 commits January 30, 2025 16:33

Added tutorial on OSCAL import from raw data; misc updates

cf017d1

Repairing a whitespace glitch in Markdown

18e7855

wendellpiez requested review from iMichaela and galtm January 31, 2025 16:08

galtm approved these changes Jan 31, 2025

View reviewed changes

Small updates and improvements

fb80add

wendellpiez merged commit 0038caf into usnistgov:main Jan 31, 2025
3 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Many tutorial draft improvements #23

Many tutorial draft improvements #23

wendellpiez commented Jan 3, 2025

github-actions bot commented Jan 3, 2025 •

edited

Loading

wendellpiez commented Jan 31, 2025 •

edited

Loading

wendellpiez commented Jan 31, 2025 •

edited

Loading

galtm left a comment

galtm Jan 31, 2025

galtm Jan 31, 2025

galtm Jan 31, 2025

galtm Jan 31, 2025

galtm Jan 31, 2025

galtm Jan 31, 2025

galtm Jan 31, 2025

galtm Jan 31, 2025

wendellpiez commented Jan 31, 2025


		Additional ideas:
		Files to be tested using Schematron or XSpec executable are listed in the FILESET pipelines:


		<p:store href="www/FM_6-22-fulltext.html" serialization="map{ 'method': 'html' }" message="[OSCAL-WEBPUB_FM_6-22] p:store: www/FM_6-22-fulltext.html ..."/>

		<!-- implicit p:sink as we start with new source port -->

		<!-- NB - A Schematron error comes back as soon as this is out of line with /*/@type i.e. the file name
		- starting the @message with { $prefix } silences the error, but please reset $prefix -->

		Because it is now centered on pipelines built out of combining capabilities of steps (which may be black boxes), as much as on files and software packages, dependency management when using XProc is different from other technologies including Java and NodeJS – how so?
		Dependency management when using XProc is different from other technologies including Java and Javascript/NodeJS – how so? Because it is now centered on pipelines built out of combining capabilities of steps (which may be black boxes), as much as on files and software packages. Arguably, XProc blurs the distinction between code you write, and libraries you use, in a useful way – while presenting its own challenges.

Many tutorial draft improvements #23

Many tutorial draft improvements #23

Conversation

wendellpiez commented Jan 3, 2025

Committer Notes

All Submissions:

Changes to Core Features:

github-actions bot commented Jan 3, 2025 • edited Loading

XSpec Test Results

wendellpiez commented Jan 31, 2025 • edited Loading

wendellpiez commented Jan 31, 2025 • edited Loading

galtm left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wendellpiez commented Jan 31, 2025

github-actions bot commented Jan 3, 2025 •

edited

Loading

wendellpiez commented Jan 31, 2025 •

edited

Loading

wendellpiez commented Jan 31, 2025 •

edited

Loading