3 Reference manual

This section follows closely the reference manual on the BookML repository, but may lag behind new versions.

3.1 Package options

BookML can be configured by loading the bookml/bookml package and passing options to it like with any other LaTeX packages, for instance \usepackage[mathjax=4]{bookml/bookml}. The following options are available:

style=<name>: Switch style. <name> can be gitbook (default), which is almost identical to the output of bookdown, plain, which is a tweaked version of the normal LaTeXML style, and none for the default LaTeXML style with minimal compatibility and bug fixes only.
mathjax=<number>: Select which MathJax version to use from 2, 3, 4 (default).
nomathjax: Disable MathJax.
imagescale=X.XX: (Deprecated) Rescale all images generated via LaTeX (using bmlimage, see below) by the desired factor. Images are normally sized so that fonts inside the image match the font size of the browser, but there have been cases where BookML is wrong, and images turn out too small or too large. When that happens, tweak imagescale, and please report the issue.
nohtmlsyntax: Do not define the command \< used for writing html tags directly in TeX.
draft: Do not compile and include the alternative formats and do not generate the BookML images. BookML images will be replaced by file names.
final: Compile and include the alternative formats and generate the BookML images (default behaviour if neither of <code>draft</code>, <code>final</code> is specified).

3.2 Package commands and environments

Loading \usepackage{bookml/bookml} makes the following commands available. It also loads the latexml package, which provides additional commands such as \iflatexml and \lxRequireResource.

\BookMLversion: The currently running version of BookML.
\bmlAltFormat[<opts>]{<file>}{<label>}: Compile (if necessary) and include <file> in the download menu with label <label>. An empty label removes the file from the download menu. The optional argument <opts> is a key-value list passed internally to \lxRequireResource (for instance, use type=application/octet-stream if LaTeXML is not able to recognise the MIME type of the file). Only available in the gitbook style.
\<: Open or close an html tag, as in \<span class="example">some \LaTeX{} code\</span>. The content between the tags is normal LaTeX code. If necessary, the behaviour of each tag can be changed with the \bmlHTML*Environment commands. Tags will normally generate an additional <p>...</p> tag, unless the HTML5 spec says that they can only contain ‘phrasing content’ or that they are ‘transparent’, or if their direct descendants are also HTML tags. The text between \< and > is parsed following the HTML5 spec, except that all tags need to be closed, /> closes non-void tags, and only the basic XML enties are supported.
\bmlHTMLEnvironment{<tag>}: Introduce or redefine an html tag environment, to be used as \begin{h:tag}[attr1=val1,...]...\end{h:tag} or as \<tag>.
\bmlHTMLInlineEnvironment{<tag>}: Introduce or redefine an html tag environment which accepts ‘phrasing content’ only or is ‘transparent’.
\bmlRawHTML{<html>}: Insert <html> directly in the output document, after expanding all the TeX macros. Special characters are handled like in \href from the hyperref package: you should use \\ to enter a literal backslash, while other special characters can be escaped as \#, \%, \&, \& when necessary. When the command appears in the preamble, <html> will be part of the head and will be copied in every output page. <html> must be written in valid XML syntax, with either no namespace or the correct namespace for html. The HTML5 syntax is currently not supported.
\begin{bmlimage}: The body of this environment is compiled directly into an SVG image via LaTeX, instead of running through LaTeXML.
\bmlImageEnvironment{<env>}: Compile all environments <env> directly into SVG images via LaTeX, instead of running them through LaTeXML. The most typical example is \bmlImageEnvironment{tikzpicture} for when LaTeXML struggles to process TikZ pictures properly or sufficiently quickly. Warning: this will not work properly when the environments are called implicitly (for instance, the package tcolorbox uses \begin{tikzpicture} internally to implement its theorems, and that could results in theorems appearing as images, and in the wrong places).
\bmlDescription{<text>}: Attach an alternative text <text> to the immediately preceding object. Only useful for images, for instance immediately after \end{tikzpicture}. Warning: the command must immediately follow the object; even empty spaces can cause issues.
\bmlPlusClass{<class>}: Add the css class <class> to the immediately preceding object (this complements \lxAddClass and \lxWithClass provided by the latexml package). Warning: the command must immediately follow the object; even empty spaces can cause issues.
\bmlDisableMathJax: Disable running MathJax on the current mathematical content. When used in an environment that generates multiple equations, it applies only to the current one.

