@pretextbook/pretext-html 0.7.0 → 0.8.0

package/assets/xsl/publisher-variables.xsl

@@ -1156,7 +1156,7 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
 <!-- while a trailing slash will be reliably added if                     -->
 <!--     (a) not present in publisher file specification                  -->
 <!--     (b) the path is not empty                                        -->
-<!-- The external directory is a fact of the source (a different       -->
+<!-- The external directory is a property of the source (a different    -->
 <!-- directory of files is a different document), so its declaration    -->
 <!-- is "directories/@external" within "docinfo" (2026-07-30).  The     -->
 <!-- publication file "source/directories/@external" is deprecated but  -->
@@ -1165,6 +1165,13 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
 <!-- directory variables and the tree behind  $docinfo  does not exist  -->
 <!-- yet at that point (referencing it is a circular definition).       -->
 <xsl:variable name="external-directory-source">
+    <!-- an empty declaration is an error, not an election -->
+    <xsl:if test="$version-docinfo/directories/@external = ''">
+        <xsl:message terminate="yes">PTX:FATAL:   the value of "directories/@external" within "docinfo" must be nonempty</xsl:message>
+    </xsl:if>
+    <xsl:if test="$publication/source/directories/@external = ''">
+        <xsl:message terminate="yes">PTX:FATAL:   the value of source/directories/@external in the publisher file must be nonempty</xsl:message>
+    </xsl:if>
     <xsl:variable name="raw-input">
         <xsl:choose>
             <xsl:when test="$version-docinfo/directories/@external">
@@ -1174,7 +1181,7 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
                 <xsl:value-of select="$version-docinfo/directories/@external"/>
             </xsl:when>
             <xsl:when test="$publication/source/directories/@external">
-                <xsl:message>PTX:DEPRECATE: (2026-07-30) the external directory is a fact of the source, and is now declared with a "directories/@external" attribute within "docinfo".  The publication file entry "source/directories/@external" is honored meanwhile, but please relocate it.</xsl:message>
+                <xsl:message>PTX:DEPRECATE: (2026-07-30) the external directory is a property of your source, and is now declared with a "directories/@external" attribute within "docinfo".  The publication file entry "source/directories/@external" is honored meanwhile, but please relocate it.</xsl:message>
                 <xsl:value-of select="$publication/source/directories/@external"/>
             </xsl:when>
             <xsl:otherwise/>
@@ -1200,104 +1207,50 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
     </xsl:choose>
 </xsl:variable>
 
-<!-- Historically this was given by the "images" directory as a default, -->
-<!-- and it seems almost every author just ran with this.                -->
+<!-- The generated directory is machine-owned, so it is defaultable:  -->
+<!-- an undeclared location is the directory "generated", beside the  -->
+<!-- source.  (Historically an unmanaged scheme fell back to the      -->
+<!-- "images" directory; managed directories are now the only scheme.)-->
 <xsl:variable name="generated-directory-source">
-    <xsl:variable name="raw-input" select="$publication/source/directories/@generated"/>
-    <xsl:choose>
-        <xsl:when test="$b-managed-directories">
-            <xsl:choose>
-                <xsl:when test="substring($raw-input, 1, 1) = '/'">
-                    <xsl:message>PTX:FALLBACK:   a generated-image directory (source/directories/@generated in the publisher file) must be a relative path and not begin with "/" as in "<xsl:value-of select="$raw-input"/>".  Proceeding with the default, which is an empty string, and may lead to unexpected results.</xsl:message>
-                    <xsl:text/>
-                </xsl:when>
-                <!-- trailing path separator is good -->
-                <xsl:when test="substring($raw-input, string-length($raw-input), 1) = '/'">
-                    <xsl:value-of select="$raw-input"/>
-                </xsl:when>
-                <!-- if there is substance, we need to add a trailing slash -->
-                <xsl:when test="string-length($raw-input) > 0">
-                    <xsl:value-of select="concat($raw-input, '/')"/>
-                </xsl:when>
-                <!-- specification must be empty, so we leave it that way -->
-                <xsl:otherwise/>
-            </xsl:choose>
-        </xsl:when>
-        <!-- Should issue a deprecation warning (elsewhere) for this.    -->
-        <!-- directory.images *is* defined elsewhere in this stylesheet, -->
-        <!-- and defaults to "images", but does not have a slash, which  -->
-        <!-- is presumed for the $generated-directory variable           -->
-        <xsl:otherwise>
-            <xsl:value-of select="concat($directory.images, '/')"/>
-        </xsl:otherwise>
-    </xsl:choose>
-</xsl:variable>
-
-<!-- For backward-compatibility, we want to know if the collection of  -->
-<!-- generated images is structured by their production method (newer) -->
-<!-- or not (older, historical).  So we create a boolean based on the  -->
-<!-- presence of the publisher file specification.                     -->
-<xsl:variable name="managed-directories">
-    <xsl:if test="$version-docinfo/directories/@external = ''">
-        <xsl:message terminate="yes">PTX:FATAL:   the value of "directories/@external" within "docinfo" must be nonempty</xsl:message>
-    </xsl:if>
-    <xsl:if test="$publication/source/directories/@external = ''">
-        <xsl:message terminate="yes">PTX:FATAL:   the value of source/directories/@external in the publisher file must be nonempty</xsl:message>
-    </xsl:if>
     <xsl:if test="$publication/source/directories/@generated = ''">
         <xsl:message terminate="yes">PTX:FATAL:   the value of source/directories/@generated in the publisher file must be nonempty</xsl:message>
     </xsl:if>
-    <!-- The external directory may be declared in "docinfo" (preferred) -->
-    <!-- or the publication file (deprecated, honored); the generated    -->
-    <!-- directory is a publication file entry.  Management requires an  -->
-    <!-- external declaration, from either home, together with the       -->
-    <!-- generated declaration.                                          -->
-    <xsl:variable name="b-has-external" select="boolean($version-docinfo/directories/@external) or boolean($publication/source/directories/@external)"/>
+    <xsl:variable name="raw-input">
+        <xsl:choose>
+            <xsl:when test="$publication/source/directories/@generated">
+                <xsl:value-of select="$publication/source/directories/@generated"/>
+            </xsl:when>
+            <xsl:otherwise>
+                <xsl:text>generated</xsl:text>
+            </xsl:otherwise>
+        </xsl:choose>
+    </xsl:variable>
     <xsl:choose>
-        <xsl:when test="$b-has-external and $publication/source/directories/@generated">
-            <xsl:text>yes</xsl:text>
+        <xsl:when test="substring($raw-input, 1, 1) = '/'">
+            <xsl:message>PTX:FALLBACK:   a generated-image directory (source/directories/@generated in the publisher file) must be a relative path and not begin with "/" as in "<xsl:value-of select="$raw-input"/>".  Proceeding with the default, which is an empty string, and may lead to unexpected results.</xsl:message>
+            <xsl:text/>
         </xsl:when>
-        <xsl:when test="not($b-has-external) and not($publication/source/directories/@generated)">
-            <xsl:text>no</xsl:text>
+        <!-- trailing path separator is good -->
+        <xsl:when test="substring($raw-input, string-length($raw-input), 1) = '/'">
+            <xsl:value-of select="$raw-input"/>
         </xsl:when>
+        <!-- add the trailing slash -->
         <xsl:otherwise>
-            <xsl:message>PTX:FALLBACK:   an external directory ("directories/@external" within "docinfo", or the deprecated publication file form) and a generated directory (source/directories/@generated in the publication file) must be specified together; only one was found. Proceeding as if neither was specified.</xsl:message>
-            <xsl:text>no</xsl:text>
+            <xsl:value-of select="concat($raw-input, '/')"/>
         </xsl:otherwise>
     </xsl:choose>
 </xsl:variable>
-<xsl:variable name="b-managed-directories" select="$managed-directories = 'yes'"/>
 
-<!-- Destination directory is hard-coded here and used in      -->
-<!-- various conversions under the managed directories scheme. -->
-<xsl:variable name="external-directory">
-    <xsl:choose>
-        <xsl:when test="$b-managed-directories">
-            <xsl:text>external/</xsl:text>
-        </xsl:when>
-        <!-- backwards-compatiblity, there never was any sort of   -->
-        <!-- naming/copying scheme for externally produced content -->
-        <xsl:otherwise/>
-    </xsl:choose>
-</xsl:variable>
+<!-- Managed directories are the only scheme (2026-08-02).  The two  -->
+<!-- directions are independent facts: an undeclared external means  -->
+<!-- the project has no external assets, and the machine-owned       -->
+<!-- generated directory is defaultable.                             -->
 
-<!-- There was once a scheme of sorts for managing the directory -->
-<!-- where generated images landed and were found.  So we need   -->
-<!-- to preserve that logic for backward-compatibility.          -->
-<xsl:variable name="generated-directory">
-    <xsl:choose>
-        <xsl:when test="$b-managed-directories">
-            <xsl:value-of select="'generated/'"/>
-        </xsl:when>
-        <!-- Should issue a deprecation warning (elsewhere) for this.    -->
-        <!-- directory.images *is* defined elsewhere in this stylesheet, -->
-        <!-- and defaults to "images", but does not have a slash, which  -->
-        <!-- is presumed for the $generated-directory variable           -->
-        <xsl:otherwise>
-            <xsl:value-of select="concat($directory.images, '/')"/>
-        </xsl:otherwise>
-    </xsl:choose>
-</xsl:variable>
+
+<!-- The destination directories within any output are hard-coded -->
+<!-- here, and used in the various conversions.                   -->
+<xsl:variable name="external-directory" select="'external/'"/>
+<xsl:variable name="generated-directory" select="'generated/'"/>
 
 
 <!-- This is a directory that may need to be copied to a      -->
@@ -1436,22 +1389,17 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
     <!-- variable since it will not be used, and it is silent.        -->
     <xsl:if test="$original//webwork[node() or @*]">
         <xsl:choose>
-            <!-- Note: $generated-directory-source is never empty?    -->
-            <!-- Defaults to the very old "directory.images"?         -->
-            <!-- So testing for the publication file entry is better. -->
-            <xsl:when test="$publication/source/directories/@generated">
-                <xsl:value-of select="str:replace(concat($generated-directory-source, 'webwork/'), '&#x20;', '%20')"/>
-            </xsl:when>
-            <xsl:when test="$publication/source/@webwork-problems">
+            <!-- the deprecated location is honored only when no -->
+            <!-- generated directory is declared                 -->
+            <xsl:when test="$publication/source/@webwork-problems and not($publication/source/directories/@generated)">
                 <xsl:value-of select="str:replace($publication/source/@webwork-problems, '&#x20;', '%20')"/>
                 <xsl:message>PTX:DEPRECATE: the publication file entry  source/@webwork-problems  is</xsl:message>
                 <xsl:message>               deprecated, please move to using managed directories</xsl:message>
             </xsl:when>
-            <!-- no specification, so empty string for filename -->
-            <!-- this will be noted where it is employed        -->
-            <!-- no specification, so empty string for directory    -->
-            <!-- this will be noted where it is employed            -->
-            <xsl:otherwise/>
+            <!-- the generated directory, declared or defaulted -->
+            <xsl:otherwise>
+                <xsl:value-of select="str:replace(concat($generated-directory-source, 'webwork/'), '&#x20;', '%20')"/>
+            </xsl:otherwise>
         </xsl:choose>
     </xsl:if>
 </xsl:variable>
@@ -1463,15 +1411,8 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
 <xsl:variable name="dynamic-substitutions-file">
     <!-- Only relevant if there are dynamic exercises present.      -->
     <xsl:if test="$original//exercise//setup">
-        <xsl:choose>
-            <!-- Look in the publication file for the generated directory -->
-            <xsl:when test="$publication/source/directories/@generated">
-                <xsl:value-of select="str:replace(concat($generated-directory-source, 'dynamic_subs/dynamic_substitutions.xml'), '&#x20;', '%20')"/>
-            </xsl:when>
-            <!-- no specification, so empty string for filename -->
-            <!-- this will be noted where it is employed        -->
-            <xsl:otherwise/>
-        </xsl:choose>
+        <!-- the generated directory, declared or defaulted -->
+        <xsl:value-of select="str:replace(concat($generated-directory-source, 'dynamic_subs/dynamic_substitutions.xml'), '&#x20;', '%20')"/>
     </xsl:if>
 </xsl:variable>
 
@@ -2824,6 +2765,14 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
 </xsl:variable>
 <xsl:variable name="b-has-embed-button" select="$embed-button = 'yes'"/>
 
+<!--                           -->
+<!-- HTML Read-aloud control   -->
+<!--                           -->
+
+<xsl:variable name="read-aloud">
+    <xsl:apply-templates select="$publisher-attribute-options/html/pi:pub-attribute[@name='read-aloud']" mode="set-pubfile-variable"/>
+</xsl:variable>
+<xsl:variable name="b-read-aloud" select="not($read-aloud = 'no')"/>
 
 <!--                            -->
 <!-- HTML Banner options        -->
@@ -3548,6 +3497,7 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
     </common>
     <html>
         <pi:pub-attribute name="short-answer-responses" default="graded" options="always"/>
+        <pi:pub-attribute name="read-aloud" default="yes" options="no"/>
         <pi:pub-attribute name="favicon" default="none" options="simple"/>
         <pi:pub-attribute name="embed-button" default="no" options="yes"/>
         <pi:pub-attribute name="design-width" freeform="yes"/>
@@ -3946,9 +3896,11 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
 <!-- silently moved here, which should make no real difference -->
 <xsl:param name="directory.knowls"  select="''" />
 
-<!-- Deprecated 2020-11-23 in favor of publisher file -->
-<!-- specification, but will still be respected       -->
-<xsl:param name="directory.images" select="'images'" />
+<!-- Deprecated 2020-11-23 in favor of publisher file  -->
+<!-- specification; as of 2026-08-02 managed           -->
+<!-- directories are the only scheme, so this is dead: -->
+<!-- it survives only to power a deprecation warning.  -->
+<xsl:param name="directory.images" select="''" />
 
 <!-- 2021-01-03 chunk.level to publisher file -->
 <xsl:param name="chunk.level" select="''" />
@@ -4739,6 +4691,13 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
         <xsl:with-param name="incorrect-use" select="($html.annotation != '')" />
     </xsl:call-template>
     <!--  -->
+    <!-- 2026-08-02  managed directories are the only scheme -->
+    <xsl:call-template name="parameter-deprecation-message">
+        <xsl:with-param name="date-string" select="'2026-08-02'" />
+        <xsl:with-param name="message" select="'the  directory.images  parameter is now ignored: managed directories are the only scheme.  Generated assets live in the directory given by  source/directories/@generated  in the publication file (default: &quot;generated&quot;, beside the source), and external assets in the directory given by  &quot;directories/@external&quot;  within  &quot;docinfo&quot;.'" />
+        <xsl:with-param name="incorrect-use" select="($directory.images != '')" />
+    </xsl:call-template>
+    <!--  -->
 </xsl:template>
 
 </xsl:stylesheet>

package/assets/xsl/support/play-button/README.md

@@ -1,6 +1,5 @@
 Generic Video Preview Image
-
-```
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 2023-02-07: This image was previously provided for LaTeX output as a macro that resolves to a TikZ version.  See removed code and comments below.  In HTML we use an SVG we have mildly edited.  Search the HTML conversion for a template with name "generic-preview-svg".
 
@@ -43,4 +42,3 @@ The purpose of the PNG image is to be the static version created via the pre-pro
 (64.0200,47.9100) -- (38.2800,61.4100) -- cycle;
 \end{tikzpicture}
 }
-```

package/assets/xsl/tests/README.md

@@ -40,4 +40,4 @@ Refer to the existing tests in `pretext-text-utilities-test.xsl` for examples of
 ## Files
 
 - `pretext-text-utilities-test.xsl`: Contains tests for the text utilities templates.
-- `null.xml`: A minimal XML file used as input for the tests.
+- `null.xml`: A minimal XML file used as input for the tests.

package/assets/xsl/utilities/README.md

@@ -21,30 +21,28 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
 
 ## Source-to-Source conversions
 
-For utility programs here which rewrite your source, be **sure** to use version control (collect and review changes on a branch, stash and drop undesirable outcomes), or have backups handy. The effects are not reversible. Stylesheets will output to standard output, so you can redirect their output, or you can use something like the `-o` flag on the `xsltproc` command-line invocation. Experiment first.
+For utility programs here which rewrite your source, be **sure** to use version control (collect and review changes on a branch, stash and drop undesirable outcomes), or have backups handy.  The effects are not reversible.  Stylesheets will output to standard output, so you can redirect their output, or you can use something like the `-o` flag on the `xsltproc` command-line invocation.  Experiment first.
 
 ### `fix-deprecations.xsl`
+This will convert any obsolete element names or constructions to their replacements.  As deprecations are added, you may run it anew, and only the new changes will be applied.  Despite the name, it does make some minor changes.  Empty tags will get a single space prior to the closing backslash.
 
-This will convert any obsolete element names or constructions to their replacements. As deprecations are added, you may run it anew, and only the new changes will be applied. Despite the name, it does make some minor changes. Empty tags will get a single space prior to the closing backslash.
-
-Be sure to read all the details in the Author's Guide before using this on your source. Here is an absolute minimal example.
-
+Be sure to read all the details in the Author's Guide before using this on your source.  Here is an absolute minimal example.
 ```
 $ xsltproc /path/to/xsl/utilities/fix-deprecations.xsl -stringparam fix all /path/to/examples/sample-errors-and-warnings.xml > new-sample.xml
 
 $ diff /path/to/examples/sample-errors-and-warnings.xml new-sample.xml
 ```
-
 (Updated: 2017-07-04)
 
+
 ## Author Report
 
-`author-report.xsl` is a very simple stylesheet which will produce a text version of items in your source that could benefit from your attention. This is different than validating your PreTeXt source against the schema, but is part of using automated tools to ensure healthy source material.
+`author-report.xsl` is a very simple stylesheet which will produce a text version of items in your source that could benefit from your attention.  This is different than validating your PreTeXt source against the schema, but is part of using automated tools to ensure healthy source material.
 
 (Updated: 2018-12-09)
 
 ## Intermediate Enhanced Source
 
-`pretext-enhanced-source.xsl` is mainly meant for development use. It outputs an XML file, which is not necessarily valid PreTeXt, at a key stage of the processing. It gives you a look under the hood (or bonnet). So generally not useful (or necessary) for authors.
+`pretext-enhanced-source.xsl` is mainly meant for development use.  It outputs an XML file, which is not necessarily valid PreTeXt, at a key stage of the processing.  It gives you a look under the hood (or bonnet).  So generally not useful (or necessary) for authors.
 
 (Updated: 2020-02-25)