search

AmerMathSoc / texml-to-html

Converting AmerMathSoc/texml output to raw HTML
Apache License 2.0
3 stars 2 forks source link

readme

texml-to-html

Converting texml-generated JATS/BITS-like XML to HTML.

Getting started

Quick example

For a first test run, try an example, e.g.,

Basic usage

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;
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:

The following custom tag names are preserved:

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.

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

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:

role values

The following ARIA-DPUB role attribute values are used:

texml XML to data-* mappings

The following provide a list from the reverse point of view.

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:

For books:

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.

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.

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.