The packages latexmk, preview.sty, dvisvgm and texfot are distributed by MiKTEX, TEX Live, and virtually all Linux distributions.

For the rest of the software, follow the instructions below.

Unzip the template.zip file from the latest BookML release. Open a terminal in the directory containing Makefile, template.tex, and run

make detect

…or gmake detect on Windows.

Use gmake detect on Windows. You should get something like the following:

Anything missing will show a red NOT FOUND. If the version is too old, there will be a red or a yellow prompt to upgrade.

First try? Run make (or gmake on Windows). After a bit, you will find a folder template and two zip files template.zip, SCORM.template.zip. Please open template/index.html and verify that it looks as you would expect. The zip files are set up for upload on Minerva.

To update BookML, simply replace the bookml folder with the content of a newly downloaded bookml.zip.

Once your are satisfied that the template is working, drop your own files next to template.tex: each file containing \documentclass will be treated the same as template.tex, and will be compiled to PDFs, SCORM and zip packages. Run make detect again, and check that ‘Main files’ contains such new files.

There is now a reasonable chance that your files are already working (unless you are using TikZ, which needs some care), but before your first try, you should truncate your files with an early \end{document}, as compilation times can be long and most errors will originate in the preamble anyway.

To compile, do the following:

• •
  ​

  Run

  ⬇

  make
  

  On Windows, it is gmake rather than make.

  After a bit, you will have files named like lecturenotes.zip, SCORM.lecturenotes.zip. The former works with ‘Upload Zip package’; the latter with ‘Create SCORM package’.

  To generate one particular package, for instance the one for the file lecturenotes.tex, run

  ⬇

  make lecturenotes.zip
  

  or, if you are using SCORM packages,

  ⬇

  make SCORM.lecturenotes.zip
  

• •
  ​

  When you change a file and want to regenerate the zip files, just run make again. Only the files that need updating will be recompiled.

• •
  ​

  You may occasionally get errors like

  ⬇

  No rule to make target 'bookml-short-guide.toc', needed by 'auxdir/bookml-short-guide.pdf'.
  

  If that happens, run make a second time. If the error is still there, run make clean-aux, or delete the auxdir folder, to reset BookML.

Consult template.tex for the minimal requirements in the preamble (e.g. you must provide a \title command). You should create copies of template-sans.tex, template-sans-large.tex for each of your main files, at least as a baseline. Alternative versions can be customized and removed, as explained in the next subsection. We recommend offering some alternative versions as good practice.

You should also follow the key requirements below.

• •
  ​

  Use the babel package to set the document language (crucial for screen readers to work correctly). For instance:

  ⬇

  \usepackage[british]{babel}
  

• •
  ​

  Set the document metadata in the preamble (essential for proper navigation links, web page titles, SCORM package metadata, and so on).

  ⬇

  \title{LaTeXML + BookML guide}
  
  \author{Vincenzo Mantova}
  

• •
  ​

  Ensure all TEX style formatting commands (\Large, \bf, …) are enclosed between braces, and use LATEX alternatives such as \textbf{} when possible. If you see the wrong font in the HTML output, it is likely caused by TEX-style font switches that haven’t gone well.

  ⬇

  {\bf some bold text}    % DO
  
  \bf some bold text      % DON'T
  
  \textbf{some bold text} % BEST
  

• •
  ​

  Using TikZ or XY-pic and an old version of LATExml (before 0.8.7)? Follow the instruction below right away. Without it, LATExml will take several minutes longer (regardless of the size of the file) and often produce broken images. Since version 0.8.7, LATExml has become more capable, and 0.8.8 can produce excellent TikZ pictures as well as tikzcd diagrams.

To create an alternative PDF meant to be included in the same SCORM or zip package (such as a large print PDF), for instance for the lecturenotes.zip package, add the following to the preamble of lecturenotes.tex:

  \usepackage{bookml/bookml} % if not already in your preamble

  \bmlAltFormat{lecturenotes.LARGE.pdf}{PDF (large print)}

and create a corresponding lecturenotes.LARGE.tex that

• •
  ​

  does NOT contain \documentclass (or it will be compiled into its own SCORM and zip packages);

• •
  ​

  configures e.g. different fonts and margins, then call \input{lecturenotes.tex}.

BookML will automatically compile and include lecturenotes.LARGE.pdf in your final outputs.

Consult template.tex, template-sans.tex, template-sans-large.tex for some simple techniques to achieve this.

If you instead want distinct SCORM and zip packages, for instance compile a problem sheet both with and without solutions, explore example.zip to see some possibilities.

