@pretextbook/pretext-html 0.3.0 → 0.4.0

package/assets/xsl/pretext-jupyter.xsl

@@ -28,7 +28,9 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
     xmlns:exsl="http://exslt.org/common"
     xmlns:str="http://exslt.org/strings"
+    xmlns:pi="http://pretextbook.org/2020/pretext/internal"
     extension-element-prefixes="exsl str"
+    exclude-result-prefixes="pi"
     >
 
 <!-- Trade on HTML markup, numbering, chunking, etc.        -->
@@ -36,8 +38,13 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 <!-- NB: this will import -assembly and -common stylesheets -->
 <xsl:import href="./pretext-html.xsl" />
 
-<!-- Output is JSON, enriched with serialized HTML -->
-<xsl:output method="text" />
+<!-- Output is an XML description of a notebook: a "notebook"     -->
+<!-- element containing a flat list of "cell" elements, whose      -->
+<!-- content is serialized HTML (markdown cells) or program text  -->
+<!-- (code cells).  The Python routine  jupyter()  converts each   -->
+<!-- such file into the JSON of a Jupyter notebook via "nbformat", -->
+<!-- which owns all JSON escaping and schema conformance.          -->
+<xsl:output method="xml" encoding="UTF-8" />
 
 <!-- ######### -->
 <!-- Variables -->
@@ -54,8 +61,6 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 <!-- iPython files as output -->
 <xsl:variable name="file-extension" select="'.ipynb'" />
 
-<xsl:param name="jupyter.kernel" select="''" />
-
 <!-- Disable clipboardable -->
 <xsl:template name="insert-clipboardable-class"/>
 
@@ -122,7 +127,12 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 <!-- We have entire cells for division headings. -->
 <xsl:template match="&STRUCTURAL;" mode="pretext-heading">
     <xsl:variable name="html-rtf">
-        <xsl:apply-templates select="." mode="section-heading" />
+        <!-- each division heads its own notebook, and the document -->
+        <!-- title is a level below the notebook's styling cell, so -->
+        <!-- level 2 mirrors the HTML conversion's chunked pages    -->
+        <xsl:apply-templates select="." mode="section-heading">
+            <xsl:with-param name="heading-level" select="2"/>
+        </xsl:apply-templates>
     </xsl:variable>
     <xsl:variable name="html-node-set" select="exsl:node-set($html-rtf)" />
     <xsl:call-template name="pretext-cell">
@@ -136,7 +146,10 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 
 <xsl:template match="paragraphs|introduction|conclusion" mode="pretext-heading">
     <xsl:variable name="html-rtf">
-        <xsl:apply-templates select="." mode="heading-title" />
+        <!-- a level below a division heading (see above) -->
+        <xsl:apply-templates select="." mode="heading-title">
+            <xsl:with-param name="heading-level" select="3"/>
+        </xsl:apply-templates>
     </xsl:variable>
     <xsl:variable name="html-node-set" select="exsl:node-set($html-rtf)" />
     <xsl:call-template name="pretext-cell">
@@ -149,7 +162,32 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 </xsl:template>
 
 <xsl:template match="*" mode="pretext-heading">
-    <xsl:message>pretext-heading unmatched <xsl:value-of select="local-name(.)" /></xsl:message>
+    <xsl:message>PTX:BUG: pretext-heading unmatched <xsl:value-of select="local-name(.)" /></xsl:message>
+</xsl:template>
+
+<!-- A division companion as its own notebook: a heading cell from -->
+<!-- the localized type-name (titles ignored, pending deprecation) -->
+<!-- and then the children as cells                                -->
+<xsl:template match="introduction|conclusion" mode="division-companion-page">
+    <xsl:variable name="html-rtf">
+        <h1>
+            <xsl:apply-templates select="." mode="division-companion-text"/>
+        </h1>
+    </xsl:variable>
+    <xsl:variable name="html-node-set" select="exsl:node-set($html-rtf)" />
+    <xsl:call-template name="pretext-cell">
+        <xsl:with-param name="content">
+            <xsl:call-template name="begin-string" />
+                <xsl:apply-templates select="$html-node-set" mode="xml-to-string" />
+            <xsl:call-template name="end-string" />
+        </xsl:with-param>
+    </xsl:call-template>
+    <xsl:apply-templates select="*"/>
+</xsl:template>
+
+<!-- The ordinary block realization is the whole notebook -->
+<xsl:template match="objectives|outcomes" mode="division-companion-page">
+    <xsl:apply-templates select="."/>
 </xsl:template>
 
 <!-- Three modal templates accomodate all document structure nodes -->
@@ -165,7 +203,6 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
         <xsl:with-param name="content">
             <!-- should perhaps initialize/pass $heading-level = 2 here -->
             <!-- perhaps irrelevant since headings are done in markown? -->
-            <xsl:apply-templates select="objectives|introduction" />
             <xsl:variable name="html-rtf">
                 <nav class="summary-links">
                     <xsl:apply-templates select="*" mode="summary-nav" />
@@ -192,8 +229,9 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 <!-- to adjust the page-oriented flavor of the base HTML (which exists   -->
 <!-- as part of accommodating printing from a web browser). All children  -->
 <!-- of a "page" get processed, and elsewhere get recognized as items    -->
-<!-- deserving of their own cells.                                       -->
-<xsl:template match="worksheet/page">
+<!-- deserving of their own cells.  A "handout" structures its content   -->
+<!-- with "page" identically.                                            -->
+<xsl:template match="worksheet/page|handout/page">
     <xsl:apply-templates select="*"/>
 </xsl:template>
 
@@ -228,122 +266,94 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
         <!-- the real content of the page -->
         <xsl:copy-of select="$content" />
     </xsl:variable>
