@pretextbook/pretext-html 0.18.0 → 0.18.1

package/assets/upstream.json

@@ -1,7 +1,7 @@
 {
   "source": {
     "repository": "PreTeXtBook/pretext",
-    "ref": "ee0a7e135e3346f0b0c6192822d6942424cb4af0"
+    "ref": "da193419f0746242287b2358094a496029ca9671"
   },
-  "refreshed": "2026-10-01T06:28:22.049Z"
+  "refreshed": "2026-10-24T03:13:47.656Z"
 }

package/assets/xsl/AGENTS.md

@@ -0,0 +1,34 @@
+<!--********************************************************************
+Copyright (C) 2026  Robert A. Beezer
+
+This file is part of PreTeXt.
+
+PreTeXt is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 2 or version 3 of the
+License (at your option).
+
+PreTeXt is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
+*****************************************************************-->
+
+# Stylesheets
+
+- Use Extensible Stylesheet Language Transformations (XSLT) 1.0 with Extensions to XSLT (EXSLT) only. Declare each EXSLT namespace you use, and list its prefix in `extension-element-prefixes` whether you use its extension elements, such as `exsl:document`, or only its functions: a prefix that is declared but not listed is copied onto literal result elements as a namespace declaration (`pretext-common.xsl` declares and lists `exsl`, `date`, `str`, and `dyn`). libxslt is the reference processor, through `lxml` in `pretext/pretext`.
+- PreTeXt entry stylesheets load `entities.ent` as an external parameter entity in a `DOCTYPE` (document type declaration). Add shared `-LIKE` and `-FILTER` unions there; its comments identify lists that mirror the schema or require a Guide update.
+- Project stylesheets import one format entry point, and every entry point reaches `pretext-common.xsl` through its imports. `pretext-html.xsl` directly imports `publisher-variables.xsl`, `pretext-assembly.xsl`, and `pretext-common.xsl`; publisher variables and assembly are designed to travel together. Treat `-common` stylesheets as libraries rather than entry points.
+- Obtain the identification value of an element by applying `mode="unique-id"` to it, never by reading the attribute that holds it; the template in `pretext-common.xsl` is the one place that knows how the value is stored. `mode="assembly-id"` yields a different value, which belongs to `pretext-assembly.xsl` and the `extract-*.xsl` stylesheets that feed it. A conversion never reads that one: the two values agree for most elements but not for all.
+- Do not put a `priority` attribute on a template when a more specific match pattern, a mode, or import precedence will settle which template applies. Where nothing else will, a comment beside the template gives the reason.
+- Prefix internal logic defects with `PTX:BUG:`. Use `PTX:WARNING:`, `PTX:ERROR:`, and `PTX:FATAL:` according to the [coding chapter](../doc/guide/developer/coding.xml).
+- A message that an author will read describes the outcome and does not name the `pretext/pretext` script, since the PreTeXt command-line interface (CLI) can do the same work. A comment may name the script freely.
+- Write a comment of several lines as single-line comments, one `<!-- ... -->` per line, with every closing `-->` in the same column.
+- A publisher option change pairs the implementing stylesheet with `../schema/publication-schema.xml`, regenerated schemas, a Guide entry, and an example. A theme option also updates `html-theme-option-list` in `publisher-variables.xsl`.
+- Follow the [localization contract](localizations/README.md): add new string identifiers to `en-US.xml`, and register each new language file in `localizations.xml`. Verify localization changes manually.
+- Follow the [support-file procedure](support/README.md) when updating Runestone Services versions.
+- Copy the copyright header from a sibling onto every new `.xsl` file.
+- Run `(cd tests && xsltproc pretext-text-utilities-test.xsl null.xml)`. Add tests there for new low-level text utilities.

package/assets/xsl/entities.ent

@@ -183,9 +183,11 @@
 <!ENTITY SOLUTION-LIKE "hint|answer|solution">
 <!ENTITY SOLUTION-FILTER "self::hint or self::answer or self::solution">
 
