Home

Nic's lwarp tutorial

lwarp is a TeX package, which allows to generate both a normal pdf file and an html version from the same .tex file.

The resulting pdf is identical to usual. The compilation process is unchanged.
The resulting html pages use MathJax/MathML to render equations, tables, etc.

So, the idea is that the pdf can be used 'as normal' for teaching, and the html pages may be used for accessibility purposes, or both for different parts of both, etc.

Most importantly, lwarp requires only minor changes to existing tex code. It supports a wide array of standard tex packages, and you can use it in combination with your usual tex editor. It seems to work nicely, so I wrote this wiki page on how to get started with it. For more detailed info see the lwarp documentation itself.

The lwarp package is developed by Brian Dunn at https://github.com/bdtc/lwarp.

Here's an example of the results, using Chapter 1 of my MAS350 notes

Here's the usual pdf file
Here's the first page of the HTML version, here's a later page with plenty of cross-referencing, environments and formulae
Here and here you can see the HTML version interacting nicely with Firefox's accessibility tools.
Here's the source code which generated them both - some extra bits at top, but its just a normal tex file!
Here is the whole source folder . Only MAS350-converted.tex was created manually.

Getting started

I assume you have a functional tex installation, and a tex editor. I recommend MiKTeX and TexMaker, on which this tutorial is based. You will also need a command line: on Linux use the terminal; on Windows I suggest Microsoft's PowerShell or the Ubuntu terminal via WSL, although cmd.exe will work too. I expect you also need administrator rights on your machine.

Installing lwarp

Instructions for miktex users:

Use the miktex console to fully update miktex, including the latest miktex-misc package
- Depending on your local configuration, you may have to do this in both admin mode and/or user mode of the console.
- If your miktex version is so old that it doesn't include the console, get a newer miktex version.
Use the miktex console to install the lwarp package

For other tex distributions, particularly those without console/package managers, see Section 4 of the lwarp documentation, or just mimic steps 1 and 2 as best you can. Note: on Debian lwarp comes with apt-get texlive-latex-recommended.

Testing lwarp with mathjax

Instructions for texmaker users:

Get the tutorial.tex file; you can type texdoc -l lwarp_tutorial.txt into the command line or retrieve it from here
Open tutorial.tex in texmaker
Find the commented out line mentioning mathjax, near the top, and uncomment it (this lets you use mathjax for formulae, rather than svg/perl)
Build the tex file within texmaker as normal, to produce tutorial.pdf
From the command line, run lwarpmk html in your working dir to generate tutorial_html.html
Open the pdf (in e.g. adobe) and the html file (in a browser) and check they look OK.

For other tex editors, I imagine it works the same... If not, try changing the build process to run only pdflatex, instead of e.g. pdflatex+bibtex+etc.

When you run lwarpmk html for the first time it seems you need to run it twice, just like with pdflatex (to get the cross referencing in). If it tells you the file is already up to date, use lwarpmk html1 to force a build.

Migrating existing tex files to lwarp

Try something small first... say, the first section of some lecture notes.

Make a copy of tutorial.tex, lets call it tutorial2.tex, put it in a separate folder
Open tutorial2.tex and read the messages in capital letters about what goes where:
- Add your packages in the appropriate place, noting that you must load hyperref and cleverref after the other packages (or some clashes may occur)
- Add your macros, environment defs, etc, immediately below where you put your packages
- Clean out the body text and copy in the stuff that you actually want
Tell mathjax about your macros:
- For each macro (i.e. \def, \newcommand and suchlike): add the exact same macro inside a \CustomizeMathJax{...} block.
- So for example, if you have \def\N{\mathbb{N}}, add a new line with \CustomizeMathJax{\def\N{\mathbb{N}}} on it
Sniff around above \begin{document} and fill in the details, like title/author fields, tocdepth, etc. These days I think it is a good idea to datestamp everything.
Build tex/html as instructed above

Migrating tex code

Although lwarp seems to be very good at supporting existing TeX packages, it's likely you'll still need to modify your code a bit. When you run lwarpmk html it gives a helpful error message if it can't process something, other things I only spotted by looking at the html file in a browser.

