@pretextbook/pretext-html 0.3.0 → 0.5.0

package/assets/xsl/pretext-braille-preprint.xsl

@@ -67,6 +67,60 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 <!-- Not so much "include" as "manipulate"            -->
 <xsl:param name="math.punctuation.include" select="'all'"/>
 
+<!-- Developer-only.  Braille arriving from Speech Rule Engine     -->
+<!-- (mathematics) is Unicode braille cells (U+2800 through        -->
+<!-- U+283F).  With "late" (the default) those cells ride through  -->
+<!-- the preprint intermediate unchanged and become BRF ASCII      -->
+<!-- symbols in the renderer.  With "early" the conversion to BRF  -->
+<!-- ASCII symbols happens here, so the preprint file itself is    -->
+<!-- readable by anyone fluent in BRF, at no change to the final   -->
+<!-- BRF.  The root element of the preprint records the choice so  -->
+<!-- the renderer can react.                                       -->
+<xsl:param name="debug.brf.symbols" select="'late'"/>
+<xsl:variable name="brf-symbols">
+    <xsl:choose>
+        <xsl:when test="($debug.brf.symbols = 'early') or ($debug.brf.symbols = 'late')">
+            <xsl:value-of select="$debug.brf.symbols"/>
+        </xsl:when>
+        <xsl:otherwise>
+            <xsl:message>PTX:FALLBACK: the "debug.brf.symbols" string parameter must be "early" or "late", not "<xsl:value-of select="$debug.brf.symbols"/>", using "late" instead</xsl:message>
+            <xsl:text>late</xsl:text>
+        </xsl:otherwise>
+    </xsl:choose>
+</xsl:variable>
+<xsl:variable name="b-braille-symbols-early" select="$brf-symbols = 'early'"/>
+
+<!-- The 64 Unicode braille cells, in numerical order, and their   -->
+<!-- BRF ASCII equivalents, generated with liblouis, which is what -->
+<!-- the renderer employs for the identical conversion when the    -->
+<!-- cells ride through as Unicode ("late").  Exception: the blank -->
+<!-- cell U+2800 maps to a NO-BREAK SPACE, not to a plain space:   -->
+<!-- it reads as a space, but the renderer can still distinguish   -->
+<!-- a (non-breaking) blank cell from an authored space when it    -->
+<!-- makes line-breaking decisions, and it becomes a plain space   -->
+<!-- in the final output, exactly as a blank cell does.            -->
+<xsl:variable name="unicode-braille-cells" select="'&#x2800;&#x2801;&#x2802;&#x2803;&#x2804;&#x2805;&#x2806;&#x2807;&#x2808;&#x2809;&#x280A;&#x280B;&#x280C;&#x280D;&#x280E;&#x280F;&#x2810;&#x2811;&#x2812;&#x2813;&#x2814;&#x2815;&#x2816;&#x2817;&#x2818;&#x2819;&#x281A;&#x281B;&#x281C;&#x281D;&#x281E;&#x281F;&#x2820;&#x2821;&#x2822;&#x2823;&#x2824;&#x2825;&#x2826;&#x2827;&#x2828;&#x2829;&#x282A;&#x282B;&#x282C;&#x282D;&#x282E;&#x282F;&#x2830;&#x2831;&#x2832;&#x2833;&#x2834;&#x2835;&#x2836;&#x2837;&#x2838;&#x2839;&#x283A;&#x283B;&#x283C;&#x283D;&#x283E;&#x283F;'"/>
+<xsl:variable name="ascii-braille-cells">&#xA0;a1b'k2l`cif/msp"e3h9o6r~djg&gt;ntq,*5&lt;-u8v.%{$+x!&amp;;:4|0z7(_?w}#y)=</xsl:variable>
+
+<!-- Convert Unicode braille cells to BRF ASCII symbols, when      -->
+<!-- elected ("early"); the text is otherwise undisturbed.         -->
+<!-- The conversion is all-or-nothing per text: when a             -->
+<!-- construction has no braille translation, Speech Rule Engine   -->
+<!-- can leave print residue among the cells, and such a mixture   -->
+<!-- must ride along whole (cells as Unicode) so the renderer      -->
+<!-- gives it the identical late treatment under either election.  -->
+<xsl:template name="brf-symbols-filter">
+    <xsl:param name="text"/>
+    <xsl:choose>
+        <xsl:when test="$b-braille-symbols-early and (translate($text, concat($unicode-braille-cells, ' &#xa;&#x9;&#xd;&#xa0;'), '') = '')">
+            <xsl:value-of select="translate($text, $unicode-braille-cells, $ascii-braille-cells)"/>
+        </xsl:when>
+        <xsl:otherwise>
+            <xsl:value-of select="$text"/>
+        </xsl:otherwise>
+    </xsl:choose>
+</xsl:template>
+
 <!-- ############################## -->
 <!-- Incorporate (Meld) Mathematics -->
 <!-- ############################## -->
@@ -203,70 +257,129 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 
 <!-- And we sneak in a warning that this conversion is underway, but not complete. -->
 <xsl:template name="warning-unimplemented">
-    <xsl:message>** Some PreTeXt elements lack full implementation in the braille conversion.</xsl:message>
-    <xsl:message>** Smaller items will simply be missing from your output.</xsl:message>
-    <xsl:message>** Larger items may have all-caps placeholders in your output.</xsl:message>
-    <xsl:message>** These will all be reported as "Overlooked" in the log.</xsl:message>
-    <xsl:message>** Please report the complete list in the PreTeXt support forum,</xsl:message>
-    <xsl:message>** so we can prioritize making the output for your project complete.</xsl:message>
+    <xsl:message>PTX:INFO: Some PreTeXt elements lack full implementation in the braille conversion.</xsl:message>
+    <xsl:message>PTX:INFO: Smaller items will simply be missing from your output.</xsl:message>
+    <xsl:message>PTX:INFO: Larger items may have all-caps placeholders in your output.</xsl:message>
+    <xsl:message>PTX:INFO: These will all be reported as "Overlooked" in the log.</xsl:message>
+    <xsl:message>PTX:INFO: Please report the complete list in the PreTeXt support forum,</xsl:message>
+    <xsl:message>PTX:INFO: so we can prioritize making the output for your project complete.</xsl:message>
 </xsl:template>
 
 <!-- The entry template "waits" for the "$math-meld-rtf" and    -->
 <!-- "$segmented-rtf" global variables to form, then the actual -->
