Blobify

This section explains how to import a LaTeX document into a ColDoc portal.

Since the portal will use plastex to convert LaTeX to HTML, and pdflatex with the standalone package for compact PDF representation of UUIDs, some changes have to be made.

Following are instructions, and you may also want to see in the directory test/paper for a complete working example.

In your LaTeX document, you should set the language as

\usepackage[english]{babel}

and not as

\documentclass[english]{article}

Then, right after the documentclass statement, add

\newif\ifplastex\plastexfalse
%
\ifplastex\else
\ifdefined\CurrentFile\else
\usepackage{currfile}
\fi\fi

The conditional ifplastex will be forcibly set to true when compiling using plastex.

This snippet will also load the package currfile only when compiling with older LaTeX (older than 2019); it will be used for internal checkpointing.

Plastex tweaks

Then wrap all code that is not compatible with plastex (code that sets fonts etc etc) as follows

\ifplastex\else
 % set fonts ...
\fi

Also, you will have to replace some packages that do not work well with plastex, as in this example

\ifplastex
% plastex does not know of these
\def\eqref{\ref}
\fi
%
\ifplastex
% https://github.com/mathjax/MathJax/issues/1081
\def\sfrac{\frac}
\else
\usepackage{xfrac}
\fi
%
\ifplastex
% plastex does not know varioref
\def\vref{\ref}
\def\vpageref{\pageref}
\else
\usepackage{varioref}
\fi

See plastex docs for details

Standalone tweaks

You should also wrap all the code in the preamble that modifies page geometry so that it is ignored in standalone mode, as in this example:

\ifplastex\else\ifstandalone\else
\usepackage[margin=18ex,headheight=16pt]{geometry}
\usepackage{fancyhdr}
\pagestyle{fancy}
\fi\fi

See standalone docs for details

Multiple LaTeX format

It is possible to prepare a LaTeX document that can be compiled using different engines: pdflatex, xelatex or lualatex

To this end, you should install the latest version of the iftex package from https://www.ctan.org/pkg/iftex

Then add a snippet in the document preamble as follows:

\usepackage{iftex}
%%%%%%%%% use conditionals to load some engine-specific packages
\ifplastex
 % code for plastex
 \newcommand\mathbbm[1]{{\mathbb{#1}}}
\else\iftutex
% code for xetex or luatex
  \input{preamble_xelatex}
\else
 % code for standard (pdf)latex
   \input{preamble_pdflatex}
\fi\fi

Then put in the file preamble_xelatex.tex all commands to setup fonts for xelatex or lualatex; and similarly in preamble_pdflatex.tex for pdflatex.

Downloading, and compiling single UUIDs

You should also move all your favorite customizations in a file preamble_definitions.tex

  • loading of packages such as amsthm, amsmath

  • definitions for theorems and such

  • personal macros

  • ...etc...

There is a provision in the portal so that users may download the LaTeX of a single UUID: the portal will add enough LaTeX code so that it will be possible to compile that UUID; so it will add to the bundle

  • preamble_pdflatex.tex or preamble_xelatex.tex, for document-related definition;

  • that file preamble_definitions.tex so that the user will have a copy of all the needed macros and definitions,

to be able to compile that blob.

Check it all

Check that the document compiles fine to HTML by invoking PlasTeX on your document using

plastex -d output_html document.tex

(it is recommended that you use the plastex version that was installed in the installation phase)

And check that it still compiles fine with standard pdflatex

Then try to import in a test portal. Setup the test portal as follows

export COLDOC_SITE_ROOT=${COLDOC_SRC_ROOT}/test/tmp/test_site
cd  ${COLDOC_SRC_ROOT}
make -C test clean
make -C test django_deploy

Then try to import your document in the portal

ColDocDjango/blob_inator.py --coldoc-site-root ${COLDOC_SITE_ROOT} --coldoc-nick=testdoc --ZS --SAT  --split-sections --editor=ed_itor --author=jsmith --lang=eng yourdir/yourdocument.tex

note that:

  • if your document best compiles with a specific engine, use the --latex-engine option of blob_inator.py to specify which;

  • if you use non-standard commands to display images, add them to the command line options for blob_inator.py as --split-graphic mypicturecommand. (Warning: it is assumed that mypicturecommand uses the same syntax of includegraphics).

Then check if the document can be compiled

ColDocDjango/latex.py --coldoc-site-root ${COLDOC_SITE_ROOT} --coldoc-nick=testdoc --url-UUID="http://localhost:8000/UUID/testdoc/" all

and eventually run the test portal

make -C test django_run &

and access the web portal at http://localhost:8000.

Try authenticating using the different users (see the output of django_deploy for usernames and passwords).

Check that everything looks fine.

Check in particular that images were imported correctly.

If you are not satisfied, or if something fails:

  • tweak your document,

  • try different command line options for blob_inator.py

If the result is satisfactory enough, that is, if only small changes are needed, you can also change the document inside the portal by editing the files inside ${COLDOC_SITE_ROOT}/coldocs/testdoc/blobs/. Note that the data structure can be compiled from the command line, using

cd ${COLDOC_SITE_ROOT}/coldocs/testdoc/blobs/
pdflatex main_eng.tex
plastex -d main_html main_eng.tex

where eng may be replaced by the desired language.

Multilingual documents

In this regard, to be able to compute a multilingual document from the command line, you may also add in the preamble the snippet of code

%%% this part will be skipped when compiled inside ColDoc
\ifdefined\ColDocAPI\else
\usepackage{coldoc_standalone}
\fi

and copy that file coldoc_standalone.sty to the directory of your main LaTeX file, and adapt it to your needs.