BookML

Automated LaTeX to bookdown-style HTML and SCORM, powered by LaTeXML.

BookML is a small wrapper around LaTeXML for the production of accessible HTML content straight from LaTeX files, and for packaging it as SCORM. Created by and maintained for maths lecturers at the University of Leeds. Its main features:

• simple installation: simply drop the bookml folder next to the files to be compiled and copy GNUmakefile in the same place (well, uhm, that is a bit of a lie: you need to install LaTeXML first!)
• accessible and mobile friendly output: virtually identical to the GitBook style of bookdown, including font selection and dark mode, tweaked to meet the Web Content Accessibility Guidelines 2.1 level AA
• fully automated (re-)compilation based on which files have changed on disk, powered by GNU make: just run

  make

  to zip together all PDF and HTML outputs from all the main .tex files in the folder (one package per main .tex file)
• transparent generation of SVG images from TikZ pictures, animate animations, Xy-matrices, and virtually any other picture-like environment: just add a few lines of code in the preamble

  \usepackage{bookml/bookml}
  \bmlImageEnvironment{tikzpicture,animate}
  \iflatexml\else % prevent LaTeXML from even trying to load TikZ
  \usepackage{tikz}
  \usepackage{animate}
  \fi

• alternative text for images straight from LaTeX:

  \usepackage{bookml/bookml}\bmlImageEnvironment{tikzpicture}
  ...
  \begin{tikzpicture} ... \end{tikzpicture}\bmlDescription{Textual description of the TikZ picture}
  % alt= option for \includegraphics requires LaTeXML 0.8.7
  \includegraphics[alt={Text description of the figure}]{figure}

• arbitrary HTML content in LaTeX, such as foldable tags:

  \usepackage{bookml/bookml}
  ...
  \<DETAILS>
    \<SUMMARY>\textbf{Solution.}\</SUMMARY>
    To create a foldable `proof' environment, ...
  \</DETAILS>

• declare alternative PDF versions (for instance sans serif, large print):

  \bmlAltFormat{PDF (large print)}{notes-large-print.pdf}
  % you must provide notes-large-print.tex

  the files will be automatically compiled and included in the 'Download' menu of bookdown (see the example for more info)
• SCORM support: running make creates valid SCORM.*.zip packages supported by most Learning Management Systems (if not, please submit an issue!)

Getting started

1. Install the prerequisites.
2. Install/upgrade: unpack the latest BookML release and put the bookml folder next to your .tex files.
3. First install only: copy bookml/GNUmakefile next to your .tex files.
4. Run make (or gmake).

Or you can unpack the template to start with a working minimal example.

The BookML manual is an example of a LaTeX file compiled in GitBook and plain style and it describes all the options and ways to customise the output.

The Leeds BookML guide has further examples and tips for lecturers and detailed installation instructions (some specific to the University of Leeds), including for instance how to compile exercises with and without solutions, or how to produce various alternative PDFs from the same file.

Prerequisites

• LaTeXML (minimum 0.8.5, recommended 0.8.6 or later)
• for any image handling: the Perl module Image::Magick
• for handling EPS, PDF images: Ghostscript
• for BookML images (for Tikz and similar packages): Ghostscript, latexmk, preview.sty, dvisvgm (minimum 1.6, recommended 2.7 or later)
• for automatic PDF, HTML, zip, SCORM packaging: GNU make, latexmk, zip, optionally texfot