@amermathsoc/texml-to-html 15.1.0 → 15.2.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [15.2.0](https://github.com/AmerMathSoc/texml-to-html/compare/v15.1.1...v15.2.0) (2024-03-29)
+
+
+### Features
+
+* **formula.js:** mapAttributes() but from tex-math ([3e1f603](https://github.com/AmerMathSoc/texml-to-html/commit/3e1f603032d278fccc138bd20c2eda746a8f32e2)), closes [#441](https://github.com/AmerMathSoc/texml-to-html/issues/441)
+
+### [15.1.1](https://github.com/AmerMathSoc/texml-to-html/compare/v15.1.0...v15.1.1) (2023-12-13)
+
+
+### Bug Fixes
+
+* **mixed-citation.js:** fix HTML escaping ([4df1462](https://github.com/AmerMathSoc/texml-to-html/commit/4df14624280786ad870c4e0c2940275f6054eae8)), closes [#438](https://github.com/AmerMathSoc/texml-to-html/issues/438)
+
 ## [15.1.0](https://github.com/AmerMathSoc/texml-to-html/compare/v15.0.0...v15.1.0) (2023-11-23)
 
 

package/README.md

@@ -1,6 +1,6 @@
 # texml-to-html
 
-Converting texml-generated JATS/BITS-like XML to HTML.
+Converting [texml](https://github.com/AmerMathSoc/texml)-generated JATS/BITS-like XML to HTML.
 
 ## Getting started
 
@@ -8,16 +8,365 @@ Converting texml-generated JATS/BITS-like XML to HTML.
 
 For a first test run, try [an example](./examples), e.g.,
 
-* Install via npm: `$ npm i @amermathsoc/texml-to-html`
-* Process a test file: `$ node node_modules/@amermathsoc/texml-to-html/examples/cli.js node_modules/@amermathsoc/texml-to-html/text/article.xml > htmlOutput.html`
+- Install via npm: `$ npm i @amermathsoc/texml-to-html`
+- Process a test file: `$ node node_modules/@amermathsoc/texml-to-html/examples/cli.js node_modules/@amermathsoc/texml-to-html/text/article.xml > htmlOutput.html`
 
 ### Basic usage
 
 ```js
-import fs from 'fs';
-import path from 'path';
-import xml2html from '@amermathsoc/texml-to-html';
+import fs from "fs";
+import path from "path";
+import xml2html from "@amermathsoc/texml-to-html";
 
-const article = xml2html(fs.readFileSync(path.resolve(process.argv[2])).toString()).window.document;
+const article = xml2html(
+  fs.readFileSync(path.resolve(process.argv[2])).toString()
+).window.document;
 console.log(article.toString());
 ```
+
+## Overview
+
+Our general strategy for elements and attributes is to follow allow-lists and discard everything else.
+
+We primarily we are recursing through the input DOM, building the output DOM. Rarely, we deviate from this approach for practical reasons (e.g., for metadata extraction).
+
+### preserved elements
+
+Some elements in texml's XML output have the same name (and purpose) as in HTML. We preserve them in the output:
+
+- hr
+- p
+- pre
+- sup
+- sub
+- table
+- tbody
+- thead
+- th
+- tr
+- td
+
+### preseved attributes
+
+Some attributes in texml's XML output have the same name (and purpose) in HTML.
+
+As per our general strategy, we only preserve _some_ attributes on _some_ elements.
+
+- attribute names that are preserved
+  - class
+  - id
+  - rowspan
+  - colspan
+  - hidden
+- element names where those attributes are preserved
+  - all preserved elements (cf. above)
+  - abstract
+  - app
+  - boxed-text
+  - def-list
+  - def
+  - fig
+  - fn
+  - notes
+  - p
+  - preface
+  - ref-list
+  - sec-heading
+  - statement
+  - target
+  - term
+
+### `data-*` attributes
+
+Beyond HTML element and attributes, texml-to-html stores data in custom `data-*` attributes. The following lists should help as a guide to understand the this structural information.
+
+:warning: This list can easily fall out of date. It should be automated.
+
+#### `data-*` attribute values and origin
+
+- data-ams-doc
+  - titlepage
+  - subtitle
+  - article
+  - copyright-page
+  - copyright
+  - amsref
+  - paragraph
+  - subtitle
+  - sec-meta
+  - secheading
+  - {@specific-use} [sec, ack, front-matter-part, dedication, custom-meta]
+  - statement
+  - graphic
+  - inline-graphic
+  - math inline
+  - math block
+  - math tex [added in ams-html output]
+  - amsref
+  - stringname
+  - verse-group
+  - label
+  - title
+  - notes [on section, from XML notes element, cf. AmerMathSoc/texml-to-html#329]
+  - biblioentry [formerly role="doc-biblioentry" (deprecated)]
+  - tags - container for (duplicated) equation tags
+    - container is inside data-ams-doc="math block" elements
+    - ams-html uses these to generate the math panel DTs for equations
+- data-ams-doc-contrib
+  - {@content-type} [expected: "authors", "editors", "translators", "contributors"]
+  - {@contrib-type} [expected: "author", "editor", "translator", "contributor"]
+  - {@contrib-type} name
+- data-ams-doc-contrib-comment
+  - STRING
+- data-ams-style
+  - {styled-content@style-type} [expected: sans-serif]
+  - roman
+  - sc
+  - monospace
+  - underline
+  - {disp-quote@specific-use}
+  - (inline-)graphic{@specific-use}
+  - {@style} [expected: theorem styles]
+  - boxed (from boxed-text)
+- data-ams-ref
+  - {@ref-type} [expected: bibr, fn, disp-formula, sec, fig, table, algorithm, list, statement]
+  - notrid
+  - fn-return [added in ams-html output]
+- data-ams-doc-level
+  - [0-9]
+- data-ams-content-type
+  - {@content-type }
+  - { @notes-type } (for notes elements, cf. AmerMathSoc/texml-to-html#329)
+- data-ams-specific-use
+  - {@specific-use}
+- data-ams-qed-box
+  - BOOLEAN
+- data-ams-position
+  - anchor
+- data-ams-width
+  - graphic | inline-graphic @width
+- data-ams-height
+  - graphic | inline-graphic @height
+- data-ams-doc-alttitle
+  - alt-title (book only, for sectioning content only)
+
+##### 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.
+We list the attribute names, the related tools and purpose:
+
+- [deprecated] data-eqn-tag-#
+  - superceded by data-ams-tags (cf. earlier)
+  - ams-eqn-store used to use these numbered attribute names to store extracted equation tags for downstream use (e.g., ams-html math panel)
+- [deprecated] data-ams-tags
+  - this attribute contained a stringified array of equation tag strings
+  - while initially generated by texml-to-html, ams-eqn-store overwrote them with rendered output if TeX was present in the strings.
+
+<!-- NOTE move to another location if it grows enough -->
+
+##### `role` values
+
+The following [ARIA-DPUB](https://w3c.github.io/dpub-aria/) role attribute values are used:
+
+- doc-preface
+- doc-bibliography
+- doc-appendix
+- doc-dedication
+- doc-noteref
+- doc-biblioref
+- doc-footnote
+- doc-chapter
+- doc-abstract
+- doc-toc
+- doc-footnote
+- doc-appendix
+
+#### texml XML to `data-*` mappings
+
+The following provide a list from the reverse point of view.
+
+- book
+  - book-id[@book-id-type = 'publ_key'] => data-ams-doc="series"
+  - book-meta => data-ams-doc="titlepage"
+    - contains JSON blob with book-meta, collection-meta; cf. metadata section in this document
+  - book-back//ref-list => data-ams-doc-level="1
+  - book//sec/alt-title => data-ams-doc-alttitle
+- article => data-ams-doc="article" [this is a somewhat messy part as we pick and choose, sort of reversely; much of it repeated on copyright page without data attributes]
+  - front => data-ams-doc="frontmatter" (some info in head element)
+    - contains JSON blob with (most of) journal-meta, article-meta; cf. metadata section in this document.
+    - the folllowing descendants create additional HTML (since they may contain tex-math):
+      - article-meta>title-group => passthrough
+      - notes => data-ams-doc=notes with data-ams-content-type (for @notes-type)
+      - abstract => via role
+      - kwd-group's => data-ams-doc with @vocab or "keywords"
+      - funding-group => data-ams-doc=funding-group
+- styled-content => data-ams-style="{@style-type}"
+  - roman => data-ams-style="roman"
+    - or `\textrm{...}` (if inside `text`)
+  - sc => data-ams-style="sc"
+    - or `$\mathsc{...}$` (if inside text)
+  - monospace => data-ams-style="monospace"
+    - or `\texttt{...}` (if inside text)
+  - underline => data-ams-style="underline"
+- disp-quote => data-ams-style="{@specific-use}"
+- xref => data-ams-ref="{@ref-type}"
+  - xref[not(@rid)] => data-ams-ref="notrid" [but note on ref-type=fn, bibr]
+  - or `\xhref[@ref-type]{#@rid}{...}` (if inside disp/inline-formula)
+- p//p => data-ams-doc="paragraph"
+- fn/label => data-ams-doc="label"
+- statement/secheading/title | statement/secheading/label => data-ams-doc="secheading"
+- mixed-citation => data-ams-doc="biblioentry" [formerly role="doc-biblioentry" (deprecated)]
+- sec | ack | front-matter-part | front-matter/dedication => data-ams-doc="{@specific-use}"
+  - [e.g., sec/title | app/title | sec/label | app/label | front-matter-part/title]
+    - subtitle => data-ams-doc="subtitle"
+    - sec-meta => data-ams-doc="sec-meta" + "data-ams-contributors" (json blob, cf. metadata section in this document) + "data-ams-byline" (pre-generated byline)
+    - label => data-ams-doc="label"
+    - title => data-ams-doc="title"
+- abstract => role="doc-abstract">
+- statement => data-ams-doc="statement"
+- graphic | inline-graphic => data-ams-doc="{name()}" data-ams-style="{@specific-use}"
+  - graphic | inline-graphic @width => data-ams-width
+  - graphic | inline-graphic @height => data-ams-height.
+- inline-formula => data-ams-doc="math inline" OR `$...$`
+  - within disp/inline-formula, inline-formula may appear inside text. In that case, we have to create TeX strings for MathJax to process, wrapped in `$`
+- disp-formula => data-ams-doc="math block"
+- disp-formula-group => data-ams-doc="statement" data-ams-content-type="disp-formula-group"
+- raw-citation => data-ams-doc="amsref"
+- string-name => data-ams-doc="stringname"
+- verse-group => data-ams-doc="verse-group"
+- boxed-text => div@data-ams-style="boxed"
+- notes => section with data-ams-doc="notes"
+  - @notes-type => @data-ams-content-type (and role=dedication for dedications)
+  - use cases: dedication (articles), article and section notes (NOTI only), drm notice & epub note (books)
+- attributes
+  - @disp-level => data-ams-doc-level [data-ams-doc-level is also added to some elements that lack disp-level]
+  - @content-type => data-ams-content-type
+  - @style => data-ams-style
+  - @specific-use => data-ams-specific-use [sometimes mapped to other attributes, e.g., style]
+  - @has-qed-box => data-ams-qed-box
+  - @position => data-ams-position
+  - @text-color, @background-color, @border-color => data-ams-style-color (as combined CSS declarations)
+    - currently appears on: boxed-text, styled-content
+
+### metadata handling
+
+Publication metadata (both journal/series and article/book metadata) is primarily stored in a JSON blob in a `script` tag in the frontmatter (for articles) and titlepage (for books) sections respectively.
+
+Section metadata (contributor metadata and pre-generated byline) is stored similarly as a json blob inside the `data-ams-contributors` attribute.
+
+The relevant components in `texml-to-html` (i.e., `article-metadata-json.js`, `book-meta-json.js`, `sec-meta.js`) should provide a (hopefully easy enough) overview how the XML metadata is mapped and stored. The snapshots in the `test` folder should also be helpful, alongside any (example) article's JSON blob.
+
+The following are commonly found metadata items:
+
+For journal articles:
+
+- `<article-meta>`
+  - `<contrib-group>` etc (cf. "contributors" below)
+  - `<self-uri>`
+  - `<title-group>` etc
+  - `<pub-date>` etc
+  - `<notes>`
+  - `<kwd-group>`
+    - MSC (using `<compound-kwd>` etc)
+    - article keywords (using `<kwd>`)
+  - `<related-article>` etc (correction/erratum forward/backward)
+  - `<custom-meta-group>` (communicated by, NOTI categories, NOTI titlepic)
+  - `<funding-group>` / `<funding-statement>`
+  - `<permissions>`
+    - `<copyright-statement>`
+  - `<history>` etc
+  - `<article-id>` etc
+  - `<abstract>` etc
+  - `<volume>`, `<issue>`
+- `<journal-meta>`
+  - `<journal-id>`
+  - `<journal-title-group>` etc
+  - `<issn>` etc
+  - `<publisher>`
+  - `<self-uri>` etc
+
+For books:
+
+- `<collection-meta>`
+  - `<publisher>` etc
+  - `<title-group>`
+  - `<volume-in-collection>`
+    - `<volume-number>`
+  - `<custom-meta-group>` (for subseries)
+    `<book-meta>`
+  - `<book-id>` etc
+  - `<book-title-group>` etc
+  - `<book-volume-number>`
+  - `<publisher>`
+  - `<contrib-group>` etc (cf. "contributors" below)
+  - `<self-uri>`
+  - `<title-group>` etc
+  - `<pub-date>` etc
+  - `<notes>`
+  - `<issn>`
+  - `<isbn>`
+  - `<permissions>`
+- `<front-matter>`
+  - `<toc>` etc
+  - `<notes>`
+  - `<preface>`
+  - `<front-matter-part>`
+
+### math mode
+
+**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.
+
+#### 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.
+
+#### 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.
+
+- `text` only appears inside tex-math; it is converted to `\\text{...}`
+- `italic` creates `\textit{}`
+- `bold` creates `\textbf{}`
+- `roman` creats `\textrm{...}`
+- `sc` creates `$\mathsc{...}$`
+- `monospace` creates `\texttt{...}`
+- `ext-link` creates `\href{}{}` as(which works in both text and math mode)
+
+#### nested math mode
+
+In the case where math mode is nested (math mode inside text mode inside math mode), we have to adjust our processing to create MathJax-compatible TeX strings.
+
+- nested math mode can only appear within text and will only be inline-formula which is (essentially) converted to `$...$`
+
+### algorithm layout
+
+**Note.** Since the markup and attributes are heavily scoped, we do not reproduce the attributes in other sections.
+
+Texml creates pseudo-namespaced elements for algorithm layout (e.g., from algorithmicx pacakge).
+
+We convert the markup to HTML custom elements with attributes. Further processing happens downstream to enable adequate styling.
+
+- alg:algorithm => alg-algorithm
+- \*alg:line => alg-line
+  - @lineno => alg-lineno (preceding sibling of alg-line)
+  - data-ams-alg-spanslineno (if first child is alg:require or alg:ensure)
+- alg:block => alg-block
+  - data-ams-alg-blocklevel (calculated from nesting)
+- alg:statement, alg:require, alg:ensure, alg:globals => alg-statement
+- alg:comment => alg-comment
+- pass through:
+  - alg:body
+  - alg:outputs
+  - alg:inputs
+  - alg:condition
+  - alg:if
+  - alg:elsif
+  - alg:else
+  - alg:for
+  - alg:forall
+  - alg:while
+  - alg:repeat
+  - alg:until
+  - alg:loop

package/lib/elements/formula.js

@@ -14,6 +14,8 @@
  *  limitations under the License.
  */
 
+import mapAttributes from '../helpers/mapAttributes.js';
+
 /**
  * inline-formula and disp-formula element
  * @param {HTMLElement} htmlParentNode 
@@ -38,12 +40,11 @@ export default function (htmlParentNode, xmlnode) {
   const span = this.createNode('span', '', {
     'data-ams-doc': `math ${mathMode}`
   });
+  mapAttributes(span, xmlnode.querySelector('tex-math'));
   htmlParentNode.appendChild(span);
   const hasLinkedTag = xmlnode.querySelector('target tag');
   const tagContainer = `<span hidden data-ams-doc="tags"></span>`; //NOTE we store copies of tags for easier re-use downstream (cf. tags.js) except for text equations
   if (hasLinkedTag) span.insertAdjacentHTML('afterbegin', tagContainer)
-  if (mathMode === 'block' && xmlnode.querySelector('tex-math[has-qed-box]'))
-    span.setAttribute('data-ams-qed-box', 'true');
   this.passThrough(span, xmlnode);
   // NOTE we (sometimes?) get extra whitespace from childnodes; needs test
   const text = span.innerHTML;

package/lib/elements/mixed-citation.js

@@ -28,7 +28,7 @@ export default function (htmlParentNode, xmlnode) {
   this.passThrough(div, xmlnode);
   const rawCitation = xmlnode.parentNode.querySelector('raw-citation');
   if (!rawCitation) return;
-  const code = this.createNode('code', rawCitation.textContent, {
+  const code = this.createNode('code', rawCitation.innerHTML, {
     'data-ams-doc': 'amsref'
   });
   div.appendChild(code);

package/lib/elements/sec.js

@@ -77,7 +77,7 @@ export default function (htmlParentNode, xmlnode) {
     section.setAttribute('role', 'doc-introduction');
 
   // book appendices
-  if (tagName === 'book-app-group') {
+  if (tagName === 'book-app-group' && xmlnode.querySelectorAll(':scope > book-app').length > 1) {
     // NOTE might become redundant if book-app-group gets specific-use=part
     section.setAttribute('role', 'doc-part');
     section.setAttribute('data-ams-doc', 'part');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amermathsoc/texml-to-html",
-  "version": "15.1.0",
+  "version": "15.2.0",
   "type": "module",
   "description": "A NodeJS library for converting AMS-style JATS XML to HTML",
   "scripts": {

package/test/article.xml

@@ -384,7 +384,7 @@
                 <tex-math><text>Te#t </text><xref ref-type="fn" rid="fnid1">1</xref><fn id="fnid"><label>1</label><p><xref ref-type="fn" rid="fnid1">1</xref></p></fn><xref ref-type="other" rid="otherid1"></xref></tex-math>
                 </inline-formula>
             </p>
-            <disp-formula><tex-math has-qed-box="true"><xref ref-type="fn" rid="fnid2">2</xref><fn id="fnid2"><label/></fn><text>Start<xref ref-type="other" rid="otherid2">$</xref>End</text></tex-math></disp-formula>
+            <disp-formula><tex-math has-qed-box="true" specific-use="special"><xref ref-type="fn" rid="fnid2">2</xref><fn id="fnid2"><label/></fn><text>Start<xref ref-type="other" rid="otherid2">$</xref>End</text></tex-math></disp-formula>
             <disp-formula>
                 <tex-math>
                     <text><roman>roman#</roman> <sc>sc$</sc> <italic>italic_</italic> <bold>bold$</bold> <sans-serif>sans-serif&amp;</sans-serif> <monospace>monospace</monospace> <ext-link xlink:href="https://ext~">ext-link~</ext-link> inside text</text>
@@ -581,7 +581,7 @@
             <title>References</title>
             <ref id="ref">
                 <label>Label</label>
-                <raw-citation>Raw</raw-citation>
+                <raw-citation>Raw &lt;p</raw-citation>
                 <mixed-citation>Mixed</mixed-citation>
             </ref>
             <ref id="refnolabel">

package/test/element-inline-formula-disp-formula-tex-math.js

@@ -18,7 +18,7 @@ import { article } from './helper.js';
 import tape from 'tape';
 
 tape('inline-formula, disp-formula, tex-math', async function (t) {
-  t.plan(18);
+  t.plan(19);
   const document = article;
   const inlineformula = document.querySelector(
     '#equations [data-ams-doc="math inline"]'
@@ -55,6 +55,11 @@ tape('inline-formula, disp-formula, tex-math', async function (t) {
     'true',
     'has-qed-box'
   );
+  t.equal(
+    displayformula.getAttribute('data-ams-specific-use'),
+    'special',
+    'disp-formula gets attributes from tex-math mapped'
+  );
   t.ok(
     displayformula.innerHTML.includes('\\xhref[fn]{#fnid2}{{}^{2}}'),
     'tex-math/xref@ref-type="fn"'

package/test/element-mixed-citation.js

@@ -19,7 +19,7 @@ import { article } from './helper.js';
 import tape from 'tape';
 
 tape('Template: mixed-citation', async function(t) {
-  t.plan(2);
+  t.plan(3);
   const document = article;
   const mixedCitation = document.querySelector(
     'dd > div[data-ams-doc="biblioentry"]'
@@ -29,4 +29,5 @@ tape('Template: mixed-citation', async function(t) {
   );
   t.ok(mixedCitation, 'Element mixed-citation');
   t.ok(rawCitation, 'Element raw-citation');
+  t.equal(rawCitation.innerHTML, 'Raw <p', 'Raw citation escaping');
 });