Skip to content

Commit

Permalink
Misc adjustments and updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@wendellpiez
wendellpiez committed Aug 7, 2024
1 parent abe9b47 commit cea9160
Show file tree
Hide file tree
Showing 7 changed files with 137 additions and 92 deletions.
103 changes: 53 additions & 50 deletions tutorial/TUTORIAL-PAGE.xpl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,57 +57,60 @@

<p:wrap-sequence wrapper="sequence"/>

<p:group name="full-body">

<p:viewport match="c:file">
<p:variable name="path" select="/*/@path"/>
<p:variable name="project-uri" select="p:urify('.')"/>
<p:variable name="lesson-no" select="format-number(p:iteration-position(),'01')"/>
<!--<p:identity message="[PRODUCE-TUTORIAL-MARKDOWN] Loading {$path} "/>-->
<p:load href="{$path}" message="[TUTORIAL-PAGE] Loading {$path} "/>

<p:filter select="//body"/>
<p:add-attribute attribute-name="id"
attribute-value="{ substring-before($path,'_src.html') => replace('.*/','')}"/>
<p:add-attribute attribute-name="class" attribute-value="unit"/>
<p:rename match="body" new-name="section"/>
</p:viewport>

<p:add-attribute match="c:directory" attribute-name="class" attribute-value="lesson"/>
<p:delete match="@xml:base | c:directory/@name"/>
<p:rename match="body" new-name="section"/>
<p:rename match="c:directory" new-name="section"/>
<p:rename match="*:sequence" new-name="body"/>

<p:namespace-rename to="http://www.w3.org/1999/xhtml"/>
<p:namespace-delete prefixes="xsl ox c"/>

</p:group>

<p:viewport match="c:file">
<p:variable name="path" select="/*/@path"/>
<p:variable name="project-uri" select="p:urify('.')"/>
<p:variable name="lesson-no" select="format-number(p:iteration-position(),'01')"/>
<!--<p:identity message="[PRODUCE-TUTORIAL-MARKDOWN] Loading {$path} "/>-->
<p:load href="{$path}" message="[TUTORIAL-PAGE] Loading {$path} "/>

<p:filter select="//body" />
<p:add-attribute attribute-name="id" attribute-value="{ substring-before($path,'_src.html') => replace('.*/','')}" />
<p:add-attribute attribute-name="class" attribute-value="unit" />
<p:rename match="body" new-name="section" />
</p:viewport>

<p:add-attribute match="c:directory" attribute-name="class" attribute-value="lesson" />
<p:delete match="@xml:base | c:directory/@name"/>
<p:rename match="body" new-name="section" />
<p:rename match="c:directory" new-name="section" />
<p:rename match="*:sequence" new-name="body" />

<p:namespace-rename to="http://www.w3.org/1999/xhtml"/>
<p:namespace-delete prefixes="xsl ox c"/>

<p:identity name="full-body" />


<p:xslt>
<p:with-input port="stylesheet">
<p:inline expand-text="false">
<xsl:stylesheet version="3.0">
<xsl:mode on-no-match="shallow-copy"/>
<xsl:template match="p | pre | ul | ol | table | details" xpath-default-namespace="http://www.w3.org/1999/xhtml"/>
<xsl:template match="*:body">
<div class="toc">
<xsl:apply-templates/><!-- ... -->
</div>
</xsl:template>
<xsl:template match="*:section" expand-text="true">
<div>
<xsl:copy-of select="@*"/>
<xsl:apply-templates/>
</div>
</xsl:template>
</xsl:stylesheet>
</p:inline>
</p:with-input>
</p:xslt>

<p:delete match="@id"/>

<p:identity name="overview-div" />
<p:group name="overview-div">
<p:xslt>
<p:with-input port="stylesheet">
<p:inline expand-text="false">
<xsl:stylesheet version="3.0">
<xsl:mode on-no-match="shallow-copy"/>
<xsl:template match="p | pre | ul | ol | table | details"
xpath-default-namespace="http://www.w3.org/1999/xhtml"/>
<xsl:template match="*:body">
<div class="toc">
<xsl:apply-templates/>
<!-- ... -->
</div>
</xsl:template>
<xsl:template match="*:section" expand-text="true">
<div>
<xsl:copy-of select="@*"/>
<xsl:apply-templates/>
</div>
</xsl:template>
</xsl:stylesheet>
</p:inline>
</p:with-input>
</p:xslt>

<p:delete match="@id"/><!-- not getting attributes to match in my embedded XSLT ...? -->
</p:group>