Once you have language and metadata in place, follow the advice below to improve the chances your file will compile correctly, especially if you use TikZ or XY.

If LATExml does not recognise a particular package or class, it is sometimes easy to make it work, but it can also be near impossible.

• •
  ​

  If you use your own custom-made package or class to keep your favourite packages and options (so essentially a fancy preamble): change its extension to .tex and use \input instead of \usepackage.

• •
  ​

  If the package is producing images: use the same strategy as for TikZ, and remember to provide alternative text.

• •
  ​

  If LATExml supports a similar package: replace it (for instance, use actuarialangle instead of lifecon).

• •
  ​

  If the package is PDF-specific: use \iflatexml and \newcommand in the preamble to define macros that do something equivalent, or nothing at all, in HTML. Useful, for instance, for references including page numbers, or setting headers and footers.

• •
  ​

  If the class is not supported, tell LATExml to use a different class:

  ⬇

  % just like \usepackage, but before \documentclass
  
  \RequirePackage{bookml/bookml}
  
  \iflatexml
  
  \documentclass[12pt]{book}
  
  \else
  
  \documentclass[12pt]{memoir}
  
  \fi
  

  Make sure you pass your class options are consistent, for instance use the same font size.

• •
  ​

  If none of the above works, copy the missing macros directly from the package (or class) and add them to your preamble (usually within \makeatletter and \makeatother). It may work for simple packages, or packages partially supported by LATExml.

• •
  ​

  Generalising the last idea, you can tell LATExml to read the entire package or class as if you were using \input. To do this, create a file named package.sty.ltxml in the same folder as the .tex file (replace package with the actual package name, and sty with cls if dealing with a class):

  ⬇

  use LaTeXML::Package;
  
  InputDefinitions('package', type => 'sty', noltxml => 1);
  
  1;
  

  This will instruct LATExml to read the content of package.sty. This may work wonderfully, or crash miserably.

The bookml package automatically loads the latexml.sty package (and it includes its own copy if latexml.sty is not in your LATEX installation). latexml.sty offers a variety of commands which may be useful. Just open latexml.sty (it is very short) to see all the commands, a bit of documentation in the comments, and the occasional example. The source of the LATExml documentation contains many examples too. Below are some relevant ones.

• •
  ​

  \lxAddClass{class} and \lxWithClass{class}{content} to add CSS classes to the output;

• •
  ​

  \lxBeginTableHead, \lxEndTableHead and variations to mark table headers and footers (read the latexml.sty source for how to use them);

• •
  ​

  \lxContextTOC, \lxNavbar{arg}, \lxHeader{arg}, \lxFooter{arg} to customise the HTML pages;

• •
  ​

  \lxFcn{code}, \lxID{code}, \lxPunct{code} to help LATExml understand the meaning of mathematical symbols (for instance, read $f(a+b)$ as ‘$f$ applied to $a+b$’ as opposed to ‘$f$ multiplied by $a+b$’); the wrong interpretation may affect screen readers, so it will need to be addressed, but for now this is too hard to deal with.

1. 1.
   ​

   On the front page of your module, under ‘Module content’, click the $\oplus$ button where you want to insert your item.

2. 2.
   ​

   Choose ‘$\oplus$ Create’.

3. 3.
   ​

   Choose ‘SCORM package’.

4. 4.
   ​

   Choose ‘Upload SCORM package’ and select your SCORM.<...>.zip file.

5. 5.
   ​

   Disable ‘Grade SCORM’ and click ’Save’.

Note. Title and abstract of the file will become title and description of the Minerva entry. You will be able to edit the Minerva details right after uploading, if necessary.

For the initial permission setup, as well as screenshots of the entire process, consult Chris’ guide.

Below is a summary of the day-to-day upload process, once permissions have been set up:

1. 1.
   ​

   On the front page of your module, under ‘Module content’, click the $\oplus$ button where you want to insert your item.

2. 2.
   ​

   Choose ‘Content Collection’, then ‘Browse Content Collection’.

3. 3.
   ​

   Browse to the folder that has been set up with the appropriate permisions.

4. 4.
   ​

   Click ‘Upload’ and choose ‘Upload Zip Package’.

5. 5.
   ​

   Use ‘Browse Local Files’ to upload your <...>.zip file. You must enable ‘If selected, the system automatically overwrites the existing file with the same name’.

6. 6.
   ​

   Click ‘Submit’, the choose ‘index.html’ as file to be presented on Minerva.