@pretextbook/pretext-html 0.16.0 → 0.17.0

package/README.md

@@ -91,6 +91,77 @@ const { html } = await renderHtml({
   alone. Pass `openKnowls: false` (`--no-open-knowls` on the CLI) for the
   collapsed reading experience of a real `pretext build`.
 
+### Previewing one division of a large document
+
+A render costs what PreTeXt's assembly costs, and that tracks the number of
+elements in the document: a few hundred milliseconds for a chapter, tens of
+seconds for a whole book. A live preview of a large document therefore should
+not render the whole document, and need not: the `subtree` option renders one
+division of it, numbered and cross-referenced exactly as the whole document
+would number it, by pruning the rest to a skeleton (see `src/skeleton.ts`).
+
+```js
+const { html, size, subtree } = await renderHtml({
+  sourcePath: "source/main.ptx",
+  subtree: {
+    line: cursorLine, // the division around the author's cursor...
+    file: cursorFile, // ...in this file (defaults to sourcePath)
+    level: 2, // chunk level: sections of a book are pages of their own
+    wholeDocumentUpTo: 3000, // but a small document previews whole
+  },
+});
+```
+
+- `line`/`file` select the innermost division containing a source line; `id`
+  selects by `xml:id` instead (an element inside a division selects that
+  division). The division need not carry an `xml:id` of its own — the one
+  PreTeXt would stamp on it is injected, so the page's HTML ids are unchanged.
+- A division that contains divisions is previewed as a **summary page**: its
+  own content (introduction, conclusion, loose paragraphs) rendered in place,
+  then links to the divisions inside it, as the chapter page of a chunked
+  build summarizes its sections. Only leaf divisions render in full, so a
+  cursor at the top of a book shows the book's front matter and a table of
+  its chapters, never the book. The summary links are inert on a one-page
+  preview but carry `data-ptx-division` (and `data-ptx-id` for a link to an
+  element), so a host can make them re-render with `subtree: { id }`.
+- `level` has PreTeXt's chunk-level meaning, for a host that wants whole
+  pages at some depth: the preview is the page that would hold the selection
+  in a build chunked at that level. A selection deeper than `level` previews
+  its ancestor at `level`, whole; one at `level` is shown whole; one shallower
+  is the summary page above. Omit it to treat every division as a page of its
+  own.
+- `wholeDocumentUpTo` renders the whole document instead when it has no more
+  than that many elements — a small document previews whole as fast as any
+  division of it would.
+- Every result carries `size` (`elements`, `bytes`, and the `files` the
+  document spans, to watch for changes), and `subtree` (`id`, `level`,
+  `collapsed`) when one division was emitted rather than the whole document.
+  `measureDocument(options)` reports the same `size` without rendering, for a
+  host deciding how much to preview before each render.
+- With `fragment: true` and a context document, `subtree` narrows the preview
+  within the placed fragment — a cursor line in a chapter file previews the
+  section it is in.
+
+What a division preview still has to do on every render is read and parse the
+whole document, to prune it. Two options keep that cheap:
+
+- `readSource(path)` (or `files`, a map from absolute path to content) supplies
+  the document's files from memory — the xi:include targets, the context
+  document, the publication file — for a host that already holds its project
+  in memory (a browser editor) or has unsaved buffers (an editor). A reader
+  that returns `undefined` for a path falls through to the platform's own read.
+- A per-file parse cache, on by default, reuses the parse of every file whose
+  content has not changed since the last render. It is keyed by file, not by
+  the assembled document, so it does not matter how the project is split into
+  files: a keystroke re-parses the file being edited and nothing else. Pass a
+  `SourceCache` of your own as `cache` to scope it (and `invalidate()` it), or
+  `cache: false` to parse afresh each time.
+
+On a synthetic 12-chapter book of 28,000 elements split into 157 files, a
+section or subsection preview takes well under a second warm (0.3–0.8s
+measured, most of it the division itself), and a chapter's summary page about
+the same, against 20–40 seconds for the whole book.
+
 ### API (browser)
 
 The same renderer runs in a browser — no server, no Python. Bundlers pick it up
@@ -117,9 +188,12 @@ filesystem:
 
 - **`sourceContent` is required.** `sourcePath` still anchors relative
   `xi:include`s and the output's URLs, but nothing is read from it.
-- **`xi:include`s are not resolved from disk.** Pre-merge them, or pass the
-  already-merged document as `sourceContent`. An unresolvable include uses its
-  `<xi:fallback>` if it has one, and otherwise throws.
+- **`xi:include`s are not resolved from disk.** Supply the project's files
+  through `readSource` or `files` (see above) and they are resolved from
+  there, with the per-file parse cache working as it does under Node; or
+  pre-merge them and pass the merged document as `sourceContent`. An
+  unresolvable include uses its `<xi:fallback>` if it has one, and otherwise
+  throws.
 - **`publicationPath` / `docinfoSourcePath` need absolute URLs**, since those
   are the only readable locations. Prefer `docinfo` (a string) over
   `docinfoSourcePath`.

package/assets/preview-html.xsl

@@ -226,6 +226,62 @@
     </xsl:choose>
 </xsl:variable>
 
+<!-- A subtree root one level above the chunk level is a summary page: its own  -->
+<!-- content, then links to the divisions inside it. Only that page is emitted; -->
+<!-- the chunker is kept from also producing a page per child division.        -->
+<!-- See SUMMARY_PAGE_OVERRIDE in refresh-xsl.mjs.                              -->
+<xsl:template match="*" mode="chunking">
+    <xsl:choose>
+        <xsl:when test="$b-subsetting and not(generate-id(.) = generate-id(id($subtree)))"/>
+        <xsl:otherwise>
+            <xsl:apply-imports/>
+        </xsl:otherwise>
+    </xsl:choose>
+</xsl:template>
+
+<xsl:template match="*" mode="intermediate">
+    <xsl:apply-templates select="." mode="file-wrap">
+        <xsl:with-param name="content">
+            <xsl:apply-templates select="." mode="debug-location"/>
+            <section class="{local-name(.)}">
+                <xsl:apply-templates select="." mode="html-id-attribute"/>
+                <xsl:apply-templates select="." mode="section-heading">
+                    <xsl:with-param name="heading-level" select="$chunk-heading-level"/>
+                </xsl:apply-templates>
+                <xsl:apply-templates select="." mode="author-byline"/>
+                <xsl:if test="self::frontmatter[not(titlepage)]">
+                    <xsl:call-template name="frontmatter-title"/>
+                </xsl:if>
+                <!-- The division's own content, in place -->
+                <xsl:for-each select="*">
+                    <xsl:variable name="structural">
+                        <xsl:apply-templates select="." mode="is-structural"/>
+                    </xsl:variable>
+                    <xsl:if test="not($structural = 'true')">
+                        <xsl:apply-templates select=".">
+                            <xsl:with-param name="heading-level" select="$chunk-heading-level + 1"/>
+                        </xsl:apply-templates>
+                    </xsl:if>
+                </xsl:for-each>
+                <!-- Then the divisions inside it, as upstream's summary links -->
+                <nav class="summary-links">
+                    <ul>
+                        <xsl:for-each select="*">
+                            <xsl:variable name="structural">
+                                <xsl:apply-templates select="." mode="is-structural"/>
+                            </xsl:variable>
+                            <xsl:if test="$structural = 'true'">
+                                <xsl:apply-templates select="." mode="summary-nav"/>
+                            </xsl:if>
+                        </xsl:for-each>
+                    </ul>
+                </nav>
+                <xsl:apply-templates select="." mode="permalink"/>
+            </section>
+        </xsl:with-param>
+    </xsl:apply-templates>
+</xsl:template>
+
 <!-- Show the print-preview button on printouts, but inert: the page it would -->
 <!-- reload with "?printpreview=<id>" does not exist for an in-memory render, -->
 <!-- and a host that resolves that query against its own URL sends the reader -->

package/assets/upstream.json

@@ -1,7 +1,7 @@
 {
   "source": {
     "repository": "PreTeXtBook/pretext",
-    "ref": "master"
+    "ref": "ee0a7e135e3346f0b0c6192822d6942424cb4af0"
   },
-  "refreshed": "2026-08-31T02:38:18.809Z"
+  "refreshed": "2026-10-01T06:28:22.049Z"
 }

package/assets/xsl/entities.ent

@@ -154,7 +154,7 @@
 <!-- "top" figure-like is a captioned display that earns a number (a    -->
 <!-- panel inside a captioned side-by-side earns a letter instead).     -->
 <!ENTITY FUNDAMENTAL-BLOCK-FILTER "(&DEFINITION-FILTER;) or (&THEOREM-FILTER;) or (&AXIOM-FILTER;) or (&REMARK-FILTER;) or (&COMPUTATION-FILTER;) or (&EXAMPLE-FILTER;)">
-<!ENTITY TOP-FIGURE-FILTER "(&FIGURE-FILTER;) and not(parent::sidebyside/parent::figure or parent::sidebyside/parent::sbsgroup/parent::figure)">
+<!ENTITY TOP-FIGURE-FILTER "(&FIGURE-FILTER;) and not(parent::sidebyside/parent::figure or parent::sidebyside/parent::sbsgroup/parent::figure or self::figure[parent::stack/parent::figure])">
 
 <!-- Panels of a "sidebyside", and content of a "stack" panel.  The   -->
 <!-- lists mirror the schema, plus grandfathered items the code still -->
@@ -166,6 +166,19 @@
 <!ENTITY SBSPANEL "p|pre|ol|ul|dl|program|console|poem|audio|video|interactive|slate|exercise|image|figure|table|listing|list|tabular|stack">
 <!ENTITY STACKABLE "tabular|image|p|pre|ol|ul|dl|audio|video|interactive|slate|program|console">
 
+<!-- A panel of a "sidebyside" is a child of the "sidebyside", or a     -->
+<!-- child of a "stack" in the "sidebyside".  The layout of the         -->
+<!-- "sidebyside" sizes its panels (and the content of a "figure"       -->
+<!-- panel).  An object nested more deeply, such as an "image" in an    -->
+<!-- "exercise" panel or in a list item, is sized by its own attributes -->
+<!-- relative to the available width where it sits.                     -->
+<!ENTITY SBS-PANEL-FILTER "parent::sidebyside or parent::stack/parent::sidebyside">
+
+<!-- An object sized by the layout of the "sidebyside": a panel, or the -->
+<!-- content of a "figure" panel.  Anything nested more deeply is sized -->
+<!-- by its own attributes.                                             -->
+<!ENTITY SBS-LAYOUT-FILTER "(&SBS-PANEL-FILTER;) or parent::figure[&SBS-PANEL-FILTER;]">
+
 <!-- appendages of examples, exercises, tasks -->
 <!ENTITY SOLUTION-LIKE "hint|answer|solution">
 <!ENTITY SOLUTION-FILTER "self::hint or self::answer or self::solution">

package/assets/xsl/latex/pretext-latex-texstyle.xsl

@@ -189,7 +189,6 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
 <!-- Here we build the "standard" (classic) latex preamble,       -->
 <!-- with some minor modifications suggested by the texstyle file -->
 <xsl:template match="texstyle/ptx-preamble">
-    <xsl:call-template name="frontmatter-helpers"/>
     <xsl:call-template name="preamble-early"/>
     <xsl:call-template name="cleardoublepage"/>
     <xsl:call-template name="standard-packages"/>
@@ -208,6 +207,7 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
     <xsl:call-template name="latex-engine-support"/>
     <xsl:call-template name="font-support"/>
     <xsl:call-template name="math-packages"/>
+    <xsl:call-template name="text-symbols"/>
     <xsl:call-template name="pdfpages-package"/>
     <xsl:call-template name="semantic-macros"/>
     <xsl:call-template name="chapter-start-number"/>
@@ -756,8 +756,11 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
 </xsl:template>
 
 
+<!-- A journal's bibliography is formatted by PreTeXt, not by BibTeX: -->
+<!-- in the journal's CSL style, when references have been generated  -->
+<!-- and replaced during assembly, else in PreTeXt's own way.  So the -->
+<!-- texstyle file only says *where* the list belongs.                -->
 <xsl:template match="texstyle/bibliography">
-    <xsl:message>PTX:WARNING: Bibliographies are not implemented correctly yet.</xsl:message>
     <xsl:apply-templates select="$document-root/references|$document-root/backmatter/references"/>
 </xsl:template>
 

package/assets/xsl/localizations/README.md

@@ -41,7 +41,7 @@ Current (partially) implemented language codes and contributors
 * bg-BG, Bulgarian (Bulgaria), Boyko Bantchev
 * ca-ES, Catalan (Spain), Jordi Saludes
 * cs-CZ, Czech (Czechia), Jiří Lebl
-* de-DE, German (Germany), Karl-Dieter Crisman
+* de-DE, German (Germany), Karl-Dieter Crisman, Klaus Krtschil
 * es-ES, Spanish (Spain), Juan José Torrens
 * en-US, English (United States), Robert A. Beezer
 * fi-FI, Finnish (Finland), Lasse M. Manninen

package/assets/xsl/localizations/af-ZA.xml

@@ -144,10 +144,10 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
     <localization string-id='fragment'>Fragment</localization>
     <!-- Parts of an exercise and its solution -->
     <!-- See the en-US file for a detailed explanation of the words for exercises -->
-    <localization string-id='divisionalexercise'>Oefening</localization>
-    <localization string-id='inlineexercise'>Kontrolepunt</localization>
-    <localization string-id='worksheetexercise'>Werkbladoefening</localization>
-    <localization string-id='readingquestion'>Leesvraag</localization>
+    <localization string-id='exercise-divisional'>Oefening</localization>
+    <localization string-id='exercise-inline'>Kontrolepunt</localization>
+    <localization string-id='exercise-worksheet'>Werkbladoefening</localization>
+    <localization string-id='exercise-reading'>Leesvraag</localization>
     <localization string-id='webwork'>WeBWorK</localization>
     <localization string-id='hint'>Wenk</localization>
     <localization string-id='answer'>Antwoord</localization>
@@ -236,7 +236,6 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
     <localization string-id='permalink-tooltip'>Copy heading and permalink for</localization>
     <!-- <localization string-id='calculator'>Calculator</localization> -->
     <localization string-id='evaluate'>Evalueer</localization>
-    <!-- <localization string-id='code'>Code</localization> -->
     <!-- <localization string-id='instructions'>Instructions</localization> -->
     <!-- <localization string-id='correct'>Correct</localization> -->
     <!-- <localization string-id='incorrect'>Incorrect</localization> -->
@@ -249,7 +248,7 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
     <!-- <localization string-id='reset'>Reset</localization> -->
     <!-- <localization string-id='array'>array</localization> -->
     <!-- <localization string-id="papersize">Paper size</localization> -->
-    <!-- <localization string-id="printing-options">Additional printing options</localization> -->
+    <!-- <localization string-id="printing-options">Printing options</localization> -->
     <!-- <localization string-id="hide-hints">Hide hints</localization> -->
     <!-- <localization string-id="hide-answers">Hide answers</localization> -->
     <!-- <localization string-id="hide-solutions">Hide solutions</localization> -->

package/assets/xsl/localizations/bg-BG.xml

@@ -144,10 +144,10 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
     <!-- <localization string-id='fragment'>Fragment</localization> -->
     <!-- Parts of an exercise and its solution -->
     <!-- See the en-US file for a detailed explanation of the words for exercises -->
-    <localization string-id='divisionalexercise'>Упражнение</localization>
-    <localization string-id='inlineexercise'>Checkpoint</localization>
-    <localization string-id='worksheetexercise'>Worksheet Exercise</localization>
-    <localization string-id='readingquestion'>Reading Question</localization>
+    <localization string-id='exercise-divisional'>Упражнение</localization>
+    <localization string-id='exercise-inline'>Checkpoint</localization>
+    <localization string-id='exercise-worksheet'>Worksheet Exercise</localization>
+    <localization string-id='exercise-reading'>Reading Question</localization>
     <localization string-id='webwork'>WeBWorK</localization>
     <localization string-id='hint'>Подсказка</localization>
     <localization string-id='answer'>Отговор</localization>
@@ -236,7 +236,6 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
     <localization string-id='permalink-tooltip'>Copy heading and permalink for</localization>
     <!-- <localization string-id='calculator'>Calculator</localization> -->
     <localization string-id='evaluate'>Evaluate</localization>
-    <!-- <localization string-id='code'>Code</localization> -->
     <!-- <localization string-id='instructions'>Instructions</localization> -->
     <!-- <localization string-id='correct'>Correct</localization> -->
     <!-- <localization string-id='incorrect'>Incorrect</localization> -->
@@ -249,7 +248,7 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
     <!-- <localization string-id='reset'>Reset</localization> -->
     <!-- <localization string-id='array'>array</localization> -->
     <!-- <localization string-id="papersize">Paper size</localization> -->
-    <!-- <localization string-id="printing-options">Additional printing options</localization> -->
+    <!-- <localization string-id="printing-options">Printing options</localization> -->
     <!-- <localization string-id="hide-hints">Hide hints</localization> -->
     <!-- <localization string-id="hide-answers">Hide answers</localization> -->
     <!-- <localization string-id="hide-solutions">Hide solutions</localization> -->

package/assets/xsl/localizations/ca-ES.xml

@@ -147,12 +147,12 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
     <localization string-id='fragment'>Fragment</localization>
     <!-- Parts of an exercise and its solution -->
     <!-- See the en-US file for a detailed explanation of the words for exercises -->
-    <localization string-id='divisionalexercise'>Exercici</localization>
+    <localization string-id='exercise-divisional'>Exercici</localization>
     <!-- Translation needed for Spain Spanish -->
     <!-- See en-US file for distinctions here, do not repeat previous translation -->
-    <localization string-id='inlineexercise'>Punt de control</localization>
-    <!-- <localization string-id='worksheetexercise'>Worksheet Exercise</localization> -->
-    <!-- <localization string-id='readingquestion'>Reading Question</localization> -->
+    <localization string-id='exercise-inline'>Punt de control</localization>
+    <!-- <localization string-id='exercise-worksheet'>Worksheet Exercise</localization> -->
+    <!-- <localization string-id='exercise-reading'>Reading Question</localization> -->
     <localization string-id='webwork'>WeBWorK</localization>
     <localization string-id='hint'>Pista</localization>
     <localization string-id='answer'>Resposta</localization>
@@ -245,7 +245,6 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
     <!-- This needs to be defined to *something* (English) -->
     <!-- Translate at first opportunity, please -->
     <localization string-id='evaluate'>Avaluar</localization>
-    <!-- <localization string-id='code'>Code</localization> -->
     <!-- <localization string-id='instructions'>Instructions</localization> -->
     <!-- <localization string-id='correct'>Correct</localization> -->
     <!-- <localization string-id='incorrect'>Incorrect</localization> -->
@@ -258,7 +257,7 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
     <!-- <localization string-id='reset'>Reset</localization> -->
     <!-- <localization string-id='array'>array</localization> -->
     <!-- <localization string-id="papersize">Paper size</localization> -->
-    <!-- <localization string-id="printing-options">Additional printing options</localization> -->
+    <!-- <localization string-id="printing-options">Printing options</localization> -->
     <!-- <localization string-id="hide-hints">Hide hints</localization> -->
     <!-- <localization string-id="hide-answers">Hide answers</localization> -->
     <!-- <localization string-id="hide-solutions">Hide solutions</localization> -->

package/assets/xsl/localizations/cs-CZ.xml

@@ -144,12 +144,12 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
     <localization string-id='fragment'>Fragment</localization>
     <!-- Parts of an exercise and its solution -->
     <!-- See the en-US file for a detailed explanation of the words for exercises -->
-    <localization string-id='divisionalexercise'>Cvičení</localization>
+    <localization string-id='exercise-divisional'>Cvičení</localization>
     <!-- Translation needed for Czech Czech -->
     <!-- See en-US file for distinctions here, do not repeat previous translation -->
-    <localization string-id='inlineexercise'>Zkouška</localization>
-    <localization string-id='worksheetexercise'>Cvičení pracovního listu</localization>
-    <localization string-id='readingquestion'>Otázka ze čtení</localization>
+    <localization string-id='exercise-inline'>Zkouška</localization>
+    <localization string-id='exercise-worksheet'>Cvičení pracovního listu</localization>
+    <localization string-id='exercise-reading'>Otázka ze čtení</localization>
     <localization string-id='webwork'>WeBWorK</localization>
     <localization string-id='hint'>Nápověda</localization>
     <localization string-id='answer'>Odpověď</localization>
@@ -240,7 +240,6 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
     <!-- This needs to be defined to *something* (English) -->
     <!-- Translate at first opportunity, please -->
     <localization string-id='evaluate'>Ohodnotit</localization>
-    <!-- <localization string-id='code'>Code</localization> -->
     <localization string-id='instructions'>Instrukce</localization>
     <localization string-id='correct'>Správně</localization>
     <localization string-id='incorrect'>Nesprávně</localization>
@@ -253,7 +252,7 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
     <localization string-id='reset'>Reset</localization>
     <localization string-id='array'>pole</localization>
     <localization string-id="papersize">Velikost papíru</localization>
-    <localization string-id="printing-options">Další možnosti tisku</localization>
+    <localization string-id="printing-options">Možnosti tisku</localization>
     <localization string-id="hide-hints">Zakrýt nápovědu</localization>
     <localization string-id="hide-answers">Zakrýt odpovědi</localization>
     <localization string-id="hide-solutions">Zakrýt řešení</localization>