-    <exsl:document href="{$the-filename}" method="text">
-        <!-- <xsl:call-template name="converter-blurb-html" /> -->
-        <!-- begin outermost group -->
-        <xsl:text>{&#xa;</xsl:text>
-        <!-- cell list first, majority of notebook, metadata to finish -->
-        <xsl:text>"cells": [&#xa;</xsl:text>
-        <!-- Escape JSON strings now, be sure later adjustments -->
-        <!-- conform to JSON syntax in this regard              -->
-        <xsl:variable name="escaped-cell-list">
-            <xsl:call-template name="escape-json-string">
-                <xsl:with-param name="text" select="$cell-list"/>
-            </xsl:call-template>
-        </xsl:variable>
-        <!-- Multiple strings in a cell are merged into one by    -->
-        <!-- combining adjoining end/begin pairs, leaving only    -->
-        <!-- leading and trailing delimiters (next substitution). -->
-        <!-- This is one solution of the problem of $n-1$         -->
-        <!-- separators for $n$ items.                            -->
-        <xsl:variable name="split-strings" select="str:replace($escaped-cell-list, $ESBS, '')" />
-        <xsl:variable name="finalize-strings" select="str:replace(str:replace($split-strings, $ES, '&quot;'), $BS, '&quot;')" />
-        <!-- The only pseudo-markup left is that of the two types -->
-        <!-- of cells possible in a Jupyter notebook.  We split   -->
-        <!-- just the adjacent brackets with comma-newline, so    -->
-        <!-- source has each cell entirely on its own line.  This -->
-        <!-- is the other solution of the problem of $n-1$        -->
-        <!-- separators for $n$ items.                            -->
-        <xsl:variable name="split-cells" select="str:replace($finalize-strings, $RBLB, $RBLB-comma)" />
-        <!-- Now we consider the actual markers and replace   -->
-        <!-- with the JSON that Jupyter expects as source.    -->
-        <!-- We are done, so "value-of" is good enough,       -->
-        <!-- rather than having a final $code-cells.  The     -->
-        <!-- four *-wrap variables here are just conveniences -->
-        <xsl:variable name="markdown-cells" select="str:replace(str:replace($split-cells, $BM, $begin-markdown-wrap), $EM, $end-markdown-wrap)" />
-        <xsl:value-of select="str:replace(str:replace($markdown-cells, $BC, $begin-code-wrap), $EC, $end-code-wrap)" />
-        <!-- end cell list -->
-        <xsl:text>&#xa;],&#xa;</xsl:text>
-        <!-- version identifiers -->
-        <xsl:text>"nbformat": 4, "nbformat_minor": 0, </xsl:text>
-        <!-- metadata copied from blank SMC notebook -->
-        <xsl:text>"metadata": {</xsl:text>
-        <xsl:text>"kernelspec": {</xsl:text>
-        <!-- TODO: configure kernel in "docinfo" -->
-        <!-- "display_name" seems ineffective, but is required -->
-        <xsl:text>"display_name": "", </xsl:text>
-        <!-- TODO: language not needed? -->
-        <!-- <xsl:text>"language": "python", </xsl:text> -->
-        <!-- TODO: make kernelspec configurable? -->
-        <!-- <xsl:text>"name": "python2"</xsl:text> -->
-        <!-- "sagemath" as  "name" will be latest kernel -->
-        <!-- in Sage distribution Jupyter, and in CoCalc -->
-        <xsl:choose>
-            <xsl:when test="contains('|python3|Python3|python 3|Python 3|py|Py|python|Python|'
-                , concat('|', $jupyter.kernel, '|'))">
-                <xsl:text>"name": "python3"</xsl:text>
-            </xsl:when>
-            <xsl:otherwise>
-                <xsl:text>"name": "sagemath"</xsl:text>
-            </xsl:otherwise>
-        </xsl:choose>
-        <!-- TODO: how much of the following is necessary before loading? -->
-        <xsl:text>}, </xsl:text>
-        <xsl:text>"language_info": {</xsl:text>
-        <xsl:text>"codemirror_mode": {</xsl:text>
-        <xsl:text>"name": "ipython", </xsl:text>
-        <xsl:text>"version": 3</xsl:text>
-        <xsl:text>}, </xsl:text>
-        <xsl:text>"file_extension": ".py", </xsl:text>
-        <xsl:text>"mimetype": "text/x-python", </xsl:text>
-        <xsl:text>"name": "python", </xsl:text>
-        <xsl:text>"nbconvert_exporter": "python", </xsl:text>
-        <xsl:text>"pygments_lexer": "ipython3", </xsl:text>
-        <xsl:text>"version": "3.6.4"</xsl:text>
-        <xsl:text>}, </xsl:text>
-        <xsl:text>"name": "</xsl:text>
-        <xsl:value-of select="$the-filename" />
-        <xsl:text>"</xsl:text>
-        <xsl:text>}&#xa;</xsl:text>
-        <!-- end outermost group -->
-        <xsl:text>}</xsl:text>
+    <!-- The file written here is the *description* of a notebook,  -->
+    <!-- so an "xml" suffix is appended to the eventual notebook    -->
+    <!-- filename.  Hyperlinks within cell content are relative     -->
+    <!-- references to the final "ipynb" filenames, so the Python   -->
+    <!-- conversion must strip the suffix when writing final files. -->
+    <exsl:document href="{$the-filename}.xml" method="xml" encoding="UTF-8">
+        <notebook>
+            <!-- The kernel comes from the publication file (with a       -->
+            <!-- deprecated stringparam honored), and is communicated to  -->
+            <!-- the Python routine, which owns all remaining             -->
+            <!-- notebook-level metadata.                                 -->
+            <xsl:attribute name="kernel">
+                <xsl:value-of select="$jupyter-kernel"/>
+            </xsl:attribute>
+            <xsl:copy-of select="$cell-list"/>
+        </notebook>
     </exsl:document>
 </xsl:template>
 
 <!-- a code cell with HTML magic         -->
 <!-- allows reader to activate styling   -->
 <!-- Code first, so it begins with focus -->
+<!-- The styling is deliberately self-contained: no network      -->
+<!-- requests (a reader's activity is nobody's business), no     -->
+<!-- scripts (host applications routinely remove them), and no   -->
+<!-- colors that fight a host application's light or dark theme. -->
+<!-- The notebook is fully readable if this cell is never run:   -->
+<!-- styling is a progressive enhancement, never structural.     -->
 <xsl:template name="load-css">
     <!-- HTML as one-off code cell   -->
     <!-- Serialize HTML by hand here -->
     <xsl:call-template name="code-cell">
+        <xsl:with-param name="purpose" select="'styling'"/>
         <xsl:with-param name="content">
             <xsl:call-template name="begin-string" />
             <xsl:text>%%html&#xa;</xsl:text>