Sections 6 and 8 of the lwarp documentation list some limitations. Some are genuine, but many are just good coding practice. I didn't run into any of them, but here in brief are the ones that I guess will crop up most often:

Use png/jpg/svg with \includegraphics. Html doesn't support pdf/eps images. If you need pdf/eps images, lwarp contains some image conversion utilities; see the documentation.
Don't use \includegraphics[scale=...]{...}, instead use e.g. \includegraphics[width=0.5\linewidth]{...}.
Don't macro an enviroment e.g. don't define \beq as shorthand for \begin{equation} and so on (but \(, $ and $$ all work fine).
In section names, use $...$ instead of $...$ for math (because they get hashed and $s are ignored by the hash).
Don't hijack math mode to create superscripts in text mode e.g. use May 19\textsuperscript{th} and not May $19^{\text{th}}$.
Don't manually set the page counter. Setting other counters manually seems to be fine, though.
Use flushright, flushleft instead of raggedright, raggedleft. More generally, prefer environments over macros - lwarp basically works by injecting code into environments, behind the scenes.
Read Section 8.2.3 if you are a heavy user of hspace, vspace, vfill, hfill and suchlike (but you shouldn't be!).
Read Section 8.3 if you are a heavy user of minipages, boxes and frames.

Here's what I did run into (migrating two full courses in summer 2021, approx 350 pages in total).

Had to avoid having duplicate section headings; I had 5 subsections all called 'Exercises'. The command line of lwarpmk was helpful enough to tell me that adding e.g. \section[unique_identifier]{Duplicate title} solves the problem.
Mathjax didn't render my \def\1{\mathbbm{1}}, but you can get it via unicode: \CustomizeMathJax{\def\1{\unicode{x1D7D9}}} (there was no problem using mathbbm for equivalent \R, \N etc macros).
The showkeys package mildly conflicts with lwarp, and causes a blank page to appear before the pdf title page. This is not a problem, because showkeys has to be turned off anyway when you build your pdf for non-author users.
Had to change \begin{alignat} to $$\begin{alignedat}. This has the disadvantage that alignedat doesn't allow to label equations individually, which didn't matter in my case. Fortunately align itself works fine, so the limitation is reasonably small.

Accessibility

To increase the accessibility of HTML output:

You can add alt text to images with \includegraphics[alt={Some text.}]{filename}
I've made a sans serif version of the lwarp sagebrush skin. To use it, download the file and set \CSSFilename{sans-serif-lwarp-sagebrush.css}, which is found just above \begin{document}

Keeping file and folder structure clean

Running lwarpmk html creates a tonne of extra files. For a short tex document, using one folder per document is enough is sufficient to preserve sanity.

However, for additional sanity, you may wish to use this Python script, which runs lwarpmk and then moves/copies all necessary website files out of the working directory and into ./out_html/. For multiple linked documents, I suggest creating a more sophisticated version of that script to match your own project.

Misc

It's sensible to link to the first page within the notes, rather than the 'full page' [name]_html.html. This is because 100 pages of mathjax take a while to render, especially if for some reason you are trying to read them on a smartphone.

If you don't remember to turn on the mathjax option, lwarp will want to render equations as svg images, which is done by running lwarpml limages after you build the html as described above. To do this you must have perl installed (e.g. http://strawberryperl.com/, https://learn.perl.org/installing/unix_linux.html). The resulting html pages don't look as good as mathjax, perhaps also worse for accessibility purposes. I suggest not doing this.

If you're feeling adventurous you can check texmaker -> options -> configure texmaker -> commands, and hijack its build process to run both the pdf output and the html output automatically. I prefer working most of the time just with the tex/pdf inside texmaker, and only occasionally building the html.

Top level of how lwarp works: including the lwarp package causes the normal tex build process to output lots of extra info/files, which are then picked up by lwarpmk to generate the html. There is a lot of work going on to make it play nicely with commonly used tex packages. It knows about a wide range of specific environments (\begin{...} ... \end{...}) and uses the structure implicit from these to generate an html representation of the page.