3.3 Makefile options

The build process accepts configuration options via Make variables, using the syntax VARIABLE=value to replace a value and FLAGS+=moreflags to append more values. Changing the settings will automatically recompile the files that are affected. To apply an option only to the outputs of file.tex, use file_VARIABLE and file_FLAGS (normal variables are replaced, while file_*FLAGS variables are added to the general *FLAGS values). Special characters in the file name must be replaced with _; for instance use sheet1_solutions_SPLITAT to control the outputs of sheet1+solutions.tex. Comments can be added by starting the line with #.

For instance, the following GNUmakefile specifies that the files to compile are notes.tex and exercises.tex only (instead of every .tex file with \documentclass), that they must be compiled to SCORM packages, and that exercises.tex must not be split by section. Moreover, exercises.tex should be complied using LuaTeX.

SOURCES=notes.tex exercises.tex

include bookml/bookml.mk

FORMATS=scorm

# exercises is split into small sections but we want a single HTML page

exercises_SPLITAT=

exercises_LATEXMKFLAGS=-pdflua

The options can be passed in four ways:

1.

Written in GNUmakefile, with each option on its own line, without indentation. You typically want to put the values before include bookml/bookml.mk, for instance to avoid scanning the .tex files when you are overriding SOURCES. Moreover, AUX_DIR **must** appear **before** include bookml/bookml.mk. On the other hand, adding flags with += **must** be done **after** include bookml/bookml.mk.
2.

On the command line as make VARIABLE=value. Appending is not supported on the command line.
3.

In your shell environment.
4.

In GNUmakefile applied directly to the target, like file.pdf: LATEXMKFLAGS = -pdflua. This is discouraged: it behaves consistently **only if applied to the ultimate affected target**. For instance, SPLITAT must be applied to $(AUX_DIR)/html/file/index.html. If applied to file.zip by mistake, the variable may or may not take effect depending on its value on SCORM.file.zip, potentially leading to an infinite loop. Use file_SPLITAT instead.

Changing the configuration will trigger a recompilation of the files that are affected. For instance, changing file_SPLITAT will cause file/index.html to rebuild, but not file.pdf, nor notes/index.html.

For more information about the Makefile syntax and how variables are evaluated, consult the GNU Make manual.

AUX_DIR: Location of the directory containing all intermediate files generated during compilation, such as .aux and .bbl files. This option is ignored by the BookML GitHub action. Default auxdir.
SOURCES: Space-separated list of .tex files to be compiled. File names with spaces are not supported. Default is the list of .tex files in the current directory that contain the string \documentclass (even if appearing in a comment!).
FORMATS: Spaces-separated list of formats to be generated from SOURCES. Recognised formats are pdf, scorm, zip. Default scorm zip.
SPLITAT: How to split the html output into multiple files (chapter, section, subsection, subsubsection). Set to empty to disable splitting. See the latexmlpost manual, --split option, for more details. Warning: when applied to a single target, it must be applied to $(AUX_DIR)/file/index.html: instead of say file.zip:, otherwise zip and SCORM outputs will see different values. Default section.
CURL: Command to call curl. Default curl (if present).
DVISVGM: Command to call dvisvgm. Default dvisvgm (if present).
DVISVGMFLAGS: Options to pass to dvisvgm. Default --no-fonts --optimize.
EPSTOSVG_CONVERTER: Select which converter to use for converting EPS images to SVG. Currently supported values are auto, dvisvgm, inkscape; auto will look for dvisvgm, inkscape in that order. If set to empty, LaTeXML will convert EPS to PNG using ImageMagick. Default auto.
INKSCAPE: Command to call inkscape. Default inkscape (if present).
INKSCAPEFLAGS: Options to pass to inkscape. Default --without-gui.
LATEXMK: Command to call Latexmk. Default latexmk.
LATEXMKFLAGS: Command options to pass to Latexmk. For instance, use LATEXMKFLAGS=-pdflua to use LuaTeX when compiling to PDF. Please ensure that Latexmk will produce a PDF rather than a DVI.
LATEXML: Command to call LaTeXML. Default latexml.
LATEXMLFLAGS: Options to pass to LaTeXML.
LATEXMLPOST: Command to call latexmlpost. Default latexmlpost.
LATEXMLPOSTFLAGS: Options to pass to latexmlpost.
MUTOOL: Command to call mutool. Default mutool (if present).
MUTOOLFLAGS: Options to pass to mutool draw.
PDFTOCAIRO: Command to call pdftocairo. Default pdftocairo (if present).
PDFTOCAIROFLAGS: Options to pass to pdftocairo.
PDFTOSVG_CONVERTER: Select which converter to use for converting PDF images to SVG. Currently supported values are auto, dvisvgm, inkscape, mutool, pdftocairo; auto will look for mutool, pdftocairo, dvisvgm, inkscape in that order. If set to empty, LaTeXML will convert PDF to PNG using ImageMagick. Default auto.
PERL: Command to call Perl. Default perl.
TEXFOT: Command to call texfot. Default texfot.
TEXFOTFLAGS: Options to pass to texfot.
UNZIP: Command to call unzip. Default tar (if present) on Windows, unzip (if present) on other platforms.
ZIP: Command to call zip. Default zip (or miktex-zip if zip.exe is not available on Windows).