-<!-- output is a run of modal "meld-runin" templates as a sort  -->
-<!-- of post-processing step.                                   -->
+<!-- output comes from two post-processing passes: the modal    -->
+<!-- "meld-runin" templates absorb run-in titles into their     -->
+<!-- segments, and then the modal "flatten-runs" templates      -->
+<!-- dissolve nested font-change markup into a flat sequence    -->
+<!-- of "run" elements bearing composite "@typeform" values.    -->
 <xsl:template match="/">
-    <xsl:apply-templates select="exsl:node-set($segmented-rtf)/brf" mode="meld-runin"/>
+    <xsl:variable name="melded-runin-rtf">
+        <xsl:apply-templates select="exsl:node-set($segmented-rtf)/brf" mode="meld-runin"/>
+    </xsl:variable>
+    <xsl:apply-templates select="exsl:node-set($melded-runin-rtf)/brf" mode="flatten-runs"/>
+</xsl:template>
+
+<!-- ############################ -->
+<!-- Flatten Font Changes to Runs -->
+<!-- ############################ -->
+
+<!-- Font-change markup ("italic", "bold", "code") arrives from the -->
+<!-- earlier pass as elements, which may nest ("italic" containing  -->
+<!-- "code", say).  A formatter wants a flat sequence, so each text -->
+<!-- node becomes a "run" element whose "@typeform" records every   -->
+<!-- font change in effect, as space-separated tokens.  Text with   -->
+<!-- no font change rides along bare.  The font-change elements     -->
+<!-- themselves evaporate.  Mathematics ("math") is already braille -->
+<!-- cells and is preserved whole, its interior untouched.          -->
+
+<!-- Dissolve, children continue -->
+<xsl:template match="italic|bold|code" mode="flatten-runs">
+    <xsl:apply-templates select="node()" mode="flatten-runs"/>
+</xsl:template>
+
+<!-- Mathematics is opaque, xerox entirely -->
+<xsl:template match="math" mode="flatten-runs">
+    <xsl:copy-of select="."/>
+</xsl:template>
+
+<!-- Text nodes inside a segment (or a converted run-in title)  -->
+<!-- either ride bare (no font change) or become a "run".  The  -->
+<!-- ancestor axis sees the font-change elements because they   -->
+<!-- are still present in the tree under examination.           -->
+<xsl:template match="text()" mode="flatten-runs">
+    <xsl:variable name="typeform">
+        <xsl:if test="ancestor::italic">
+            <xsl:text>italic </xsl:text>
+        </xsl:if>
+        <xsl:if test="ancestor::bold">
+            <xsl:text>bold </xsl:text>
+        </xsl:if>
+        <xsl:if test="ancestor::code">
+            <xsl:text>code </xsl:text>
+        </xsl:if>
+    </xsl:variable>
+    <xsl:choose>
+        <xsl:when test="$typeform = ''">
+            <xsl:value-of select="."/>
+        </xsl:when>
+        <xsl:otherwise>
+            <run>
+                <xsl:attribute name="typeform">
+                    <xsl:value-of select="normalize-space($typeform)"/>
+                </xsl:attribute>
+                <xsl:value-of select="."/>
+            </run>
+        </xsl:otherwise>
+    </xsl:choose>
+</xsl:template>
+
+<!-- Xerox machine.  Elements and attributes only: text nodes have -->
+<!-- their own template above, and it must win the match.          -->
+<xsl:template match="*|@*" mode="flatten-runs">
+    <xsl:copy>
+        <xsl:apply-templates select="@*|node()" mode="flatten-runs"/>
+    </xsl:copy>
 </xsl:template>
 
 <!-- Process segments here, looking for run-in titles/headings -->
 <xsl:template match="segment" mode="meld-runin">
-    <!-- Look for "run-in" material just prior -->
-    <xsl:variable name="adjacent-runin" select="preceding-sibling::*[1][self::runin]"/>
+    <!-- Look for "run-in" material just prior: the whole maximal   -->
+    <!-- chain of consecutive "runin" siblings whose first          -->
+    <!-- following non-"runin" sibling is this very segment.  Each  -->
+    <!-- melds in, in order, with its separator.  Chains occur      -->
+    <!-- routinely: an exercise, or a list item, may begin with a   -->
+    <!-- nested list, stacking a marker for every level.            -->
+    <xsl:variable name="runin-chain" select="preceding-sibling::runin[generate-id(following-sibling::*[not(self::runin)][1]) = generate-id(current())]"/>
     <xsl:copy>
         <xsl:apply-templates select="@*" mode="meld-runin"/>
-        <xsl:apply-templates select="$adjacent-runin/@indentation|$adjacent-runin/@lines-before" mode="meld-runin"/>
-        <xsl:apply-templates select="$adjacent-runin/node()" mode="meld-runin"/>
-        <xsl:value-of select="$adjacent-runin/@separator"/>
+        <!-- the chain's first runin positions the merged segment -->
+        <xsl:apply-templates select="$runin-chain[1]/@indentation|$runin-chain[1]/@lines-before" mode="meld-runin"/>
+        <xsl:for-each select="$runin-chain">
+            <xsl:apply-templates select="node()" mode="meld-runin"/>
+            <xsl:value-of select="@separator"/>
+        </xsl:for-each>
         <xsl:apply-templates select="node()" mode="meld-runin"/>
     </xsl:copy>
 </xsl:template>
 