-<!-- appendages of OPENPROBLEM-LIKE -->
-<!ENTITY DISCUSSION-LIKE "context|discussion|opinion|status|suggestion">
-<!ENTITY DISCUSSION-FILTER "self::context or self::discussion or self::opinion or self::status or self::suggestion">
+<!-- appendages of OPENPROBLEM-LIKE                                    -->
+<!-- A "status" is also a field of a bibliographic entry, so this one  -->
+<!-- is recognized by its parent: an OPENPROBLEM-LIKE, or one's "task" -->
+<!ENTITY DISCUSSION-LIKE "context|discussion|opinion|status[parent::*[&OPENPROBLEM-FILTER;] or parent::task]|suggestion">
+<!ENTITY DISCUSSION-FILTER "self::context or self::discussion or self::opinion or (self::status and (parent::*[&OPENPROBLEM-FILTER;] or parent::task)) or self::suggestion">
 
 <!-- Elements the schema gives text-only content: no PreTeXt markup is   -->
 <!-- permitted inside them, whether because they are verbatim (code, a   -->

package/assets/xsl/extract-biblio-csl.xsl

@@ -19,15 +19,17 @@ You should have received a copy of the GNU General Public License
 along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
 *********************************************************************-->
 
-<!-- This stylesheet locates video/@youtube elements and -->
-<!-- prepares a Python dictionary necessary to extract a -->
-<!-- thumbnail for each video from the YouTube servers   -->
+<!-- This stylesheet locates the "biblio" of a back matter     -->
+<!-- "references", and the "xref" that cite them, and writes   -->
+<!-- the first as CSL-JSON and the second as lists of targets, -->
+<!-- which a CSL processor needs to format both                -->
 
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
                 xmlns:xml="http://www.w3.org/XML/1998/namespace"
                 xmlns:pi="http://pretextbook.org/2020/pretext/internal"
+                xmlns:exsl="http://exslt.org/common"
                 xmlns:str="http://exslt.org/strings"
-                exclude-result-prefixes="str"
+                exclude-result-prefixes="exsl str"
 >
 <!-- exclude-result-prefixes="pi" -->
 
@@ -103,12 +105,9 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
     <xsl:message>PTX:BUG: PreTeXt "biblio" markup using a "<xsl:value-of select="local-name()"/>" element is not implemented</xsl:message>
 </xsl:template>
 
-<!-- Gross JSON array structure, duplicate an ID for the division -->
+<!-- Gross JSON array structure -->
 <xsl:template match="backmatter/references" mode="biblio-to-json">
     <xsl:element name="biblio-csl" namespace="http://pretextbook.org/2020/pretext/internal">
-        <xsl:attribute name="biblio-id">
-            <xsl:apply-templates select="." mode="assembly-id"/>
-        </xsl:attribute>
         <xsl:text>[&#xa;</xsl:text>
         <xsl:apply-templates select="biblio" mode="biblio-to-json"/>
         <xsl:text>&#xa;]</xsl:text>
@@ -119,9 +118,11 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
 <!-- TODO: refine "select" to only match to-level possibilities -->
 <xsl:template match="biblio" mode="biblio-to-json">
     <xsl:text>{&#xa;</xsl:text>
-    <xsl:apply-templates select="@xml:id|@type" mode="biblio-to-json"/>
-    <xsl:apply-templates select="*" mode="biblio-to-json"/>
-     <xsl:text>&#xa;}</xsl:text>
+    <xsl:call-template name="json-members">
+        <xsl:with-param name="nodes" select="@xml:id|@type|*"/>
+        <xsl:with-param name="separator" select="',&#xa;'"/>
+    </xsl:call-template>
+    <xsl:text>&#xa;}</xsl:text>
     <xsl:if test="following-sibling::biblio">
         <xsl:text>,&#xa;</xsl:text>
         <!-- intra-biblio visual formatting help -->
@@ -129,6 +130,37 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
     </xsl:if>
 </xsl:template>
 
+<!-- The members of a JSON object are the conversions of "nodes", with  -->
+<!-- "separator" between one member and the next.  A node that converts -->
+<!-- to nothing (markup not implemented, caught above) is no member, so -->
+<!-- the separators are right whichever nodes those are.  Each template -->
+<!-- for a member writes the member alone, and nothing after it.        -->
+<!-- TODO: "xml-to-json.xsl" converts a description of JSON, made of    -->
+<!-- elements, and supplies the separators and the quoting; built on    -->
+<!-- it, this template and the quoting in each template could go.       -->
+<xsl:template name="json-members">
+    <xsl:param name="nodes"/>
+    <xsl:param name="separator"/>
+    <xsl:variable name="members-rtf">
+        <xsl:for-each select="$nodes">
+            <xsl:variable name="json">
+                <xsl:apply-templates select="." mode="biblio-to-json"/>
+            </xsl:variable>
+            <xsl:if test="not($json = '')">
+                <member>
+                    <xsl:value-of select="$json"/>
+                </member>
+            </xsl:if>
+        </xsl:for-each>
+    </xsl:variable>
+    <xsl:for-each select="exsl:node-set($members-rtf)/member">
+        <xsl:value-of select="."/>
+        <xsl:if test="not(position() = last())">
+            <xsl:value-of select="$separator"/>
+        </xsl:if>
+    </xsl:for-each>
+</xsl:template>
+
 <!-- Attributes -->
 <!-- Happy accident that local-name(@xml:id) is JSON "id" key for CSL -->
 
@@ -151,15 +183,14 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
             <xsl:value-of select="."/>
         </xsl:with-param>
     </xsl:call-template>
-    <xsl:text>",&#xa;</xsl:text>
+    <xsl:text>"</xsl:text>
 </xsl:template>
 
-<!-- Simple string fields to key/value pair -->
-<!-- NB: in the order presented in CSL-JSON schema, except as noted.                  -->
-<!-- NB: simple fields for parts of a name are later, and grouped together.           -->
-<!-- NB: simple fields for alternate date model are at the end, and grouped together. -->
-<!-- TODO: many more, from "abstract" to "year-suffix", plus for names and dates.     -->
-<xsl:template match="publisher|publisher-place|page|volume|title|collection-title|page-first|number-of-pages|URL|name/family|name/given|name/static-ordering|season|circa" mode="biblio-to-json">
+<!-- Simple string fields to key/value pair                                       -->
+<!-- NB: in the order presented in CSL-JSON schema, except as noted.              -->
+<!-- NB: simple fields for parts of a name are later, and grouped together.       -->
+<!-- TODO: many more, from "abstract" to "year-suffix", plus for names and dates. -->
+<xsl:template match="archive|archive_location|chapter-number|collection-number|collection-title|container-title|container-title-short|DOI|edition|event|genre|ISBN|ISSN|issue|number|number-of-pages|number-of-volumes|page|page-first|publisher|publisher-place|status|title|URL|version|volume|name/family|name/given|name/dropping-particle|name/non-dropping-particle|name/suffix|name/static-ordering|name/literal" mode="biblio-to-json">
     <xsl:text>"</xsl:text>
     <xsl:value-of select="local-name()"/>
     <xsl:text>"</xsl:text>
@@ -175,18 +206,6 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
         </xsl:with-param>
     </xsl:call-template>
     <xsl:text>"</xsl:text>
-    <xsl:if test="following-sibling::*">
-        <xsl:text>,</xsl:text>
-        <xsl:choose>
-            <!-- top-label get a newline, else a space -->
-            <xsl:when test="parent::biblio">
-                <xsl:text>&#xa;</xsl:text>
-            </xsl:when>
-            <xsl:otherwise>
-                <xsl:text> </xsl:text>
-            </xsl:otherwise>
-        </xsl:choose>
-    </xsl:if>
 </xsl:template>
 
 <!-- ############### -->
@@ -196,7 +215,7 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
 <!-- Structured name variables. -->
 <!-- TODO: see  "$ref": "#/definitions/name-variable"  in CSL-JSON -->
 <!-- schema to identify many more.  "author" through "translator". -->
-<xsl:template match="biblio/author|biblio/editor" mode="biblio-to-json">
+<xsl:template match="biblio/author|biblio/editor|biblio/translator" mode="biblio-to-json">
     <xsl:text>"</xsl:text>
     <xsl:value-of select="local-name()"/>
     <xsl:text>"</xsl:text>
@@ -204,9 +223,6 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
     <xsl:text>[</xsl:text>
     <xsl:apply-templates select="name" mode="biblio-to-json"/>
     <xsl:text>]</xsl:text>
-    <xsl:if test="following-sibling::*">
-        <xsl:text>,&#xa;</xsl:text>
-    </xsl:if>
 </xsl:template>
 
 <!-- Name structure -->
@@ -216,7 +232,10 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
     <!--     family, given, suffix, etc.                -->
     <!-- They will use the simple template above, where -->
     <!-- fields are qualified with the "name" parent    -->
-    <xsl:apply-templates select="*" mode="biblio-to-json"/>
+    <xsl:call-template name="json-members">
+        <xsl:with-param name="nodes" select="*"/>
+        <xsl:with-param name="separator" select="', '"/>
+    </xsl:call-template>
     <xsl:text>}</xsl:text>
     <xsl:if test="following-sibling::name">
         <xsl:text>, </xsl:text>
@@ -230,7 +249,7 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
 <!-- Structured date variables. -->
 <!-- TODO: see  "$ref": "#/definitions/date-variable"  in CSL-JSON -->
 <!-- schema to identify many more. "accessed" through "submitted". -->
-<xsl:template match="submitted|issued" mode="biblio-to-json">
+<xsl:template match="accessed|issued" mode="biblio-to-json">
     <xsl:text>"</xsl:text>
     <xsl:value-of select="local-name()"/>
     <xsl:text>"</xsl:text>
@@ -244,18 +263,6 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
         <xsl:text>]</xsl:text>
     </xsl:if>
     <xsl:text>&#xa;}</xsl:text>
-    <xsl:if test="following-sibling::*">
-        <xsl:text>,</xsl:text>
-        <xsl:choose>
-            <!-- likely always first test? -->
-            <xsl:when test="parent::biblio">
-                <xsl:text>&#xa;</xsl:text>
-            </xsl:when>
-            <xsl:otherwise>
-                <xsl:text> </xsl:text>
-            </xsl:otherwise>
-        </xsl:choose>
-    </xsl:if>
 </xsl:template>
 
 <!-- An array of length 1 to 3, with spaces after commas -->