@amermathsoc/texml-to-html 18.7.0 → 19.0.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
+## [19.0.0](https://github.com/AmerMathSoc/texml-to-html/compare/v18.7.0...v19.0.0) (2025-11-26)
+
+
+### ⚠ BREAKING CHANGES
+
+* Expects new texml TOC markup (toc-title-group).
+
+### Features
+
+* adjust to new TOC markup ([b18f29a](https://github.com/AmerMathSoc/texml-to-html/commit/b18f29a831bd6a1943d8a05faf04f01d20f65167)), closes [#494](https://github.com/AmerMathSoc/texml-to-html/issues/494)
+
 ## [18.7.0](https://github.com/AmerMathSoc/texml-to-html/compare/v18.6.0...v18.7.0) (2025-07-02)
 
 

package/README.md

@@ -162,7 +162,7 @@ Beyond HTML element and attributes, texml-to-html stores data in custom `data-*`
 
 ##### downstream `data-*` attributes
 
-While the vast majority of data attributes originate in texml-to-html, we have a few cases where downstream tooling introduces custom attributes.
+While most data attributes originate in texml-to-html, we have a few cases where downstream tooling introduces custom attributes.
 We list the attribute names, the related tools and purpose:
 
 - [deprecated] data-eqn-tag-#
@@ -329,12 +329,16 @@ For books:
 
 **Note.** There is some overlap with other sections of this document. Ensure that updates are consistent across the document.
 
-For math mode, texml creates MathJax-optimized TeX strings that may contain XML markup; for content not supported by MathJax it falls back to SVG creation. This mix requires extra processing.
+For math mode, texml creates MathJax-optimized TeX strings that may contain XML markup; for content not supported by MathJax it falls back to SVG creation. This mix requires additional processing.
+
+For MathJax requirements, see the section below.
 
 #### xref
 
 Math mode output may contain xref elements. This gets turned into something like `\xhref[@ref-type]{#@rid}{...}`; the custom `xhref` MathJax macro works in both (MathJax's) text and math mode.
 
+Furthermore, xref-group and cite-group will pass through and may need to be stripped for MathJax processing.
+
 #### text inside math mode
 
 In the case where math mode contains text mode, texml creates text elements possibly containing text XML markup. We turn this into MathJax-compatible TeX strings.
@@ -383,3 +387,38 @@ We convert the markup to HTML custom elements with attributes. Further processin
   - alg:repeat
   - alg:until
   - alg:loop
+
+### MathJax requirements
+
+The output generated by texml and texml-to-html assumes the following MathJax extensions are available:
+
+#### mathjax-src extensions
+
+- Base
+- Ams
+- AmsCd
+- Bbox
+- Boldsymbol
+- Braket
+- Cancel
+- Color
+- ConfigMacros
+- Enclose
+- Extpfeil
+- Html
+- TagFormat
+- TextMacros
+- Unicode
+- Verb
+- Mathtools
+- Cases
+- Empheq
+- Colortbl
+
+#### third-party extensions
+
+- [mathjax-xhref](https://github.com/AmerMathSoc/mathjax-xhref)
+- [mathjax-img](https://github.com/pkra/mathjax-img)
+- [mathjax-ams-macros](https://github.com/AmerMathSoc/mathjax-ams-macros)
+- [mathjax-unicode-math](https://github.com/AmerMathSoc/mathjax-unicode-math)
+- [mathjax-dbnsymb](https://github.com/AmerMathSoc/mathjax-dbnsymb)

package/lib/elements/sec.js

@@ -82,7 +82,10 @@ export default function (htmlParentNode, xmlnode) {
   if (tagName === 'book-app-group') {
     section.setAttribute('data-ams-doc', 'app-group');
   }
-  if (tagName === 'book-app' && !xmlnode.parentNode.closest('book-app')) section.setAttribute('role', 'doc-appendix'); // TODO: revisit after AmerMathSoc/texml#223
+  if (tagName === 'book-app' && !xmlnode.parentNode.closest('book-app')) {
+    section.setAttribute('role', 'doc-appendix'); // TODO: revisit after AmerMathSoc/texml#223
+    // section.setAttribute('data-ams-doc-level', '0')
+    }
 
   this.createHeading(section, xmlnode);
   this.passThrough(section, xmlnode);

package/lib/elements/toc.js

@@ -26,7 +26,7 @@ export default function (htmlParentNode, xmlnode) {
     id: xmlnode.id,
   });
   htmlParentNode.appendChild(nav);
-  this.recurseTheDom(nav, xmlnode.querySelector('title-group'));
+  this.recurseTheDom(nav, xmlnode.querySelector('toc-title-group'));
   const ol = this.createNode('ol');
   nav.appendChild(ol);
   [...xmlnode.childNodes]

package/lib/transformer.js

@@ -208,6 +208,17 @@ export class Transformer {
         this.passThrough(span, xmlnode);
         return span.innerHTML.trim();
     }
+
+    /**
+     * Recursion hack for metadata generation
+     * @param {Node} xmlnode
+     * @returns {String}
+     */
+    recurseTheDomIntoHTMLString = xmlnode => {
+        const span = this.createNode('span');
+        this.recurseTheDom(span, xmlnode);
+        return span.innerHTML.trim();
+    }
     
     createHeading = (section, xmlnode)  => {  // create heading structure
         const label = xmlnode.querySelector(':scope>label:not(:empty)');
@@ -305,6 +316,7 @@ export class Transformer {
     'cite-group' = CiteGroup.bind(this)
     'cite-detail' = CiteDetail.bind(this)
     'title-group' = TitleGroup.bind(this)
+    'toc-title-group' = TitleGroup.bind(this)
 
     // one-off reuse of imported elements
     // NOTE if RHS gets re-used more than once, use mapTag in the constructor

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@amermathsoc/texml-to-html",
-  "version": "18.7.0",
+  "version": "19.0.0",
   "type": "module",
   "description": "A NodeJS library for converting AMS-style JATS XML to HTML",
   "scripts": {
     "coverage": "c8 npm run test && c8 report --reporter html",
     "release": "commit-and-tag-version",
-    "texmlTests": "rm ./test/snapshots/texml-tests/* && find ../texml/tests/ -name *.xml -exec cp {} ./test/snapshots/texml-tests/. \\;",
+    "texmlTests": "rm -f ./test/snapshots/texml-tests/* && find ../texml/tests/ -name '*.xml' -exec cp {} ./test/snapshots/texml-tests/. \\;",
     "pretest": "node ./test/snapshots/updateTexmlSnapshots.js",
     "test": "tape test/*.js"
   },

package/test/book--metadata.xml

@@ -123,9 +123,9 @@
     </book-meta>
     <front-matter>
         <toc id="toc">
-            <title-group>
+            <toc-title-group>
             <title>Contents</title>
-            </title-group>
+            </toc-title-group>
             <toc-entry specific-use="chapter">
             <title>Chunk</title>
             <nav-pointer rid="tocid1"/>

package/test/book.xml

@@ -88,9 +88,9 @@
     </book-meta>
     <front-matter>
         <toc id="toc">
-            <title-group>
+            <toc-title-group>
             <title>Contents</title>
-            </title-group>
+            </toc-title-group>
             <toc-entry specific-use="chapter" style="custom">
             <title>Chunk</title>
             <nav-pointer rid="tocid1"/>

package/test/snapshots/texml-tests/appendix-book.html

@@ -0,0 +1,74 @@
+<!DOCTYPE html> <html dir="ltr" lang="en"><head><meta charset="utf-8"><meta content="width=device-width, initial-scale=1" name="viewport"><title>Sample book with appendix</title></head><body>
+  <section data-ams-doc="titlepage"><script type="application/json">{"book":{"identifiers":{"AMS":{},"crossref":{},"issn":{},"isbn":{},"loc":{},"basename":null},"title":"Sample book with appendix","alttitle":"Sample book with appendix"},"publishers":[],"contributors":{"authors":[{"name":"Jane Doe","bio":"","affiliations":[],"emails":[]}]},"permissions":{},"history":{}}</script></section>
+  
+    <nav id="ltxid2" data-ams-doc-level="0" role="doc-toc"><h1><span data-ams-doc="title">Contents</span></h1><ol><li><a data-ams-ref="epub-opening-page" href="#ltxid3"><span data-ams-doc="title">Publisher’s Notice</span></a></li><li><a data-ams-ref="chapter" href="#ltxid5"><span data-ams-doc="label">Chapter 1<ams-x>.</ams-x></span> <span data-ams-doc="title">Chapter title</span></a><ol><li><a data-ams-ref="section" href="#ltxid6"><span data-ams-doc="label">1<ams-x>.</ams-x></span> <span data-ams-doc="title">Introduction</span></a></li></ol></li><li><a data-ams-ref="book-app" href="#ltxid9"><span data-ams-doc="label">Appendix A<ams-x>.</ams-x></span> <span data-ams-doc="title">Esoteric Secrets</span></a><ol><li><a data-ams-ref="section" href="#ltxid10"><span data-ams-doc="label">1<ams-x>.</ams-x></span> <span data-ams-doc="title">Appendix section</span></a></li></ol></li><li><a data-ams-ref="book-app" href="#ltxid12"><span data-ams-doc="title">Esotericer Secrets</span></a><ol><li><a data-ams-ref="section" href="#ltxid13"><span data-ams-doc="label">2<ams-x>.</ams-x></span> <span data-ams-doc="title">Another appendix section</span></a></li></ol></li><li><a data-ams-ref="book-app" href="#ltxid14"><span data-ams-doc="label">Appendix B<ams-x>.</ams-x></span> <span data-ams-doc="title">Esotericest Secrets</span></a><ol><li><a data-ams-ref="section" href="#ltxid15"><span data-ams-doc="title">Shout outs</span></a></li></ol></li></ol></nav>
+    <section data-ams-doc-level="0" data-ams-content-type="publishers-note" data-ams-doc="notes" data-ams-specific-use="epub-opening-page" id="ltxid3"><h1><span data-ams-doc="title">Publisher’s Notice</span></h1>
+      
+      <p>The <a href="https://www.ams.org">American Mathematical Society</a> has provided this ebook to you without Digital Rights Management (DRM) software applied so that you can enjoy reading it on your personal devices. This ebook is for your personal use only and must not be made publicly available in any way. You may not copy, reproduce, or upload this ebook except to read it on your personal devices.</p>
+    </section>
+  
+  
+    
+      
+        <section role="doc-chapter" id="ltxid5" data-ams-doc="chapter" data-ams-doc-level="0"><h1><span data-ams-doc="label">Chapter 1</span> <span data-ams-doc="title">Chapter title</span></h1>
+          
+          
+          <section role="doc-introduction" id="ltxid6" data-ams-doc="section" data-ams-doc-level="1"><h2><span data-ams-doc="label">1<ams-x>.</ams-x></span> <span data-ams-doc="title">Introduction</span></h2>
+            
+            
+            <p>Here is some text.</p>
+          </section>
+        </section>
+      
+    
+  
+  
+    <section id="ltxid8" data-ams-doc="app-group" data-ams-doc-level="0">
+      
+        <h1><span data-ams-doc="title">Appendixes</span></h1>
+      
+      <section role="doc-appendix" id="ltxid9" data-ams-doc="null" data-ams-doc-level="5">
+        
+          <h6><span data-ams-doc="label">Appendix A</span> <span data-ams-doc="title">Esoteric Secrets</span></h6>
+        
+        
+          <p>Some text.</p>
+          <section data-ams-specific-use="section" id="ltxid10" data-ams-doc-level="1" role="doc-appendix"><h2><span data-ams-doc="label">1<ams-x>.</ams-x></span> <span data-ams-doc="title">Appendix section</span></h2>
+            
+            
+            <p>Some text.</p>
+            <section id="ltxid11" data-ams-doc="subsection" data-ams-doc-level="2"><h3><span data-ams-doc="label">1.1<ams-x>.</ams-x></span> <span data-ams-doc="title">Appendix subsection<ams-x>.</ams-x></span></h3>
+              
+              
+              <p>Some text.</p>
+            </section>
+          </section>
+        
+      </section>
+      <section role="doc-appendix" id="ltxid12" data-ams-doc="null" data-ams-doc-level="5">
+        
+          <h6><span data-ams-doc="label">Appendix</span> <span data-ams-doc="title">Esotericer Secrets</span></h6>
+        
+        
+          <p>Some text.</p>
+          <section data-ams-specific-use="section" id="ltxid13" data-ams-doc-level="1" role="doc-appendix"><h2><span data-ams-doc="label">2<ams-x>.</ams-x></span> <span data-ams-doc="title">Another appendix section</span></h2>
+            
+            
+            <p>Some text.</p>
+          </section>
+        
+      </section>
+      <section role="doc-appendix" id="ltxid14" data-ams-doc="null" data-ams-doc-level="5">
+        
+          <h6><span data-ams-doc="label">Appendix B</span> <span data-ams-doc="title">Esotericest Secrets</span></h6>
+        
+        
+          <p>Here is the real truth.</p>
+        
+      </section>
+    </section>
+    <section role="doc-acknowledgments" id="ltxid15" data-ams-doc="section" data-ams-doc-level="1"><h2><span data-ams-doc="title">Shout outs</span></h2>
+      
+    </section>
+  
+</body></html>

package/test/snapshots/texml-tests/appendix-book.xml

@@ -0,0 +1,142 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE book PUBLIC "-//NLM//DTD BITS Book Interchange DTD v2.1 20180401//EN" "BITS-book2.dtd">
+<book xmlns:xlink="http://www.w3.org/1999/xlink">
+  <book-meta>
+    <book-title-group>
+      <book-title>Sample book with appendix</book-title>
+    </book-title-group>
+    <contrib-group content-type="authors">
+      <contrib contrib-type="author">
+        <string-name>Jane Doe</string-name>
+      </contrib>
+    </contrib-group>
+  </book-meta>
+  <front-matter id="ltxid1">
+    <toc id="ltxid2">
+      <toc-title-group>
+        <title>Contents</title>
+      </toc-title-group>
+      <toc-entry specific-use="epub-opening-page">
+        <title>Publisher’s Notice</title>
+        <nav-pointer rid="ltxid3"/>
+      </toc-entry>
+      <toc-entry specific-use="chapter">
+        <label>Chapter 1<x>.</x></label>
+        <title>Chapter title</title>
+        <nav-pointer rid="ltxid5"/>
+        <toc-entry specific-use="section">
+          <label>1<x>.</x></label>
+          <title>Introduction</title>
+          <nav-pointer rid="ltxid6"/>
+        </toc-entry>
+      </toc-entry>
+      <toc-entry specific-use="book-app">
+        <label>Appendix A<x>.</x></label>
+        <title>Esoteric Secrets</title>
+        <nav-pointer rid="ltxid9"/>
+        <toc-entry specific-use="section">
+          <label>1<x>.</x></label>
+          <title>Appendix section</title>
+          <nav-pointer rid="ltxid10"/>
+        </toc-entry>
+      </toc-entry>
+      <toc-entry specific-use="book-app">
+        <title>Esotericer Secrets</title>
+        <nav-pointer rid="ltxid12"/>
+        <toc-entry specific-use="section">
+          <label>2<x>.</x></label>
+          <title>Another appendix section</title>
+          <nav-pointer rid="ltxid13"/>
+        </toc-entry>
+      </toc-entry>
+      <toc-entry specific-use="book-app">
+        <label>Appendix B<x>.</x></label>
+        <title>Esotericest Secrets</title>
+        <nav-pointer rid="ltxid14"/>
+        <toc-entry specific-use="section">
+          <title>Shout outs</title>
+          <nav-pointer rid="ltxid15"/>
+        </toc-entry>
+      </toc-entry>
+    </toc>
+    <notes id="ltxid3" notes-type="publishers-note" specific-use="epub-opening-page">
+      <title>Publisher’s Notice</title>
+      <p>The <ext-link xlink:href="https://www.ams.org">American Mathematical Society</ext-link> has provided this ebook to you without Digital Rights Management (DRM) software applied so that you can enjoy reading it on your personal devices. This ebook is for your personal use only and must not be made publicly available in any way. You may not copy, reproduce, or upload this ebook except to read it on your personal devices.</p>
+    </notes>
+  </front-matter>
+  <book-body id="ltxid4">
+    <book-part>
+      <body>
+        <sec disp-level="1" id="ltxid5" specific-use="chapter">
+          <label>Chapter 1</label>
+          <title>Chapter title</title>
+          <sec disp-level="2" id="ltxid6" specific-use="section">
+            <label>1<x>.</x></label>
+            <title>Introduction</title>
+            <p>Here is some text.</p>
+          </sec>
+        </sec>
+      </body>
+    </book-part>
+  </book-body>
+  <book-back id="ltxid7">
+    <book-app-group id="ltxid8">
+      <book-part-meta>
+        <title-group>
+          <title>Appendixes</title>
+        </title-group>
+      </book-part-meta>
+      <book-app id="ltxid9">
+        <book-part-meta>
+          <title-group>
+            <label>Appendix A</label>
+            <title>Esoteric Secrets</title>
+          </title-group>
+        </book-part-meta>
+        <body>
+          <p>Some text.</p>
+          <app disp-level="2" id="ltxid10" specific-use="section">
+            <label>1<x>.</x></label>
+            <title>Appendix section</title>
+            <p>Some text.</p>
+            <sec disp-level="3" id="ltxid11" specific-use="subsection">
+              <label>1.1<x>.</x></label>
+              <title>Appendix subsection<x>.</x></title>
+              <p>Some text.</p>
+            </sec>
+          </app>
+        </body>
+      </book-app>
+      <book-app id="ltxid12">
+        <book-part-meta>
+          <title-group>
+            <label>Appendix</label>
+            <title>Esotericer Secrets</title>
+          </title-group>
+        </book-part-meta>
+        <body>
+          <p>Some text.</p>
+          <app disp-level="2" id="ltxid13" specific-use="section">
+            <label>2<x>.</x></label>
+            <title>Another appendix section</title>
+            <p>Some text.</p>
+          </app>
+        </body>
+      </book-app>
+      <book-app id="ltxid14">
+        <book-part-meta>
+          <title-group>
+            <label>Appendix B</label>
+            <title>Esotericest Secrets</title>
+          </title-group>
+        </book-part-meta>
+        <body>
+          <p>Here is the real truth.</p>
+        </body>
+      </book-app>
+    </book-app-group>
+    <ack disp-level="2" id="ltxid15" specific-use="section">
+      <title>Shout outs</title>
+    </ack>
+  </book-back>
+</book>