-<!-- It is entirely possible for a segment to be preceded by     -->
-<!-- consecutive "runin" elements.  Three examples:              -->
-<!--                                                             -->
-<!--   "proof" then "case"                                       -->
-<!--   "hint" then "li" (and other SOLUTION-LIKE)                -->
-<!--   "exercise" then "li" (but should probably be "task"?)     -->
-<!--                                                             -->
-<!-- Likely a structure with an immediate "p" with an immediate  -->
-<!-- list could result in a run-in title for the structure and   -->
-<!-- a run-in title for the first list item.  Experimentation on -->
-<!-- 2023-04-05 with Judson's AATA did not reveal any runs of    -->
-<!-- three (or more) consecutive "runin" elements.  So our       -->
-<!-- solution is ad-hoc for the double case, with a bug report   -->
-<!-- for three or more.                                          -->
-<!-- We convert the first "runin" to a "segment" (rather than    -->
-<!-- killing it) and let the second "runin" get absorbed by the  -->
-<!-- subsequent "segment".                                       -->
-<xsl:template match="runin[following-sibling::*[1][self::runin]]" mode="meld-runin">
-    <segment>
-        <xsl:apply-templates select="@*|node()" mode="meld-runin"/>
-    </segment>
-    <xsl:if test="following-sibling::*[2][self::runin]">
-        <xsl:message>BUG: the braille conversion has encountered three "run-in" titles in a row,</xsl:message>
-        <xsl:message>which we had not expected.  Please report me.  Thank-you.</xsl:message>
-        <xsl:message>First: <xsl:value-of select="."/></xsl:message>
-        <xsl:message>Second: <xsl:value-of select="following-sibling::*[1][self::runin]"/></xsl:message>
-        <xsl:message>Third: <xsl:value-of select="following-sibling::*[2][self::runin]"/></xsl:message>
-    </xsl:if>
+<!-- A "runin" whose chain ends at a "segment" has been absorbed   -->
+<!-- above; it must not persist.  A "runin" whose chain does NOT   -->
+<!-- end at a segment (a block comes next, or nothing does) has no -->
+<!-- host to meld into, so it becomes a segment of its own rather  -->
+<!-- than disappear: content is never dropped silently.            -->
+<xsl:template match="runin" mode="meld-runin">
+    <xsl:choose>
+        <xsl:when test="following-sibling::*[not(self::runin)][1][self::segment]">
+            <!-- absorbed by that segment -->
+        </xsl:when>
+        <xsl:otherwise>
+            <segment>
+                <xsl:apply-templates select="@*|node()" mode="meld-runin"/>
+            </segment>
+        </xsl:otherwise>
+    </xsl:choose>
 </xsl:template>
 
-<!-- Every "runin" has been absorbed into a trailing "segment" or -->
-<!-- perhaps converted into a "segment".  This will prevent the   -->
-<!-- absorbed ones from persisting.                               -->
-<xsl:template match="runin" mode="meld-runin"/>
-
 <!-- Xerox machine -->
 <xsl:template match="@*|node()" mode="meld-runin">
     <xsl:copy>
@@ -279,6 +392,21 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
     <!-- Need an overall container   -->
     <!-- Maybe copy a language code? -->
     <brf>
+        <!-- Record how braille cells are represented ("early" is  -->
+        <!-- BRF ASCII symbols, "late" is Unicode braille cells)   -->
+        <!-- so the renderer can react to mathematics accordingly. -->
+        <xsl:attribute name="brf-symbols">
+            <xsl:value-of select="$brf-symbols"/>
+        </xsl:attribute>
+        <!-- Page geometry, from the publication file (or the      -->
+        <!-- defaults), for the renderer: cells in a line, lines   -->
+        <!-- on an embossed page.                                  -->
+        <xsl:attribute name="page-width">
+            <xsl:value-of select="$braille-page-width"/>
+        </xsl:attribute>
+        <xsl:attribute name="page-height">
+            <xsl:value-of select="$braille-page-height"/>
+        </xsl:attribute>
         <!-- centered heading on line 1 -->
         <segment centered="yes" lines-after="1">Transcriber Notes</segment>
         <!-- Literal text for each note, control whitespace,  -->
@@ -302,6 +430,14 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
             </segment>
         </xsl:if>
         <!--  -->
+        <!-- [BANA-2016, 8.6.2(b)] bullet symbols used in lists are -->
+        <!-- listed in a transcriber's note                          -->
+        <xsl:if test="//ul">
+            <segment indentation="2">
+                <xsl:text>Items of unordered lists retain their print markers, each followed by a period.  The symbols in use are: bullet (dots 456, 256), circle (dots 1246 and a grade one indicator, 123456), and square (dots 456, 1246, 3456, 145).</xsl:text>
+            </segment>
+        </xsl:if>
+        <!--  -->
         <!-- automatically infers we have a note already for "sidebyside" -->
         <xsl:if test="//sbsgroup">
             <segment indentation="2">
@@ -884,7 +1020,7 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 <!-- to coordinate text and manually inserted tactile versions.     -->
 <xsl:template match="image" mode="block-title">
     <xsl:text>Image: </xsl:text>
-    <xsl:apply-templates select="." mode="visible-id"/>
+    <xsl:apply-templates select="." mode="unique-id"/>
     <xsl:text>.</xsl:text>
 </xsl:template>
 
@@ -902,6 +1038,11 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 <!-- pages, rather than across, since horizontal real estate is limited  -->
 <!-- and images are going full (own) page.                               -->
 <!-- From discussion with Michael Cantino and Al Maneki, 2023-03-30      -->
+<!--                                                                     -->
+<!-- This is the same linear composition as the text conversion (no      -->
+<!-- horizontal layout, so the -common machinery is unused), but         -->
+<!-- with braille-idiomatic transcriber notes, so the two                -->
+<!-- conversions share the design, not the code.                         -->
 
 <xsl:template match="sidebyside">
     <xsl:variable name="npanels" select="count(*)"/>
