@pretext-book/fragment

Take a PreTeXt fragment and embed it in a pretext document. Then, extract the fragment from the compiled output.

This can be used to make unit tests for PreTeXt implementations.

Fragments and Templates

A PreTeXt fragment looks like the following:

<FRAGMENT parents="chapter section[foo='bar']" template="article">
    <p>Some text and <m>math</m></p>
</FRAGMENT>

It represents a small piece of isolated PreTeXt code that will be inserted into a larger document (a template). The parents attribute is a CSS selector that determines what parent nodes will be dynamically created before being inserted into the template. For the fragment above, the code that would be inserted into the template is

<chapter>
    <section foo="bar">
        <p>Some text and <m>math</m></p>
    </section>
</chapter>

A template is a PreTeXt document with a single <FRAGMENT /> tag in it. For example

<?xml version="1.0" encoding="UTF-8" ?>
<pretext>
    <article>
        <FRAGMENT />
    </article>
</pretext>

When substituting into the template, the <FRAGMENT /> tag is replaced with the content of a PreTeXt fragment.

Installation

Make sure you have nodejs (>= v18) installed.

To install the fragment cli globally, run

npm install @pretext-book/fragment -g

To make a local installation, you'll need a directory with a package.json file. (One can be created for you by running npm init and answering the prompts.) Then run

npm install @pretext-book/fragment

Usage

If you installed globally (and you've configured your path to include npm-install-executables), you should have access to the pretext-fragment command. Otherwise, npx pretext-fragment should execute the fragment cli.

The fragment cli can be used to expand a template and to extract the contents of a template that has been rendered by PreTeXt. For example, if you have @pretext-book/fragment installed locally, you can run

npx pretext-fragment --fragment-file node_modules/@pretext-book/fragment/tests/fragments/p1.xml \
                     --template-file node_modules/@pretext-book/fragment/tests/templates/article.xml \
                     --out sample-main.ptx

sample-main.ptx should now contain a fully-expanded template ready to be compiled to HTML by PreTeXt.

Once the code is compiled, run

npx pretext-fragment --extract-from-html-file node_modules/@pretext-book/fragments/tests/rendered-fragments/p1.html \
                     --out p1-extracted.html

to extract the rendered portion of the fragment.

For more information on the fragment cli, run npx pretext-fragment --help.

Limitations

PreTeXt doesn't always leave clues about what PreTeXt elements render to what HTML. So, @pretext-book/fragment uses a heuristic: it applies unique and ordered ids to all parent elements of the fragment and then extracts the contents of the element with the smallest id in the output source. This means, if the inserted template has auto-generated siblings in the html output, those siblings will also show up in the extracted html.

Development

To develop, follow the instructions in the root directory of the @pretext-book monorepo.