-            <!-- for offline testing -->
-            <!-- <xsl:text>&lt;link href="./mathbook-content.css" rel="stylesheet" type="text/css" /&gt;&#xa;</xsl:text> -->
-            <xsl:text>&lt;link href="https://pretextbook.org/beta/mathbook-content.css" rel="stylesheet" type="text/css" /&gt;&#xa;</xsl:text>
-            <xsl:text>&lt;link href="https://aimath.org/mathbook/mathbook-add-on.css" rel="stylesheet" type="text/css" /&gt;&#xa;</xsl:text>
-            <!-- A bad hack since "subtitle" is in masthead code, better CSS should take care of this -->
-            <xsl:if test="$document-root/subtitle">
-                <xsl:text>&lt;style&gt;.subtitle {font-size:medium; display:block}&lt;/style&gt;&#xa;</xsl:text>
-            </xsl:if>
-            <xsl:text>&lt;link href="https://fonts.googleapis.com/css?family=Open+Sans:400,400italic,600,600italic" rel="stylesheet" type="text/css" /&gt;&#xa;</xsl:text>
-            <xsl:text>&lt;link href="https://fonts.googleapis.com/css?family=Inconsolata:400,700&amp;subset=latin,latin-ext" rel="stylesheet" type="text/css" /&gt;</xsl:text>
-            <!-- Cell hider is unwrapped from some notebook display command that injects HTML: -->
-            <!-- https://nbviewer.jupyter.org/github/shashi/ijulia-notebooks/blob/master/funcgeo/Functional%20Geometry.ipynb -->
-            <xsl:text>&lt;!-- Hide this cell. --&gt;&#xa;</xsl:text>
-            <xsl:text>&lt;script&gt;&#xa;</xsl:text>
-            <xsl:text>var cell = $(".container .cell").eq(0), ia = cell.find(".input_area")&#xa;</xsl:text>
-            <xsl:text>if (cell.find(".toggle-button").length == 0) {&#xa;</xsl:text>
-            <xsl:text>ia.after(&#xa;</xsl:text>
-            <xsl:text>    $('&lt;button class="toggle-button"&gt;Toggle hidden code&lt;/button&gt;').click(&#xa;</xsl:text>
-            <xsl:text>        function (){ ia.toggle() }&#xa;</xsl:text>
-            <xsl:text>        )&#xa;</xsl:text>
-            <xsl:text>    )&#xa;</xsl:text>
-            <xsl:text>ia.hide()&#xa;</xsl:text>
-            <xsl:text>}&#xa;</xsl:text>
-            <xsl:text>&lt;/script&gt;&#xa;</xsl:text>
+            <xsl:text>&lt;style&gt;&#xa;</xsl:text>
+            <xsl:text>.mathbook-content {line-height: 1.4;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content .heading {margin-bottom: 0.5em;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content article .heading {font-size: 1em; margin: 0 0 0.5em;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content code.code-inline {padding: 0 0.2em; border: 0.05em solid #bbbbbb; border-radius: 0.2em;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content .heading .codenumber {margin-left: 0.25em;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content .heading .title {margin-left: 0.25em; font-style: italic;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content .subtitle {font-size: medium; display: block; font-weight: normal;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content article {border-left: 0.15em solid #888888; padding-left: 0.75em; margin: 0.75em 0;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content article .para:last-child {margin-bottom: 0;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content article.proof {border-left: 0.1em dotted #888888;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content article.fragment-first {margin-bottom: 0;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content article.fragment-interior, .mathbook-content article.fragment-last {margin-top: 0;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content .para {margin-top: 0.75em;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content pre.code-display {border: 0.05em solid #888888; padding: 0.5em; overflow-x: auto;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content figure {margin: 1em auto; text-align: center;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content .image-box {margin-left: auto; margin-right: auto;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content img.contained {width: 100%;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content figcaption {font-style: italic; margin-top: 0.25em;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content figcaption .type, .mathbook-content figcaption .codenumber {font-style: normal; font-weight: bold;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content .summary-links li {list-style: none;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content .summary-links a {display: block; margin: 0.5em 0; padding: 0.6em 0.9em; border: 0.05em solid #888888; border-radius: 0.5em; font-size: 1.2em; font-weight: bold; text-decoration: none;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content .summary-links a .codenumber {margin-right: 0.5em;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content .sbsrow {display: grid; grid-template-columns: repeat(auto-fit, minmax(0, 1fr)); column-gap: 3%; align-items: start;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content .sbspanel.middle, .mathbook-content .sbspanel--middle {align-self: center;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content .sbspanel.bottom, .mathbook-content .sbspanel--bottom {align-self: end;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content table {border-collapse: collapse;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content table td, .mathbook-content table th {padding: 0.2em 0.5em; border: 0 solid;}&#xa;</xsl:text>
+            <!-- host themes stripe and highlight table rows; authored -->
+            <!-- tables speak through their rules, never backgrounds.  -->
+            <!-- The full "background" shorthand, explicit alternating -->
+            <!-- selectors, and !important outrank any host theme.     -->
+            <xsl:text>.mathbook-content table tr, .mathbook-content table td, .mathbook-content table th {background: transparent !important;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content table tbody tr:nth-child(odd), .mathbook-content table tbody tr:nth-child(even), .mathbook-content table tbody tr:hover {background: transparent !important;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content td.t1, .mathbook-content th.t1 {border-top-width: 1px;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content td.t2, .mathbook-content th.t2 {border-top-width: 2px;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content td.t3, .mathbook-content th.t3 {border-top-width: 3px;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content td.b1, .mathbook-content th.b1 {border-bottom-width: 1px;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content td.b2, .mathbook-content th.b2 {border-bottom-width: 2px;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content td.b3, .mathbook-content th.b3 {border-bottom-width: 3px;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content td.l1, .mathbook-content th.l1 {border-left-width: 1px;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content td.l2, .mathbook-content th.l2 {border-left-width: 2px;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content td.l3, .mathbook-content th.l3 {border-left-width: 3px;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content td.r1, .mathbook-content th.r1 {border-right-width: 1px;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content td.r2, .mathbook-content th.r2 {border-right-width: 2px;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content td.r3, .mathbook-content th.r3 {border-right-width: 3px;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content td.l {text-align: left;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content td.c {text-align: center;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content td.r {text-align: right;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content table tr.header-vertical th {writing-mode: vertical-rl; padding-left: 2em;}&#xa;</xsl:text>
+            <xsl:text>.mathbook-content .sbspanel img {max-width: 100%;}&#xa;</xsl:text>
+            <xsl:text>&lt;/style&gt;</xsl:text>
             <xsl:call-template name="end-string" />
         </xsl:with-param>
     </xsl:call-template>
@@ -352,7 +362,7 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
     <xsl:call-template name="markdown-cell">
         <xsl:with-param name="content">
             <xsl:call-template name="begin-string" />
-            <xsl:text>**Important:** to view this notebook properly you will need to execute the cell above, which assumes you have an Internet connection.  It should already be selected, or place your cursor anywhere above to select.  Then press the "Run" button in the menu bar above (the right-pointing arrowhead), or press Shift-Enter on your keyboard.</xsl:text>
+            <xsl:text>The collapsed code cell above adds some light styling, and in a trusted notebook it takes effect automatically.  If this page looks plain, run that cell once, with Shift-Enter or a Run button.  Everything below is fully readable either way, and nothing here requires an Internet connection.</xsl:text>
             <xsl:call-template name="end-string" />
         </xsl:with-param>
     </xsl:call-template>
@@ -376,6 +386,12 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
                     <xsl:value-of select="$latex-packages-mathjax" />
                     <!-- Sequence replacements if \gt and/or \amp need to go -->
                     <xsl:value-of select="str:replace($latex-macros,'\newcommand{\lt}{&lt;}&#xa;', '')"/>
+                    <!-- "math support" macros, mirroring the base HTML template -->
+                    <xsl:call-template name="fillin-math"/>
+                    <!-- legacy built-in support for "slanted|beveled|nice" fractions -->
+                    <xsl:if test="$b-has-sfrac">
+                        <xsl:text>\newcommand{\sfrac}[2]{{#1}/{#2}}&#xa;</xsl:text>
+                    </xsl:if>
                 </xsl:with-param>
             </xsl:call-template>
             <xsl:call-template name="end-string" />
@@ -383,6 +399,33 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
     </xsl:call-template>
 </xsl:template>
 
+<!-- An override of the template in pretext-common.xsl.  The        -->
+<!-- publisher's "shade" style needs \definecolor and \colorbox,    -->
+<!-- from a MathJax extension a notebook's configuration does not   -->
+<!-- load (and we cannot touch); an unknown macro renders literally -->
+<!-- as mathematics.  So "shade" degrades to the visually closest   -->
+<!-- style, "box", which is core TeX throughout.  The "underline"   -->
+<!-- style is also safe, and is reproduced verbatim.                -->
+<xsl:template name="fillin-math">
+    <xsl:choose>
+        <xsl:when test="$fillin-math-style = 'underline'">
+            <xsl:text>\newcommand{\fillinmath}[1]{\mathchoice</xsl:text>
+            <xsl:text>{\underline{\displaystyle     \phantom{\ \,#1\ \,}}}</xsl:text>
+            <xsl:text>{\underline{\textstyle        \phantom{\ \,#1\ \,}}}</xsl:text>
+            <xsl:text>{\underline{\scriptstyle      \phantom{\ \,#1\ \,}}}</xsl:text>
+            <xsl:text>{\underline{\scriptscriptstyle\phantom{\ \,#1\ \,}}}}&#xa;</xsl:text>
+        </xsl:when>
+        <!-- "box", and "shade" degraded to "box" -->
+        <xsl:otherwise>
+            <xsl:text>\newcommand{\fillinmath}[1]{\mathchoice</xsl:text>
+            <xsl:text>{\boxed{\displaystyle     \phantom{\,#1\,}}}</xsl:text>
+            <xsl:text>{\boxed{\textstyle        \phantom{\,#1\,}}}</xsl:text>
+            <xsl:text>{\boxed{\scriptstyle      \phantom{\,#1\,}}}</xsl:text>
+            <xsl:text>{\boxed{\scriptscriptstyle\phantom{\,#1\,}}}}&#xa;</xsl:text>
+        </xsl:otherwise>
+    </xsl:choose>
+</xsl:template>
+
 
 <!-- ################# -->
 <!-- Block Level Items -->
@@ -405,19 +448,239 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 <!-- TODO: remove filter on paragraphs once we add stack for sidebyside -->
 <xsl:template match="*[parent::*[&STRUCTURAL-FILTER; or self::paragraphs[not(ancestor::sidebyside)] or self::introduction[parent::*[&STRUCTURAL-FILTER;]] or self::conclusion[parent::*[&STRUCTURAL-FILTER;]]]]|*[parent::page]" priority="-0.5">
     <!-- <xsl:message>G:<xsl:value-of select="local-name(.)" />:G</xsl:message> -->
-    <xsl:variable name="html-rtf">
-        <xsl:apply-imports />
+    <xsl:choose>
+        <!-- A block with executable "sage" anywhere within it cannot -->
+        <!-- be one markdown cell: the code deserves genuine,         -->
+        <!-- executable code cells.  Since cells never nest, the      -->
+        <!-- block splits into *fragments* around its code: each      -->
+        <!-- fragment is a complete, balanced rendering, and any      -->
+        <!-- element spanning a split (the block itself, a            -->
+        <!-- "statement", a "task") is re-opened in the next          -->
+        <!-- fragment.  A fragment-position class lets styling draw   -->
+        <!-- continuity (side borders) across the cells, and cell     -->
+        <!-- metadata records the same structure durably.             -->
+        <xsl:when test=".//sage[not(@type = 'display')]">
+            <!-- NB: "apply-imports" honors the current mode, so the -->
+            <!-- rendering must happen here, in the default mode     -->
+            <xsl:variable name="html-rtf">
+                <xsl:apply-imports/>
+            </xsl:variable>
+            <xsl:call-template name="fragmented-block">
+                <xsl:with-param name="rendered" select="$html-rtf"/>
+            </xsl:call-template>
+        </xsl:when>
+        <xsl:otherwise>
+            <xsl:variable name="html-rtf">
+                <xsl:apply-imports />
+            </xsl:variable>
+            <xsl:variable name="demoted-rtf">
+                <xsl:apply-templates select="exsl:node-set($html-rtf)" mode="demote-headings"/>
+            </xsl:variable>
+            <xsl:variable name="html-node-set" select="exsl:node-set($demoted-rtf)" />
+            <xsl:call-template name="pretext-cell">
+                <xsl:with-param name="content">
+                    <xsl:call-template name="begin-string" />
+                        <xsl:apply-templates select="$html-node-set" mode="xml-to-string" />
+                    <xsl:call-template name="end-string" />
+                </xsl:with-param>
+            </xsl:call-template>
+        </xsl:otherwise>
+    </xsl:choose>
+</xsl:template>
+
+<!-- The HTML conversion threads a heading level to every block's  -->
+<!-- heading, but "xsl:apply-imports" (necessary above, to reuse   -->
+<!-- the entire HTML conversion for a block) cannot pass           -->
+<!-- parameters, an XSLT 1.0 limitation.  So every block heading   -->
+<!-- arrives at the default level, "h1".  The rendered HTML        -->
+<!-- itself, though, records the true nesting: each block's        -->
+<!-- wrapper element holds its heading as a child.  So the         -->
+<!-- accurate level is recovered from the rendering.  A division   -->
+<!-- heading (made elsewhere) is "h2"; a block directly below it   -->
+<!-- is "h3"; a block within a block (a "task" of a "project",     -->
+<!-- say) is "h4"; and so on, capped at "h6".  This is visual      -->
+<!-- fidelity, but more importantly it is the heading outline      -->
+<!-- that a screen reader's navigation presents.  Headings built   -->
+<!-- by other routes (divisions, "paragraphs", companion pages)    -->
+<!-- never pass through here, and keep their explicit levels.      -->
+<xsl:template match="node()|@*" mode="demote-headings">
+    <xsl:copy>
+        <xsl:apply-templates select="node()|@*" mode="demote-headings"/>
+    </xsl:copy>
+</xsl:template>
+
+<xsl:template match="h1[contains(concat(' ', normalize-space(@class), ' '), ' heading ')]" mode="demote-headings">
+    <!-- each ancestor with a heading of its own is an enclosing -->
+    <!-- block; this heading's block is the innermost of them    -->
+    <xsl:variable name="enclosing-blocks" select="count(ancestor::*[*[starts-with(local-name(), 'h') and (string-length(local-name()) = 2) and contains(concat(' ', normalize-space(@class), ' '), ' heading ')]])"/>
+    <xsl:variable name="level">
+        <xsl:choose>
+            <xsl:when test="2 + $enclosing-blocks &gt; 6">
+                <xsl:text>6</xsl:text>
+            </xsl:when>
+            <xsl:otherwise>
+                <xsl:value-of select="2 + $enclosing-blocks"/>
+            </xsl:otherwise>
+        </xsl:choose>
     </xsl:variable>
-    <xsl:variable name="html-node-set" select="exsl:node-set($html-rtf)" />
-    <xsl:call-template name="pretext-cell">
-        <xsl:with-param name="content">
-            <xsl:call-template name="begin-string" />
-                <xsl:apply-templates select="$html-node-set" mode="xml-to-string" />
-            <xsl:call-template name="end-string" />
-        </xsl:with-param>
+    <xsl:element name="h{$level}">
+        <xsl:apply-templates select="node()|@*" mode="demote-headings"/>
+    </xsl:element>
+</xsl:template>
+
+<!-- Split a block into markdown fragments around executable code  -->
+<!-- cells.  The block renders exactly as usual, except each       -->
+<!-- interior executable "sage" renders as an empty marker         -->
+<!-- element.  The rendered tree is then *sliced* at the markers:  -->
+<!-- slice k keeps the nodes that follow marker k (and precede     -->
+<!-- marker k+1), while any element that spans a marker (the       -->
+<!-- block's own wrapper, a "statement", a "task") is re-opened,   -->
+<!-- shallowly, in every slice it spans<mdash/>so each fragment is -->
+<!-- balanced HTML in the block's own dress, and the code may sit  -->
+<!-- at any depth.  The block's heading is part of the rendering,  -->
+<!-- so it lands in the first slice with no special treatment.     -->
+<xsl:template name="fragmented-block">
+    <!-- the block's ordinary rendering (markers included), made -->
+    <!-- by the caller; the context node remains the block       -->
+    <xsl:param name="rendered"/>
+    <xsl:variable name="element-name" select="local-name(.)"/>
+    <xsl:variable name="identifier">
+        <xsl:apply-templates select="." mode="html-id"/>
+    </xsl:variable>
+    <!-- settle heading levels before slicing -->
+    <xsl:variable name="demoted-rtf">
+        <xsl:apply-templates select="exsl:node-set($rendered)" mode="demote-headings"/>
+    </xsl:variable>
+    <xsl:variable name="marked" select="exsl:node-set($demoted-rtf)"/>
+    <!-- the code, in document order, mirroring the markers exactly -->
+    <xsl:variable name="code" select=".//sage[not(@type = 'display')]"/>
+    <xsl:variable name="code-count" select="count($code)"/>
+    <!-- the opening fragment always appears: it carries the heading -->
+    <xsl:call-template name="fragment-slice-cell">
+        <xsl:with-param name="marked" select="$marked"/>
+        <xsl:with-param name="slice-number" select="0"/>
+        <xsl:with-param name="element" select="$element-name"/>
+        <xsl:with-param name="identifier" select="$identifier"/>
+        <xsl:with-param name="part" select="'first'"/>
     </xsl:call-template>
+    <!-- alternate code cells with the slices that follow them -->
+    <xsl:for-each select="$code">
+        <xsl:variable name="place" select="position()"/>
+        <!-- does any actual content trail the final marker? -->
+        <xsl:variable name="last-slice-rtf">
+            <xsl:if test="$place = $code-count">
+                <xsl:apply-templates select="$marked/*" mode="fragment-slice">
+                    <xsl:with-param name="slice-number" select="$code-count"/>
+                </xsl:apply-templates>
+            </xsl:if>
+        </xsl:variable>
+        <xsl:variable name="b-code-is-last" select="($place = $code-count) and not(exsl:node-set($last-slice-rtf)//text()[normalize-space(.) != ''] or exsl:node-set($last-slice-rtf)//img)"/>
+        <xsl:apply-templates select="." mode="sage-code-cell">
+            <xsl:with-param name="element" select="$element-name"/>
+            <xsl:with-param name="identifier" select="$identifier"/>
+            <xsl:with-param name="part">
+                <xsl:choose>
+                    <xsl:when test="$b-code-is-last">
+                        <xsl:text>last</xsl:text>
+                    </xsl:when>
+                    <xsl:otherwise>
+                        <xsl:text>interior</xsl:text>
+                    </xsl:otherwise>
+                </xsl:choose>
+            </xsl:with-param>
+        </xsl:apply-templates>
+        <xsl:if test="not($b-code-is-last)">
+            <xsl:call-template name="fragment-slice-cell">
+                <xsl:with-param name="marked" select="$marked"/>
+                <xsl:with-param name="slice-number" select="$place"/>
+                <xsl:with-param name="element" select="$element-name"/>
+                <xsl:with-param name="identifier" select="$identifier"/>
+                <xsl:with-param name="part">
+                    <xsl:choose>
+                        <xsl:when test="$place = $code-count">
+                            <xsl:text>last</xsl:text>
+                        </xsl:when>
+                        <xsl:otherwise>
+                            <xsl:text>interior</xsl:text>
+                        </xsl:otherwise>
+                    </xsl:choose>
+                </xsl:with-param>
+            </xsl:call-template>
+        </xsl:if>
+    </xsl:for-each>
+</xsl:template>
+
+<!-- One slice of the marked rendering becomes one markdown cell, -->
+<!-- unless the slice holds no genuine content (adjacent code, or -->
+<!-- code that opens its block, leave gaps that nobody misses)    -->
+<xsl:template name="fragment-slice-cell">
+    <xsl:param name="marked"/>
+    <xsl:param name="slice-number"/>
+    <xsl:param name="element"/>
+    <xsl:param name="identifier"/>
+    <xsl:param name="part"/>
+    <xsl:variable name="slice-rtf">
+        <xsl:apply-templates select="$marked/*" mode="fragment-slice">
+            <xsl:with-param name="slice-number" select="$slice-number"/>
+            <xsl:with-param name="part" select="$part"/>
+        </xsl:apply-templates>
+    </xsl:variable>
+    <xsl:variable name="slice" select="exsl:node-set($slice-rtf)"/>
+    <xsl:if test="($part = 'first') or $slice//text()[normalize-space(.) != ''] or $slice//img">
+        <xsl:call-template name="pretext-cell">
+            <xsl:with-param name="content">
+                <xsl:call-template name="begin-string" />
+                    <xsl:apply-templates select="$slice" mode="xml-to-string" />
+                <xsl:call-template name="end-string" />
+            </xsl:with-param>
+            <xsl:with-param name="element" select="$element"/>
+            <xsl:with-param name="identifier" select="$identifier"/>
+            <xsl:with-param name="part" select="$part"/>
+        </xsl:call-template>
+    </xsl:if>
+</xsl:template>
+
+<!-- Slice a marked rendering.  An element containing markers is  -->
+<!-- re-opened (shallow copy) in every slice it spans; any other  -->
+<!-- node belongs to exactly the slice numbered by the count of   -->
+<!-- markers preceding it.  The markers themselves never survive. -->
+<xsl:template match="*" mode="fragment-slice">
+    <xsl:param name="slice-number"/>
+    <xsl:param name="part" select="''"/>
+    <xsl:choose>
+        <xsl:when test=".//pi:sage-marker">
+            <xsl:copy>
+                <!-- an HTML id may appear only once, so it stays -->
+                <!-- with the first slice of a spanning element   -->
+                <xsl:copy-of select="@*[not(name() = 'id') or ($slice-number = 0)]"/>
+                <!-- the outermost element of a slice advertises  -->
+                <!-- its position, for styling continuity         -->
+                <xsl:if test="not(parent::*) and not($part = '')">
+                    <xsl:attribute name="class">
+                        <xsl:value-of select="normalize-space(concat(@class, ' fragment-', $part))"/>
+                    </xsl:attribute>
+                </xsl:if>
+                <xsl:apply-templates select="node()" mode="fragment-slice">
+                    <xsl:with-param name="slice-number" select="$slice-number"/>
+                </xsl:apply-templates>
+            </xsl:copy>
+        </xsl:when>
+        <xsl:when test="count(preceding::pi:sage-marker) = $slice-number">
+            <xsl:copy-of select="."/>
+        </xsl:when>
+        <!-- other slices claim this node -->
+    </xsl:choose>
 </xsl:template>
 
+<xsl:template match="text()" mode="fragment-slice">
+    <xsl:param name="slice-number"/>
+    <xsl:if test="count(preceding::pi:sage-marker) = $slice-number">
+        <xsl:copy-of select="."/>
+    </xsl:if>
+</xsl:template>
+
+<xsl:template match="pi:sage-marker" mode="fragment-slice"/>
+
 <!-- Kill some templates temporarily -->
 <xsl:template name="inline-warning" />
 <xsl:template name="margin-warning" />
@@ -428,7 +691,53 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 
 <!-- Sage code -->
 <!-- Should evolve to accomodate general template -->
+<!-- A "sage" element whose parent produces cells (a division or   -->
+<!-- pseudo-division) becomes a genuine executable code cell.  But -->
+<!-- cells cannot nest, so a "sage" buried within a block (say an  -->
+<!-- "example") that is mid-formation as a single markdown cell    -->
+<!-- must not fire the cell machinery: it renders as a static      -->
+<!-- "pre" element within the block's HTML.  (Splitting such a     -->
+<!-- block into fragments around executable cells is the eventual  -->
+<!-- goal; this static form is the fallback.)                      -->
 <xsl:template match="sage">
+    <!-- formulate lines of code -->
+    <xsl:variable name="loc">
+        <xsl:call-template name="sanitize-text">
+            <xsl:with-param name="text">
+                <xsl:value-of select="input" />
+            </xsl:with-param>
+        </xsl:call-template>
+    </xsl:variable>
+    <xsl:choose>
+        <!-- contexts whose children each become top-level cells,   -->
+        <!-- mirroring the block-level wildcard template            -->
+        <xsl:when test="parent::*[&STRUCTURAL-FILTER;] or parent::paragraphs or parent::page or parent::introduction[parent::*[&STRUCTURAL-FILTER;]] or parent::conclusion[parent::*[&STRUCTURAL-FILTER;]]">
+            <xsl:apply-templates select="." mode="sage-code-cell"/>
+        </xsl:when>
+        <!-- a display-only listing is never executable: a static -->
+        <!-- rendering, as element nodes that serialize as part   -->
+        <!-- of the enclosing cell                                -->
+        <xsl:when test="@type = 'display'">
+            <pre class="code-display">
+                <xsl:value-of select="substring($loc, 1, string-length($loc)-1)" />
+            </pre>
+        </xsl:when>
+        <!-- interior to a block being split into fragments: the -->
+        <!-- rendering carries a marker where the code belongs,  -->
+        <!-- and the block's template slices at the markers and  -->
+        <!-- supplies the genuine code cells                     -->
+        <xsl:otherwise>
+            <pi:sage-marker/>
+        </xsl:otherwise>
+    </xsl:choose>
+</xsl:template>
+
+<!-- An executable cell from a "sage" element, with optional -->
+<!-- structure metadata when it sits interior to a block     -->
+<xsl:template match="sage" mode="sage-code-cell">
+    <xsl:param name="element" select="''"/>
+    <xsl:param name="identifier" select="''"/>
+    <xsl:param name="part" select="''"/>
     <!-- formulate lines of code -->
     <xsl:variable name="loc">
         <xsl:call-template name="sanitize-text">
@@ -445,6 +754,9 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
                 <xsl:value-of select="substring($loc, 1, string-length($loc)-1)" />
             <xsl:call-template name="end-string" />
         </xsl:with-param>
+        <xsl:with-param name="element" select="$element"/>
+        <xsl:with-param name="identifier" select="$identifier"/>
+        <xsl:with-param name="part" select="$part"/>
     </xsl:call-template>
 </xsl:template>
 
@@ -482,6 +794,19 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 <!-- For it to be effective will require the overall "ignore-math" -->
 <!-- class, and access to the MathJax configuration.               -->
 
+<!-- The notebook's MathJax reads mathematics from the *raw*        -->
+<!-- markdown source, before any HTML entity is decoded.  So        -->
+<!-- entity-escaping inside mathematics arrives literally: an       -->
+<!-- alignment ampersand serialized as "&amp;amp;" renders as a     -->
+<!-- visible "amp;".  Text within a math wrapper (the               -->
+<!-- "process-math" class) therefore serializes verbatim.  Bare     -->
+<!-- markup characters are not a hazard: PreTeXt requires \lt for   -->
+<!-- "less than" within mathematics, and MathJax lifts the math     -->
+<!-- from the source before the remainder is parsed as HTML.        -->
+<xsl:template match="text()[ancestor::*[contains(concat(' ', normalize-space(@class), ' '), ' process-math ')]]" mode="xml-to-string">
+    <xsl:value-of select="."/>
+</xsl:template>
+
 <!-- Images -->
 
 <!-- Jupyter seems to not allow an "object" tag.        -->
@@ -593,34 +918,17 @@ TODO: (overall)
 <!-- ############### -->
 
 <!-- Jupyter does a very good (but incomplete) job with inline -->
-<!-- verbatim text, requiring little care by authors.  But a   -->
-<!-- few gotchas need adjustment.  So we override.             -->
+<!-- verbatim text, requiring little care by authors.  So we   -->
+<!-- override.  The wrapper builds a genuine "code" element    -->
+<!-- whose content is plain text: the serialization step then  -->
+<!-- escapes any markup characters exactly once, so an author  -->
+<!-- may write about elements (like in the Author's Guide!)    -->
+<!-- and they arrive as visible text, never as interior HTML.  -->
 <xsl:template name="code-wrapper">
     <xsl:param name="content"/>
-
-    <!-- Jupyter notebook is careful about XML special characters, -->
-    <!-- but if you want to write about the escaped versions, they -->
-    <!-- just get converted to the real thing.  So in these five   -->
-    <!-- very special situations we escape the leading ampersand   -->
-    <!-- and whatever conversion is happening is satiated.         -->
-    <xsl:variable name="escaped-ampersand-fixed"    select="str:replace($content,                    '&amp;amp;',  '&amp;amp;amp;' )"/>
-    <xsl:variable name="escaped-leftbracket-fixed"  select="str:replace($escaped-ampersand-fixed,    '&amp;lt;',   '&amp;amp;lt;' )"/>
-    <xsl:variable name="escaped-rightbracket-fixed" select="str:replace($escaped-leftbracket-fixed,  '&amp;gt;',   '&amp;amp;gt;' )"/>
-    <xsl:variable name="escaped-apostrophe-fixed"   select="str:replace($escaped-rightbracket-fixed, '&amp;apos;', '&amp;amp;apos;' )"/>
-    <xsl:variable name="escaped-quote-fixed"        select="str:replace($escaped-apostrophe-fixed,   '&amp;quot;', '&amp;amp;quot;' )"/>
-
-    <!-- If you want to write about elements (like in the Author's     -->
-    <!-- Guide!) then you cannot have elements/tags sitting unaltered  -->
-    <!-- in verbatim text, since they now look like interior HTML.     -->
-    <!-- So we disrupt the leading left-bracket with an escaped        -->
-    <!-- version and let that convert to the character.                -->
-    <xsl:variable name="leftbracket-fixed" select="str:replace($escaped-quote-fixed, '&lt;', '&amp;lt;' )"/>
-
-    <!-- We wrap verbatim inline text with an HTML "code" element. -->
-    <!-- We enclose with PreTeXt's HTML, serializing by hand.      -->
-    <xsl:text>&lt;code class="code-inline tex2jax_ignore"&gt;</xsl:text>
-        <xsl:value-of select="$leftbracket-fixed"/>
-    <xsl:text>&lt;/code&gt;</xsl:text>
+    <code class="code-inline tex2jax_ignore">
+        <xsl:value-of select="$content"/>
+    </code>
 </xsl:template>
 
 <!-- #### -->
@@ -662,204 +970,108 @@ TODO: (overall)
     <xsl:text>"</xsl:text>
 </xsl:template>
 
-<!-- ########################## -->
-<!-- Intermediate Pseudo-Markup -->
-<!-- ########################## -->
-
-<!-- A Jupyter notebook is a flat sequence of cells, of type either     -->
-<!-- "markdown" or "code."  The content is primarily a list of strings. -->
-<!-- This presents two fundamental problems:                            -->
-<!--                                                                    -->
-<!--   1.  Lists of cells, or lists of strings, with  n  items          -->
-<!--       need exactly  n-1  commas.  It is hard to predict/find       -->
-<!--       the first or last element of a list.                         -->
-<!--                                                                    -->
-<!--   2.  Cells cannot be nested and content should not lie            -->
-<!--       outside of cells.                                            -->
-<!--                                                                    -->
-<!-- We use a sort of pseudo-markup.  Adjacency of items lets           -->
-<!-- us solve the comma problem.  We are also able to effectively       -->
-<!-- merge content into a cell, without knowing anything about          -->
-<!-- the following cell.                                                -->
-<!--                                                                    -->
-<!-- We pipeline a pseudo-markup as an intermediate text format.        -->
-<!--                                                                    -->
-<!-- Pseudo-markup language:                                            -->
-<!--                                                                    -->
-<!-- LB, RB: left and right brackets - should be UUIDs eventually       -->
-<!--                                                                    -->
-<!-- BS, ES: begin and end string                                       -->
-<!--                                                                    -->
-<!-- BM, EM, BC, EC: begin and end, markdown and code, cells            -->
-
-
-<!-- ####### -->
-<!-- Markers -->
-<!-- ####### -->
-
-<!-- This is pseudo-markup, starting with delimiters       -->
-<!-- analagous to < and > of XML.   Make these delimiters  -->
-<!-- exceedingly unique.  Comment out salt while debugging -->
-<!-- if it helps to see intermediate structure. Or leave   -->
-<!-- salt in, and grep final output for this "bad" string  -->
-<!-- that should not survive.                              -->
-
-<!-- Random-ish output from  mkpasswd  utility,           -->
-<!-- 2017-10-24 at AMS airport, Starbucks by faux gate D1 -->
-<xsl:variable name="salt" select="'x9rNtyUydoz3o'" />
-
-<xsl:variable name="LB">
-    <xsl:text>[[[</xsl:text>
-    <xsl:value-of select="$salt" />
-</xsl:variable>
-
-<xsl:variable name="RB">
-    <xsl:value-of select="$salt" />
-    <xsl:text>]]]</xsl:text>
-</xsl:variable>
-
-<!-- These are analagous to XML opening           -->
-<!-- ("begin", B) and closing ("end", E) elements -->
-
-<!-- Destined to be string -->
-<xsl:variable name="BS">
-    <xsl:value-of select="$LB" />
-    <xsl:text>BS</xsl:text>
-    <xsl:value-of select="$RB" />
-</xsl:variable>
-<xsl:variable name="ES">
-    <xsl:value-of select="$LB" />
-    <xsl:text>ES</xsl:text>
-    <xsl:value-of select="$RB" />
-</xsl:variable>
-
-<!-- Destined to be a Jupyter markdown cell in JSON output-->
-<xsl:variable name="BM">
-    <xsl:value-of select="$LB" />
-    <xsl:text>BM</xsl:text>
-    <xsl:value-of select="$RB" />
-</xsl:variable>
-<xsl:variable name="EM">
-    <xsl:value-of select="$LB" />
-    <xsl:text>EM</xsl:text>
-    <xsl:value-of select="$RB" />
-</xsl:variable>
-
-<!-- Destined to be a Jupyter code cell in JSON output-->
-<xsl:variable name="BC">
-    <xsl:value-of select="$LB" />
-    <xsl:text>BC</xsl:text>
-    <xsl:value-of select="$RB" />
-</xsl:variable>
-<xsl:variable name="EC">
-    <xsl:value-of select="$LB" />
-    <xsl:text>EC</xsl:text>
-    <xsl:value-of select="$RB" />
-</xsl:variable>
-
-<!-- These variables describe adjacent pseudo-markup -->
-<!-- that will be converted to JSON equivalents.     -->
-
-<xsl:variable name="ESBS">
-    <xsl:value-of select="$ES" />
-    <xsl:value-of select="$BS" />
-</xsl:variable>
-
-<xsl:variable name="RBLB">
-    <xsl:value-of select="$RB" />
-    <xsl:value-of select="$LB" />
-</xsl:variable>
-
-<!-- This is a convenience for the replacement that -->
-<!-- splits cells into lines within JSON file       -->
-<xsl:variable name="RBLB-comma">
-    <xsl:value-of select="$RB" />
-    <xsl:text>,&#xa;</xsl:text>
-    <xsl:value-of select="$LB" />
-</xsl:variable>
-
-<!-- Convenience templates -->
-<!-- These are primary interface to our creation          -->
-<!-- of pseudo-markup above, but are not the whole        -->
-<!-- story since we convert markup based on the variables -->
-
-<xsl:template name="begin-string">
-    <xsl:value-of select="$BS" />
-</xsl:template>
-
-<xsl:template name="end-string">
-    <xsl:value-of select="$ES" />
-</xsl:template>
-
-<xsl:template name="begin-markdown-cell">
-    <xsl:value-of select="$BM" />
-</xsl:template>
-
-<xsl:template name="end-markdown-cell">
-    <xsl:value-of select="$EM" />
-</xsl:template>
-
-<xsl:template name="begin-code-cell">
-    <xsl:value-of select="$BC" />
-</xsl:template>
-
-<xsl:template name="end-code-cell">
-    <xsl:value-of select="$EC" />
-</xsl:template>
-
-
 <!-- ################# -->
 <!-- Cell Construction -->
 <!-- ################# -->
 
-<xsl:variable name="begin-markdown-wrap">
-    <xsl:text>{"cell_type":"markdown", "metadata":{}, "source":[</xsl:text>
-</xsl:variable>
+<!-- A Jupyter notebook is a flat sequence of cells, of type either  -->
+<!-- "markdown" or "code", each holding one string.  We describe     -->
+<!-- each notebook as a "notebook" element holding a flat list of    -->
+<!-- "cell" elements; the Python conversion routine turns each       -->
+<!-- description into JSON with the "nbformat" library, which owns   -->
+<!-- string escaping, cell boilerplate, and schema conformance.      -->
+<!-- Cells cannot be nested, so cell-producing templates must never  -->
+<!-- fire while another cell's content is under construction.        -->
 
-<xsl:variable name="end-markdown-wrap">
-    <xsl:text>]}</xsl:text>
-</xsl:variable>
+<!-- The two templates immediately following are historical seams:  -->
+<!-- every string destined for a cell was once delimited by markers -->
+<!-- these templates produced.  A cell's content is now a single    -->
+<!-- string, so they are no-ops, retained since callers throughout  -->
+<!-- this stylesheet still frame content with them, and they mark   -->
+<!-- exactly the boundaries a future refinement (say, a markdown    -->
+<!-- flavor of cell content) might need to intercept.               -->
 
-<xsl:variable name="begin-code-wrap">
-    <xsl:text>{"cell_type":    "code", "execution_count":null, "metadata":{}, "source":[</xsl:text>
-</xsl:variable>
+<xsl:template name="begin-string"/>
 
-<xsl:variable name="end-code-wrap">
-    <xsl:text>], "outputs":[]}</xsl:text>
-</xsl:variable>
+<xsl:template name="end-string"/>
 
 <!-- A Jupyter markdown cell intended  -->
 <!-- to hold markdown or unstyled HTML -->
 <xsl:template name="markdown-cell">
     <xsl:param name="content" />
-    <xsl:call-template name="begin-markdown-cell" />
-    <xsl:value-of select="$content" />
-    <xsl:call-template name="end-markdown-cell" />
+    <cell type="markdown">
+        <xsl:value-of select="$content" />
+    </cell>
 </xsl:template>
 
 <!-- A Jupyter markdown cell intended -->
 <!-- to hold PreTeXt styled HTML      -->
 <!-- Serialization here is "by hand"  -->
+<!-- The three structure parameters describe a cell which is a  -->
+<!-- *fragment* of a PreTeXt element split around code cells;   -->
+<!-- they land in the notebook cell's metadata, preserving the  -->
+<!-- hierarchy that the flat cell list cannot express directly. -->
 <xsl:template name="pretext-cell">
     <xsl:param name="content" />
-    <xsl:call-template name="begin-markdown-cell" />
-    <xsl:call-template name="begin-string" />
-    <xsl:text>&lt;div class="mathbook-content"&gt;</xsl:text>
-    <xsl:call-template name="end-string" />
-    <xsl:value-of select="$content" />
-    <xsl:call-template name="begin-string" />
-    <xsl:text>&lt;/div&gt;</xsl:text>
-    <xsl:call-template name="end-string" />
-    <xsl:call-template name="end-markdown-cell" />
+    <xsl:param name="element" select="''"/>
+    <xsl:param name="identifier" select="''"/>
+    <xsl:param name="part" select="''"/>
+    <cell type="markdown">
+        <xsl:if test="not($element = '')">
+            <xsl:attribute name="element">
+                <xsl:value-of select="$element"/>
+            </xsl:attribute>
+        </xsl:if>
+        <xsl:if test="not($identifier = '')">
+            <xsl:attribute name="identifier">
+                <xsl:value-of select="$identifier"/>
+            </xsl:attribute>
+        </xsl:if>
+        <xsl:if test="not($part = '')">
+            <xsl:attribute name="part">
+                <xsl:value-of select="$part"/>
+            </xsl:attribute>
+        </xsl:if>
+        <xsl:text>&lt;div class="mathbook-content"&gt;</xsl:text>
+        <xsl:value-of select="$content" />
+        <xsl:text>&lt;/div&gt;</xsl:text>
+    </cell>
 </xsl:template>
 
 <!-- A Jupyter code cell intended -->
 <!-- to hold raw text/code        -->
 <xsl:template name="code-cell">
     <xsl:param name="content" />
-    <xsl:call-template name="begin-code-cell" />
-    <xsl:value-of select="$content" />
-    <xsl:call-template name="end-code-cell" />
+    <xsl:param name="element" select="''"/>
+    <xsl:param name="identifier" select="''"/>
+    <xsl:param name="part" select="''"/>
+    <!-- "purpose" flags special cells (only 'styling' so far) for -->
+    <!-- extra treatment by the Python routine: the styling cell   -->
+    <!-- collapses, and ships with its output pre-rendered         -->
+    <xsl:param name="purpose" select="''"/>
+    <cell type="code">
+        <xsl:if test="not($purpose = '')">
+            <xsl:attribute name="purpose">
+                <xsl:value-of select="$purpose"/>
+            </xsl:attribute>
+        </xsl:if>
+        <xsl:if test="not($element = '')">
+            <xsl:attribute name="element">
+                <xsl:value-of select="$element"/>
+            </xsl:attribute>
+        </xsl:if>
+        <xsl:if test="not($identifier = '')">
+            <xsl:attribute name="identifier">
+                <xsl:value-of select="$identifier"/>
+            </xsl:attribute>
+        </xsl:if>
+        <xsl:if test="not($part = '')">
+            <xsl:attribute name="part">
+                <xsl:value-of select="$part"/>
+            </xsl:attribute>
+        </xsl:if>
+        <xsl:value-of select="$content" />
+    </cell>
 </xsl:template>
 
 <!-- We don't want any permalinks -->