@@ -963,18 +1104,49 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 <!-- Lists -->
 <!-- ##### -->
 
-<!-- Lists are containers full of list items.  All by   -->
-<!-- themselves they have no real impact on the braille -->
-<!-- output.  The list items are another matter.        -->
-<!-- 2023-04-06: very prelimnary, e.g. no runover       -->
-<!-- 2023-04-10: excessive nesting => excessive run-in  -->
+<!-- Lists are containers full of list items.  The container's -->
+<!-- one responsibility: [BANA-2016, 8.3.2(a)] a list is        -->
+<!-- preceded and followed by a blank line.  That means the     -->
+<!-- OUTERMOST list; a nested list runs on without a break.     -->
+<!-- (An empty segment demanding a line before it is the idiom  -->
+<!-- for one blank line, suppressed at the top of a page.)      -->
 <xsl:template match="ul|ol|dl">
+    <xsl:variable name="b-outermost" select="not(ancestor::ol or ancestor::ul or ancestor::dl)"/>
+    <xsl:if test="$b-outermost">
+        <segment lines-before="1"/>
+    </xsl:if>
     <xsl:apply-templates select="li"/>
+    <xsl:if test="$b-outermost">
+        <segment lines-before="1"/>
+    </xsl:if>
 </xsl:template>
 
 <xsl:template match="li">
+    <!-- [BANA-2016, 8.3.1] a simple list has 1-3 margins           -->
+    <!-- [BANA-2016, 8.5.1(b)] each nested level begins two cells   -->
+    <!-- to the right of the previous level, and ALL runovers begin -->
+    <!-- two cells to the right of the farthest indented level: one -->
+    <!-- level is 1-3; two levels are 1-5, 3-5; three levels are    -->
+    <!-- 1-7, 3-7, 5-7.  In the preprint's 0-based attributes:      -->
+    <!-- level k of an n-level list has indentation 2(k-1), and     -->
+    <!-- every segment of the list has runover 2n.                  -->
+    <!-- The level of this item, and the deepest level anywhere in  -->
+    <!-- the outermost list containing it.  (A list separated from  -->
+    <!-- an enclosing list by other structure still counts every    -->
+    <!-- list ancestor, deliberately: its margins nest visibly.)    -->
+    <xsl:variable name="level" select="count(ancestor::ol | ancestor::ul | ancestor::dl)"/>
+    <xsl:variable name="outermost-list" select="ancestor::*[self::ol or self::ul or self::dl][last()]"/>
+    <xsl:variable name="list-depth">
+        <xsl:for-each select="$outermost-list//li">
+            <xsl:sort select="count(ancestor::ol | ancestor::ul | ancestor::dl)" data-type="number" order="descending"/>
+            <xsl:if test="position() = 1">
+                <xsl:value-of select="count(ancestor::ol | ancestor::ul | ancestor::dl)"/>
+            </xsl:if>
+        </xsl:for-each>
+    </xsl:variable>
+    <xsl:variable name="list-runover" select="2 * $list-depth"/>
     <!-- Marker as a "runin" element -->
-    <runin indentation="0" separator="&#x20;">
+    <runin indentation="{2 * ($level - 1)}" separator="&#x20;">
         <xsl:choose>
             <xsl:when test="parent::ol">
                 <xsl:apply-templates select="." mode="item-number"/>
@@ -989,7 +1161,51 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
             </xsl:when>
         </xsl:choose>
     </runin>
-    <xsl:apply-templates select="node()"/>
+    <xsl:choose>
+        <!-- A structured list item carries paragraphs, or other   -->
+        <!-- block-shaped material, all of which make segments (or  -->
+        <!-- whole blocks) of their own.  The test mirrors the      -->
+        <!-- schema exactly: an "li" may hold BlockStatement, which -->
+        <!-- is BlockText (paragraph, blockquote, preformatted,     -->
+        <!-- image, video, audio, program, console, tabular), the   -->
+        <!-- figure family (figure, table, listing, list), aside,   -->
+        <!-- side-by-sides, and Sage cells.  Displayed items that   -->
+        <!-- can live within a paragraph (nested lists, display     -->
+        <!-- mathematics) are deliberately NOT in this test: mixed  -->
+        <!-- content holds them, and the paragraph machinery        -->
+        <!-- splits them out correctly.                             -->
+        <xsl:when test="p or blockquote or pre or image or video or audio or program or console or tabular or figure or table or listing or list or aside or sidebyside or sbsgroup or sage">
+            <xsl:apply-templates select="node()">
+                <xsl:with-param name="list-runover" select="$list-runover"/>
+            </xsl:apply-templates>
+        </xsl:when>
+        <!-- An unstructured list item is a run of sentences,      -->
+        <!-- exactly the content of a paragraph.  But with no      -->
+        <!-- "p" there is no template to make a segment of it, and -->
+        <!-- unanchored content is lost.  So manufacture the       -->
+        <!-- missing paragraph around a copy of the content, and   -->
+        <!-- process that: the ordinary paragraph templates then   -->
+        <!-- apply, including the splitting of displayed items     -->
+        <!-- (display mathematics, a nested list) into siblings.   -->
+        <!--                                                       -->
+        <!-- TODO: the project direction is to manufacture such    -->
+        <!-- missing wrappers ("p", "statement") once, during      -->
+        <!-- assembly, marked with a "pi:" attribute, so authors   -->
+        <!-- keep their freedom while conversions see uniform      -->
+        <!-- structure.  When that arrives, this local device      -->
+        <!-- evaporates: the manufactured "p" is a real one here,  -->
+        <!-- and its flag guides any special list treatment.       -->
+        <xsl:otherwise>
+            <xsl:variable name="virtual-paragraph-rtf">
+                <p>
+                    <xsl:copy-of select="node()"/>
+                </p>
+            </xsl:variable>
+            <xsl:apply-templates select="exsl:node-set($virtual-paragraph-rtf)/p">
+                <xsl:with-param name="list-runover" select="$list-runover"/>
+            </xsl:apply-templates>
+        </xsl:otherwise>
+    </xsl:choose>
 </xsl:template>
 
 <xsl:template match="ul/li" mode="unicode-list-marker">