3.4 Makefile targets

The following targets can be used as arguments when calling make, for instance make zip.

all: Compile all targets, based on the content of SOURCES, FORMATS, and TARGETS. This is the default target.
check-for-update: Check if there is a new release of BookML available.
clean: Delete all compilation products, based on SOURCES, FORMATS, and TARGETS.
detect: Detect the versions of all the software required to run BookML and print them.
html: Compile all SOURCES to html. The outputs will be in the $(AUX_DIR)/html directory.
pdf: Compile all SOURCES to PDF. The outputs will be in the current directory, including the SyncTeX files.
scorm: Compile all SOURCES to SCORM. The outputs will be in the current directory.
update: Experimental: update the bookml/ directory. If BookML is being run from a Docker image, it will use the version bundled in the image, otherwise it will download the latest release. This operation is destructive, not well tested, and behaviour may change in the future; be prepared to download BookML manually if it breaks.
xml: Compile all SOURCES to XML. The outputs will be in the $(AUX_DIR)/xml directory.
zip: Compile all SOURCES to zip. The outputs will be in the current directory.

3.5 Custom css, Javascript, …

The css files in the folder bmluser are automatically included at the end of the <head> tag and will override the previous styles. You may also include Javascript files (file extension js) and fonts (file extensions ttf, woff, woff2)

If the file name ends with .style1,style2-jobname.css, then that file will be used only when style=style1 is passed, or when style=style2 is passed and the main file being compiled is called jobname.tex. You can use ._all.css to ensure that the file is included in every style.

Custom css can also be added using \bmlRawHTML{<style> ... </style>} to the preamble, and likewise for \bmlRawHTML{<script> ... </script>}.

For instance, the plain version of this manual has been compiled with latin-modern.plain.css that sets the font to Latin Modern.

3.6 Others

bml_no_invert: Applying this css class disable the color inversion of images in dark mode. This applies only to external images, such as EPS figures, or pictures converted using bmlimage. The class can be applied to the image itself or to a surrounding paragraph, section, environment, etc. using one of \lxAddClass, \lxWithClass, \bmlPlusClass.

3.7 Options for the BookML GitHub action

Below is the list of arguments recognised by the BookML GitHub action. The list may be incomplete; see the BookML action page for details about the latest version.

checkout: Whether to checkout the repository calling this action. Default: true (boolean).
release: Whether to create a release containing the outputs generated by BookML. Default: true (boolean).
upload-aux-directory: Whether to upload the entire aux directory, which contains all outputs generated by BookML as well as logs and other intermediate files, into a GitHub artifact attached to the workflow run. Default: true (boolean).
scheme: Select which TeX Live scheme to use among basic, small, medium, full. Default: 'full' (string).
version: Select which version of BookML to use. Note that this only affects which Docker image is used; if the bookml/ folder is already present in the repository, that version of BookML will be used. Default: 'latest' (string).
replace-bookml: Whether to replace the bookml/ folder with the one included in the Docker image. Default: false (boolean).
timeout-minutes: The maximum number of minutes to run BookML before cancelling the build. Default: 6 (positive integer).

The action has the following outputs.

outputs: File names of all outputs compiled by BookML.
targets: File names of all targets that BookML tried to compile.
outcome: Compiling outcome (one of 'success', 'failure', 'timeout', 'invalid', 'cancelled').
aux-directory-url: URL of GitHub artifact containing the aux directory (only if upload-aux-directory is true).
release-url: URL of GitHub release (only if release is true).