<!-- Now having an 'overview' div albeit without links, we splice back in -->
<p:insert position="first-child">
Expand Down
24 changes: 22 additions & 2 deletions tutorial/source/oscal-convert/oscal-convert_101_src.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,9 @@ <h2>Resources</h2>
</section>
<section>
<h2>Step one: convert some OSCAL XML into OSCAL JSON</h2>
<p>Acquisition pipeline in the project folder collects some OSCAL onto the local system, where it can be
managed, easily inspected, controlled, and edited if necessary.</p>
<p><a href="../../../oscal-convert/GRAB-RESOURCES.xpl">An acquisition pipeline</a> in the project folder
collects some OSCAL onto the local system, where it can be managed, easily inspected, controlled, and edited
if necessary.</p>
<p>But sources and results from a conversion process do not always have to work with local resources. XProc
sees the Internet itself - whatever protocols are supported by the processor (the <code>file</code> and
<code>http</code> protocols are required for conformance) work as they do on the Worldwide Web. Of
Expand All @@ -48,6 +49,25 @@ <h2>Step one: convert some OSCAL XML into OSCAL JSON</h2>
<h2>Step two: return trip</h2>
<p>Two ways: separate pipeline; and single pipeline; also a 'switcher' pipeline?</p>
</section>
<section>
<h2>What is this XSLT?</h2>
<p>If your criticism of XProc so far is that it makes it look easy when it isn't, you have a point. Conversion
from XML to JSON isn't free, assuming it works at all. In this case, the heavy lifting is done by the XSLT
component - the Saxon engine invoked by the <code>p:xslt</code> step, applying logic defined in an XSLT
stylesheet (aka transformation) stored elsewhere. It happens that a converter for OSCAL data is available in
XSLT, so rather than having to confront this considerable problem ourselves, we drop that in.</p>
<p>In later units we will see how using the XProc steps described, rudimentary data manipulations can be done
using XProc by itself, without entailing the use of either XSLT or XQuery (another capability invoked with a
different step). At the same time, while pipelines are based on the idea of passing data through a series of
processes, there are many cases where logic is sufficiently complex that it becomes essential to maintain –
and test – that logic externally from the XProc. At what point it becomes more efficient to encapsulate
logic separately (whether by XSLT, XQuery or other means), depends very much on the case.</p>
<p>The <code>p:xslt</code> pipeline step in particular is so important for real-world uses of XProc that it is
introduced early, to show such black-box application. XProc also makes a fine environment for testing XSLT
developed or acquired to handle specific tasks, a topic covered in more depth later. Indeed XSLT and XQuery
being, like XProc itself, declarative languages, it makes sense to factor them out while maintaining easy
access and transparency for analysis and auditing purposes.</p>
</section>
<section>
<h2>What could possibly go wrong?</h2>
<p>When coping with errors, syntax errors are relatively easy. But anomalous inputs, especially invalid inputs,
Expand Down
4 changes: 2 additions & 2 deletions tutorial/source/setup/setup_101_src.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ <h2>Goals</h2>
</section>
<section>
<h2>Prerequisites</h2>
<p>You have Java installed with a JVM (Java Virtual Machine) available on the command line, version 8.0 and 11
(and later).</p>
<p>You have Java installed with a JVM (Java Virtual Machine) available on the command line (a JRE or JDK),
version 8 (and later).</p>
<p>You have a live Internet connection and the capability to download and save resources (binaries and code
libraries) for local use.</p>
<p><b>Tip:</b> check your Java version from the console using <code>java --version</code>.</p>
Expand Down
6 changes: 4 additions & 2 deletions tutorial/source/setup/setup_102_src.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,8 @@ <h1>102: Examining the setup</h1>
<section><h2>Goals</h2>
<ul>
<li>Look at some pipeline organization and syntax on the inside</li>
<li>Success and failure invoking XProc pipelines: an early chance to learn to die, fast and well</li>
<li>Success and failure invoking XProc pipelines: an early chance to “learn to die” gracefully (to use the
gamers' idiom).</li>
</ul>
</section>
<section><h2>Resources</h2>
Expand All @@ -18,7 +19,8 @@ <h1>102: Examining the setup</h1>
<section><h2>Prerequisites</h2>
<p>Please complete the repository setup and smoke tests as described in the <a href="setup_101_src.html">101 lesson</a>. In this lesson, we will run these pipelines with adjustments, or similar pipelines.</p>
<p>This discussion assumes basic knowledge of coding, the Internet (including retrieving resources via <code>file</code> and <code>http</code> protocols, and web-based technologies including HTML.</p>
<p>XML knowledge is also assumed, while at the same time we are interested to know where this gap needs to be filled.</p>
<p>XML knowledge is also assumed, while at the same time we are interested to know where this gap needs to be
filled.</p>
<p>You will also need a programmer's plain text editor, XML/XSLT editor or IDE (integrated development
environment) for more interactive testing of the code.</p>
</section>
Expand Down
Loading

0 comments on commit cea9160

Please sign in to comment.