@@ -1193,7 +1409,10 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 <!-- Bibliographic items in a "references" division have a      -->
 <!-- bracketed number leading each new entry, then two spaces   -->
 <!-- of indentation for the remainder .                         -->
-<!-- TODO: expand to accomodate annotations ("note"), BANA 22.3 -->
+<!-- An annotation ("note") produces a block, so it cannot live -->
+<!-- inside the entry's segment; it follows as a sibling.       -->
+<!-- TODO: format annotations per BANA 22.3, rather than        -->
+<!-- reusing the boxed rendering of a REMARK-LIKE "note".       -->
 <xsl:template match="biblio[@type='raw']">
     <runin indentation="0" separator="&#x20;">
         <xsl:text>[</xsl:text>
@@ -1201,8 +1420,26 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
         <xsl:text>]</xsl:text>
     </runin>
     <segment indentation="0" runover="2">
-        <xsl:apply-templates/>
+        <xsl:apply-templates select="node()[not(self::note)]"/>
+    </segment>
+    <xsl:apply-templates select="note"/>
+</xsl:template>
+
+<!-- Structured bibliographic entries ("bibtex" type, or untyped   -->
+<!-- fallback) render their fields in document order, with the     -->
+<!-- same [BANA-2016, 22.2.1] margins as the raw flavor above, and -->
+<!-- the same treatment of an annotation: a "note" produces a      -->
+<!-- block, so it follows the entry as a sibling.                  -->
+<xsl:template match="biblio[not(@type = 'raw')]">
+    <runin indentation="0" separator="&#x20;">
+        <xsl:text>[</xsl:text>
+        <xsl:apply-templates select="." mode="serial-number"/>
+        <xsl:text>]</xsl:text>
+    </runin>
+    <segment indentation="0" runover="2">
+        <xsl:apply-templates select="*[not(self::note)]"/>
     </segment>
+    <xsl:apply-templates select="note"/>
 </xsl:template>
 
 <!-- Override usual killing of title, but perhaps a generic -->
@@ -1262,62 +1499,64 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 <!-- as quotation mark styles, since we are limited ourselves to   -->
 <!-- English language documents by larger decisions elsewhere.     -->
 
-<!-- Unicode Character 'NO-BREAK SPACE' (U+00A0)   -->
-<!-- yields a template for "nbsp" in -common       -->
-<!-- liblouis seems to pass this through in-kind   -->
-<!-- Used in the manufacture of a cross-reference, -->
-<!-- we will want to strip just before it ends up  -->
-<!-- in BRF .                                      -->
-<xsl:template name="nbsp-character">
-    <xsl:text>&#x00A0;</xsl:text>
-</xsl:template>
-
-<!-- Unicode Character 'EN DASH' (U+2013) -->
-<!-- Liblouis: 6-36                       -->
-<xsl:template name="ndash-character">
-    <xsl:text>&#x2013;</xsl:text>
-</xsl:template>
-
-<!-- Unicode Character 'EM DASH' (U+2014) -->
-<!-- Liblouis: 6-36                       -->
-<xsl:template name="mdash-character">
-    <xsl:text>&#x2014;</xsl:text>
-</xsl:template>
-
-<!-- Unicode Character 'COPYRIGHT SIGN' (U+00A9) -->
-<!-- Liblouis: 45-14                             -->
-<xsl:template name="copyright-character">
-    <xsl:text>&#x00A9;</xsl:text>
-</xsl:template>
-
-<!-- Unicode Character 'REGISTERED SIGN' (U+00AE) -->
-<!-- Liblouis: 45-1235                            -->
-<xsl:template name="registered-character">
-    <xsl:text>&#x00AE;</xsl:text>
-</xsl:template>
-
-<!-- Unicode Character 'TRADE MARK SIGN' (U+2122) -->
-<!-- Liblouis: 45-2345                            -->
-<xsl:template name="trademark-character">
-    <xsl:text>&#x2122;</xsl:text>
-</xsl:template>
-
-<!-- Unicode Character 'DEGREE SIGN' (U+00B0) -->
-<!-- Liblouis: 45-245                         -->
-<xsl:template name="degree-character">
-    <xsl:text>&#x00B0;</xsl:text>
+<!-- Each character reads the Unicode column of the representation -->
+<!-- table in  pretext-common.xsl.  A "braille" column entry       -->
+<!-- substitutes where liblouis lacks the true code point; the      -->
+<!-- entry "none" marks a character outside this repertoire,        -->
+<!-- which warns, keeping the gap visible.                          -->
+<!--                                                                -->
+<!-- Cells described in the liblouis table, for each Unicode        -->
+<!-- character rendered here:                                       -->
+<!--                                                                -->
+<!--   nbsp (U+00A0): passed through in-kind; used in the           -->
+<!--     manufacture of a cross-reference, we will want to strip    -->
+<!--     just before it ends up in BRF                              -->
+<!--   ndash (U+2013): 6-36                                         -->
+<!--   mdash (U+2014): 6-36                                         -->
+<!--   thin-space (U+2009): 0, a braille space                     -->
+<!--   copyright (U+00A9): 45-14                                    -->
+<!--   registered (U+00AE): 45-1235                                 -->
+<!--   trademark (U+2122): 45-2345                                  -->
+<!--   degree (U+00B0): 45-245                                      -->
+<!--   prime (U+2032): 2356                                         -->
+<!--   dblprime (U+2033): 2356-2356                                 -->
+<!--   langle (U+3008): 4-126                                       -->
+<!--   rangle (U+3009): 4-345                                       -->
+<!--   ellipsis (U+2026): 256-256-256; [BANA-2016] Appendix G,      -->
+<!--     UEB is three periods/256                                   -->
+<!--   midpoint (U+00B7): 4-16                                      -->
+<!--   swungdash: faked with TILDE (U+007E)                         -->
+<!--   pilcrow (U+00B6): 45-1234                                    -->
+<!--   section-mark (U+00A7): 45-234                                -->
+<!--   minus (U+2212): 5-36                                         -->
+<!--   times (U+00D7): 5-236                                        -->
+<!--   solidus: faked with SOLIDUS (U+002F)                         -->
+<!--   obelus (U+00F7): 5-34                                        -->
+<!--   plusminus (U+00B1): 456-235                                  -->
+<xsl:template match="char" mode="character">
+    <xsl:choose>
+        <xsl:when test="@braille = 'none'">
+            <xsl:call-template name="warn-unimplemented-character">
+                <xsl:with-param name="char-name" select="@name"/>
+            </xsl:call-template>
+        </xsl:when>
+        <xsl:when test="@braille">
+            <xsl:value-of select="@braille"/>
+        </xsl:when>
+        <xsl:otherwise>
+            <xsl:value-of select="@unicode"/>
+        </xsl:otherwise>
+    </xsl:choose>
 </xsl:template>
 
-<!-- Unicode Character 'PRIME' (U+2032) -->
-<!-- Liblouis: 2356                     -->
-<xsl:template name="prime-character">
-    <xsl:text>&#x2032;</xsl:text>
+<!-- the CJK angle brackets: the liblouis table defines cells -->
+<!-- (above) only for these, not for the mathematical pair    -->
+<!-- carried by the representation table                      -->
+<xsl:template match="char[@name = 'langle']" mode="character">
+    <xsl:text>&#x3008;</xsl:text>
 </xsl:template>
-
-<!-- Unicode Character 'DOUBLE PRIME' (U+2033) -->
-<!-- Liblouis: 2356-2356                       -->
-<xsl:template name="dblprime-character">
-    <xsl:text>&#x2033;</xsl:text>
+<xsl:template match="char[@name = 'rangle']" mode="character">
+    <xsl:text>&#x3009;</xsl:text>
 </xsl:template>
 
 <!-- Unicode Character 'LEFT SINGLE QUOTATION MARK' (U+2018) -->
@@ -1344,80 +1583,6 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
     <xsl:text>&#x201D;</xsl:text>
 </xsl:template>
 
-<!-- Unicode Character 'LEFT ANGLE BRACKET' (U+3008) -->
-<!-- Liblouis: 4-126                                 -->
-<xsl:template name="langle-character">
-    <xsl:text>&#x3008;</xsl:text>
-</xsl:template>
-
-<!-- Unicode Character 'RIGHT ANGLE BRACKET' (U+3009) -->
-<!-- Liblouis: 4-345                                  -->
-<xsl:template name="rangle-character">
-    <xsl:text>&#x3009;</xsl:text>
-</xsl:template>
-
-<!-- Unicode Character 'HORIZONTAL ELLIPSIS' (U+2026) -->
-<!-- Liblouis: 256-256-256                            -->
-<!-- [BANA-2016] Appendix G, UEB is three periods/256 -->
-<xsl:template name="ellipsis-character">
-    <xsl:text>&#x2026;</xsl:text>
-</xsl:template>
-
-<!-- Unicode Character 'MIDDLE DOT' (U+00B7) -->
-<!-- Liblouis: 4-16                          -->
-<xsl:template name="midpoint-character">
-    <xsl:text>&#x00B7;</xsl:text>
-</xsl:template>
-
-<!-- Unicode Character 'SWUNG DASH' (U+2053) -->
-<!-- instead faking it with                  -->
-<!-- Unicode Character 'TILDE' (U+007E)      -->
-<xsl:template name="swungdash-character">
-    <xsl:text>&#x007E;</xsl:text>
-</xsl:template>
-
-<!-- Unicode Character 'PILCROW SIGN' (U+00B6) -->
-<!-- Liblouis: 45-1234                         -->
-<xsl:template name="pilcrow-character">
-    <xsl:text>&#x00B6;</xsl:text>
-</xsl:template>
-
-<!-- Unicode Character 'SECTION SIGN' (U+00A7) -->
-<!-- Liblouis: 45-234                          -->
-<xsl:template name="section-mark-character">
-    <xsl:text>&#x00A7;</xsl:text>
-</xsl:template>
-
-<!-- Unicode Character 'MINUS SIGN' (U+2212) -->
-<!-- Liblouis: 5-36                          -->
-<xsl:template name="minus-character">
-    <xsl:text>&#x2212;</xsl:text>
-</xsl:template>
-
-<!-- Unicode Character 'MULTIPLICATION SIGN' (U+00D7) -->
-<!-- Liblouis: 5-236                                  -->
-<xsl:template name="times-character">
-    <xsl:text>&#x00D7;</xsl:text>
-</xsl:template>
-
-<!-- Unicode Character 'FRACTION SLASH' (U+2044) -->
-<!-- instead faking it with                      -->
-<!-- Unicode Character 'SOLIDUS' (U+002F)        -->
-<xsl:template name="solidus-character">
-    <xsl:text>&#x002F;</xsl:text>
-</xsl:template>
-
-<!-- Unicode Character 'DIVISION SIGN' (U+00F7) -->
-<!-- Liblouis: 5-34                             -->
-<xsl:template name="obelus-character">
-    <xsl:text>&#x00F7;</xsl:text>
-</xsl:template>
-
-<!-- Unicode Character 'PLUS-MINUS SIGN' (U+00B1) -->
-<!-- Liblouis: 456-235                            -->
-<xsl:template name="plusminus-character">
-    <xsl:text>&#x00B1;</xsl:text>
-</xsl:template>
 
 <!-- Icons -->
 <!-- Just the four arrows, unsure about the rest -->
@@ -1438,7 +1603,7 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
             <xsl:text>&#x2193;</xsl:text>
         </xsl:when>
         <xsl:otherwise>
-            <xsl:message>WARNING:  &quot;icon&quot; with @name attribute value "<xsl:value-of select="@name"/>" does not have an implementation for braille.</xsl:message>
+            <xsl:message>PTX:WARNING: &quot;icon&quot; with @name attribute value "<xsl:value-of select="@name"/>" does not have an implementation for braille.</xsl:message>
         </xsl:otherwise>
     </xsl:choose>
 </xsl:template>
@@ -1554,8 +1719,11 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 <xsl:template match="m[not(contains(math-nemeth, '&#xa;'))]">
     <!-- Unicode braille cells from Speech Rule Engine (SRE)   -->
     <!-- Not expecting any markup, so "value-of" is everything -->
+    <!-- Possibly converted to BRF ASCII symbols ("early")     -->
     <xsl:variable name="raw-braille">
-        <xsl:value-of select="math-nemeth"/>
+        <xsl:call-template name="brf-symbols-filter">
+            <xsl:with-param name="text" select="math-nemeth"/>
+        </xsl:call-template>
     </xsl:variable>
     <!-- We investigate actual source for very simple math   -->
     <!-- such as one-letter variable names as Latin letters  -->
@@ -1614,6 +1782,8 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 </xsl:template>
 
 <xsl:template match="m[contains(math-nemeth, '&#xa;')]|md">
+    <!-- Lines are trimmed, and possibly converted to BRF ASCII -->
+    <!-- symbols ("early"), one at a time, below                -->
     <xsl:variable name="nemeth">
         <xsl:value-of select="math-nemeth"/>
         <xsl:text>&#xa;</xsl:text>
@@ -1635,11 +1805,20 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
         <!-- done, nothing left to work on -->
         <xsl:when test="$display-math = ''"/>
         <xsl:otherwise>
-            <!-- first line into a segment -->
+            <!-- first line into a segment: trailing blank cells -->
+            <!-- trimmed first, and then a possible conversion to -->
+            <!-- BRF ASCII symbols ("early"), line by line, so a  -->
+            <!-- line of print residue rides along as Unicode     -->
+            <!-- without disqualifying its neighbors              -->
             <segment>
-                <xsl:call-template name="trim-nemeth-trailing-whitespace">
-                   <xsl:with-param name="text" select="substring-before($display-math, '&#xa;')"/>
-               </xsl:call-template>
+                <xsl:variable name="trimmed">
+                    <xsl:call-template name="trim-nemeth-trailing-whitespace">
+                        <xsl:with-param name="text" select="substring-before($display-math, '&#xa;')"/>
+                    </xsl:call-template>
+                </xsl:variable>
+                <xsl:call-template name="brf-symbols-filter">
+                    <xsl:with-param name="text" select="$trimmed"/>
+                </xsl:call-template>
             </segment>
             <!-- recurse on remainder -->
             <xsl:call-template name="segmentize-display-math">
@@ -1985,9 +2164,17 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 <!-- A paragraph without "displays" is straightforward and -->
 <!-- we can bypass the more complicated procedure next.    -->
 <xsl:template match="p">
+    <!-- Inside a list item ($list-runover is a number, not empty)  -->
+    <!-- every line of the paragraph belongs at the list's runover  -->
+    <!-- margin [BANA-2016, 8.5.1(b)]; the melded run-in marker     -->
+    <!-- supplies the first paragraph's first-line position.        -->
+    <xsl:param name="list-runover" select="''"/>
     <segment>
         <xsl:attribute name="indentation">
             <xsl:choose>
+                <xsl:when test="not($list-runover = '')">
+                    <xsl:value-of select="$list-runover"/>
+                </xsl:when>
                 <xsl:when test="@pi:indent = 'no'">
                     <xsl:text>0</xsl:text>
                 </xsl:when>
@@ -1996,6 +2183,11 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
                 </xsl:otherwise>
             </xsl:choose>
         </xsl:attribute>
+        <xsl:if test="not($list-runover = '')">
+            <xsl:attribute name="runover">
+                <xsl:value-of select="$list-runover"/>
+            </xsl:attribute>
+        </xsl:if>
         <xsl:apply-templates select="node()"/>
     </segment>
 </xsl:template>
@@ -2007,6 +2199,11 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 <!-- Note: this is derived from a similar template in the HTML        -->
 <!-- conversion.                                                      -->
 <xsl:template match="p[ol|ul|dl|m[contains(math-nemeth, '&#xa;')]|md|cd]">
+    <!-- Inside a list item ($list-runover is a number, not empty)  -->
+    <!-- every piece of the paragraph belongs at the list's runover -->
+    <!-- margin [BANA-2016, 8.5.1(b)]; nested lists among the       -->
+    <!-- displays compute their own, deeper, margins.               -->
+    <xsl:param name="list-runover" select="''"/>
     <!-- will later loop over displays within paragraph      -->
     <!-- match guarantees at least one for $initial variable -->
     <xsl:variable name="displays" select="ul|ol|dl|m[contains(math-nemeth, '&#xa;')]|md|cd" />
@@ -2019,7 +2216,22 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
         <xsl:apply-templates select="$initial"/>
     </xsl:variable>
     <xsl:if test="not(normalize-space($initial-content) = '')">
-        <segment indentation="2">
+        <segment>
+            <xsl:attribute name="indentation">
+                <xsl:choose>
+                    <xsl:when test="not($list-runover = '')">
+                        <xsl:value-of select="$list-runover"/>
+                    </xsl:when>
+                    <xsl:otherwise>
+                        <xsl:text>2</xsl:text>
+                    </xsl:otherwise>
+                </xsl:choose>
+            </xsl:attribute>
+            <xsl:if test="not($list-runover = '')">
+                <xsl:attribute name="runover">
+                    <xsl:value-of select="$list-runover"/>
+                </xsl:attribute>
+            </xsl:if>
             <xsl:apply-templates select="$initial"/>
         </segment>
     </xsl:if>
@@ -2043,6 +2255,14 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
                 </xsl:variable>
                 <xsl:if test="not(normalize-space($common-content) = '')">
                     <segment>
+                        <xsl:if test="not($list-runover = '')">
+                            <xsl:attribute name="indentation">
+                                <xsl:value-of select="$list-runover"/>
+                            </xsl:attribute>
+                            <xsl:attribute name="runover">
+                                <xsl:value-of select="$list-runover"/>
+                            </xsl:attribute>
+                        </xsl:if>
                         <xsl:apply-templates select="$common"/>
                     </segment>
                 </xsl:if>
@@ -2054,6 +2274,14 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
                 </xsl:variable>
                 <xsl:if test="not(normalize-space($final-content) = '')">
                     <segment>
+                        <xsl:if test="not($list-runover = '')">
+                            <xsl:attribute name="indentation">
+                                <xsl:value-of select="$list-runover"/>
+                            </xsl:attribute>
+                            <xsl:attribute name="runover">
+                                <xsl:value-of select="$list-runover"/>
+                            </xsl:attribute>
+                        </xsl:if>
                         <xsl:apply-templates select="$rightward"/>
                     </segment>
                 </xsl:if>
@@ -2078,9 +2306,16 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 
 <!-- The "titlepage" and front "colophon" should be mined to form front -->
 <!-- matter material in the right places, etc.  We kill them for now so -->
-<!-- we don't see their children being overlooked.                      -->
+<!-- we don't see their children being overlooked.  "bibinfo" is pure   -->
+<!-- metadata (authors, date, edition), mined by a title page when one  -->
+<!-- is implemented; unhandled, its text leaks into the output stream   -->
+<!-- with no anchor, so it is silenced the same way.                    -->
 <xsl:template match="titlepage"/>
 <xsl:template match="frontmatter/colophon"/>
+<!-- TODO: a braille title page [BANA-2016, 2.3] should mine     -->
+<!-- "bibinfo" (title, authors, date, edition) rather than       -->
+<!-- leaving it silenced here.                                   -->
+<xsl:template match="bibinfo"/>
 
 <!-- Many pieces of the "backmatter" have templates designed for divisions -->
 <xsl:template match="backmatter">
@@ -2117,11 +2352,19 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 <!-- structures.  We report AND include a textual place holder.       -->
 
 <xsl:template match="notation-list">
-    <xsl:text>NOTATIONLIST</xsl:text>
+    <segment>NOTATIONLIST</segment>
 </xsl:template>
 
+<!-- A real braille index awaits future work; until then the     -->
+<!-- omission is announced in place, rather than silent.  (The    -->
+<!-- prior placeholder was bare text, which the renderer cannot   -->
+<!-- anchor, so nothing at all appeared.)                         -->
 <xsl:template match="index-list">
-    <xsl:text>INDEXLIST</xsl:text>
+    <xsl:apply-templates select="." mode="transcriber-note">
+        <xsl:with-param name="message">
+            <xsl:text>The index is not reproduced in this braille edition.</xsl:text>
+        </xsl:with-param>
+    </xsl:apply-templates>
 </xsl:template>
 
 <xsl:template match="poem">
@@ -2146,12 +2389,6 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
         </xsl:call-template>
     </xsl:if>
     <!--  -->
-    <xsl:if test="//index-list">
-        <xsl:call-template name="missing-implementation">
-            <xsl:with-param name="element" select="'index-list'"/>
-            <xsl:with-param name="ntimes" select="count(//index-list)"/>
-        </xsl:call-template>
-    </xsl:if>
     <xsl:if test="//poem">
         <xsl:call-template name="missing-implementation">
             <xsl:with-param name="element" select="'poem'"/>
@@ -2179,11 +2416,11 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
     <xsl:param name="element"/>
     <xsl:param name="ntimes"/>
 
-    <xsl:message>Unimplemented: <xsl:value-of select="$element"/> (<xsl:value-of select="$ntimes"/> times)</xsl:message>
+    <xsl:message>PTX:INFO: Unimplemented: <xsl:value-of select="$element"/> (<xsl:value-of select="$ntimes"/> times)</xsl:message>
 </xsl:template>
 
 <xsl:template match="*" mode="overlooked">
-    <xsl:message>Overlooked: <xsl:value-of select="local-name()"/></xsl:message>
+    <xsl:message>PTX:INFO: Overlooked: <xsl:value-of select="local-name()"/></xsl:message>
 </xsl:template>
 
 <!-- *Every* element needs an implementation, or it ends up here being -->
@@ -2245,5 +2482,24 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
     </segment>
 </xsl:template>
 
+<!-- ############## -->
+<!-- Invalid Source -->
+<!-- ############## -->
+
+<!-- Constructions that violate the PreTeXt schema receive an error   -->
+<!-- message describing the violation, and leave a placeholder in the -->
+<!-- output, rather than being accommodated.  Generated content       -->
+<!-- (STACK static representations) is the known supplier: a "p"      -->
+<!-- within a "p", an "image" within a "p", and "div" (an HTML        -->
+<!-- element, not PreTeXt at all).                                    -->
+<!--                                                                  -->
+<!-- N.B. these templates are deliberately LAST in this stylesheet:   -->
+<!-- a nested "p" can also match the display-splitting template for   -->
+<!-- "p" at equal priority, and placement here settles the conflict   -->
+<!-- in favor of the error.                                           -->
+<xsl:template match="p/p|p/image|div">
+    <xsl:message>PTX:ERROR:   the braille conversion has encountered source that is not valid PreTeXt (a "<xsl:value-of select="local-name()"/>" element within a "<xsl:value-of select="local-name(parent::*)"/>"); a placeholder appears in the output in its place</xsl:message>
+    <xsl:text>[INVALID SOURCE]</xsl:text>
+</xsl:template>
 
 </xsl:stylesheet>