\documentclass[a4paper,reqno]{article}
\usepackage[mathjax]{lwarp}
\CSSFilename{lwarp-intro.css}
\usepackage{amsmath,amssymb}
\usepackage{alltt}
\usepackage{minted}
\usemintedstyle{vs}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% lists and whitespace and
%% whitespace in lists
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\usepackage{paralist,enumitem}
%% I hate indented paras
\setlength{\parindent}{0pt}
\setlength{\parskip}{6pt}
% \setlength{\plitemsep}{3pt}
%\setlist{listparindent=0pt,parsep=3pt}
%% enumeration style
% \setdefaultenum{1.}{}{}{}       

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% links and references
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\usepackage[pdftex,linktocpage,pdfstartview=FitH,colorlinks=true,allcolors=blue]{hyperref}

\newcommand{\lwarp}{\texttt{lwarp}}

%% top-matter
\title{\LaTeX\ to \textsc{HTML} with \lwarp}
\author{Fran Burstall}
\date{Last updated: 16$^{\rm th}$ October 2020}

\begin{document}
\maketitle

\section{The problem and how to solve it}
\label{sec:problem-how-solve}

As mathematicians, we are accustomed to writing papers,
lecture notes and exercise sheets in \LaTeX\ and
distributing the resulting \textsc{PDF} files.  However,
\textsc{PDF} is not a good option from the accessibility
point of view: it does not play well with screen-readers,
for example, and there is now a legal requirement to provide
alternatives.  To a first approximation, a good alternative
is \textsc{HTML} along with \textsc{MathJax} to render the
mathematics so the question is how to produce this.

One possibility is to start again and write from scratch in
\href{https://bookdown.org/yihui/bookdown/}{\textsc{bookdown}}.
However, if you already have a large amount of \LaTeX\
material, there is another, perhaps, easier path: the
\lwarp\ package.

The \lwarp\ package produces an \textsc{html} version of
your document with accessibly rendered mathematics while
allowing you to use macros, theorem environments,
\texttt{tikz} pictures and all the other bells and whistles
you are used to.  This note tells you how to get started
with \lwarp.

\section{Long story short}
\label{sec:long-story-short}

Starting with \texttt{file.tex}, add the following snippet
right after the \verb+\documentclass+ line:
\begin{minted}{tex}
\usepackage[mathjax]{lwarp}
\end{minted}
Run \texttt{pdflatex} on \texttt{file.tex} as usual enough
times to resolve references.

Now, in a terminal, invoke this incantation:
\begin{minted}{sh}
lwarpmk html
\end{minted}

If everything goes to plan, you should now find the your
working directory contains \texttt{file.html} and also a
\texttt{css} file called \texttt{lwarp.css}.  Put both of
these where you usually put your web-pages and you are good
to go.

Read on if you have pictures, macros or long documents that
need to be spread over many web-pages.

\section{Carrying on}
\label{sec:carrying}

\lwarp\ has an extensive
\href{http://mirrors.ctan.org/macros/latex/contrib/lwarp/lwarp.pdf}{manual}
(over 1000 pages but you only need sections 5 and 6 to get
started).  Here we collect some tips for rapid deployment.

\subsection{Graphics}
\label{sec:graphics}

How your pictures and diagrams work will depend on their
format:

\begin{enumerate}
\item Graphics created on board with \LaTeX\
  \texttt{picture} or \texttt{tikz} will Just Work.  Simply
  run the following in a terminal as a final step:
\begin{verbatim}
lwarpmk limages
\end{verbatim}
\item  Graphics in \textsc{pdf} or \textsc{eps} format need a
  conversion step first:
\begin{verbatim}
lwarpmk epstopdf *.eps  # only for .eps files
lwarpmk pdftosvg *.pdf
\end{verbatim}
\end{enumerate}

% \begin{itemize}
% \item graphics created on board with \LaTeX\
%   \texttt{picture} or \texttt{tikz} will Just Work.  Simply
%   run the following in a terminal as a final step:
% \begin{verbatim}
% lwarpmk limages
% \end{verbatim}
% \item graphics in \textsc{pdf} or \textsc{eps} format need a
%   conversion step first:
% \begin{verbatim}
% lwarpmk epstopdf *.eps  # only for .eps files
% lwarpmk pdftosvg *.pdf
% \end{verbatim}
% \end{itemize}
For more details, see section 8 of the manual.

\subsection{Maths macros}
\label{sec:maths-macros}

If you are like me, you use a lot of \LaTeX\ macros to help
with writing mathematics.  \textsc{MathJax} will not
understand these out of the box but can be taught about
them.

Given a list of macros in the preamble like this:
\begin{minted}{tex}
\newcommand{\R}{\mathbb{R}}
\newcommand{\C}{\mathbb{C}}
\newcommand{\Z}{\mathbb{Z}}
\end{minted}
you need to add a second block for \textsc{MathJax}:
\begin{minted}{tex}
\begin{warpHTML}
\CustomizeMathJax{\newcommand{\R}{\mathbb{R}}}
\CustomizeMathJax{\newcommand{\C}{\mathbb{C}}}
\CustomizeMathJax{\newcommand{\Z}{\mathbb{Z}}}
\end{warpHTML}
\end{minted}
If you have a lot of macros, this could be tedious but your
\href{https://www.gnu.org/software/emacs/}{text}
\href{https://www.vim.org/}{editor} should be able to help
you.

\subsection{Lecture notes and friends}
\label{sec:lect-notes-friends}

You now know enough to make exercise sheets but what about
lecture notes and other long documents that don't fit on a
single web-page?  You can get \lwarp\ to split your document
into sections, each getting its own page.  To achieve this,
replace the 
\verb+\usepackage{lwarp}+ line with something like::
\begin{minted}{tex}
\usepackage[
   HomeHTMLFilename=index,     % Filename of the homepage.
   HTMLFilename={node-},       % Filename prefix of other pages.
   mathjax                     % Use MathJax to display math.
]{lwarp}
\end{minted}
and then customise with:
\begin{minted}{tex}
\boolfalse{FileSectionNames}    % If false, numbers the files.
\setcounter{tocdepth}{2}        % Include subsections in the \TOC.
\setcounter{secnumdepth}{3}     % Number down to subsections.
\setcounter{FileDepth}{1}       % Split \HTML\ files at sections
\booltrue{CombineHigherDepths}  % Combine parts/chapters/sections
\setcounter{SideTOCDepth}{1}    % Include subsections in the side\TOC
\HTMLTitle{MA20216: Algebra 2A} % Overrides \title for the web page.
\HTMLAuthor{Fran Burstall}      % Sets the HTML meta author tag.
\HTMLLanguage{en-UK}            % Sets the HTML meta language.
\HTMLDescription{Lecture notes for MA2016: Algebra 2A}% Sets the HTML meta description.
\end{minted}
Now \texttt{lwarpmk html} will generate \texttt{index.html},
lots of files of the form \texttt{node-1.html}
containing the sections and a table of contents for
navigation.

See the manual for more details.

\section{More maths tips}
\label{sec:more-maths-tips}

Sometimes \lwarp\ or \textsc{MathJax} needs a little help to
do what you want.  Here are some examples I have found:
\begin{enumerate}
\item If \textsc{MathJax} does not understand a \LaTeX\
  construct it will display the offending item in red.
  Often a simple replacement is all that is needed:
  \begin{enumerate}
  \item Replace \verb+\dag+ with \verb+\dagger+.
  \item Replace \verb+\,,+ with \verb+\, ,+.
  \end{enumerate}
\item Help is needed with \texttt{tikzcd} environments: wrap
  them in a \verb+{\displaymathother ...}+ group.  Example:
\begin{minted}{tex}
{\displaymathother
  \begin{equation*}
     \begin{tikzcd} V \arrow{r}{\phi}& W \\
     \F^{n}\arrow{r}{\phi_A} \arrow{u}{\phi_{\cB}} &\F^m
     \arrow{u}[right]{\phi_{\cB'}}
     \end{tikzcd}
  \end{equation*}}
\end{minted}
\item You can give different content for the \textsc{pdf}
  and \textsc{html} versions by wrapping things in
  \texttt{warpprint} or \texttt{warpHTML} environments.
  For example, \lwarp\ does not support the \texttt{amsmath}
  package's 
  \verb+\intertext+ construct very well.  See
  Figure~\ref{fig:1} for the work-around.

  \textbf{Warning}: the \verb+\end{warp...}+ part must be
placed at the start of the line for this to work.
\end{enumerate}

\begin{figure}[htb]
\begin{minted}{tex}
\begin{warpprint}
  \begin{align*}
    \ip{\phi^{*}(v),w}&=\ip{v,\phi(w)}\\
    \intertext{or, equivalently, by conjugate symmetry,}
    \ip{w,\phi^{*}(v)}&=\ip{\phi(w),v}.
  \end{align*}
\end{warpprint}
\begin{warpHTML}
  \begin{equation*}
    \ip{\phi^{*}(v),w}=\ip{v,\phi(w)}\\
  \end{equation*}
  or, equivalently, by conjugate symmetry,
  \begin{equation*}
    \ip{w,\phi^{*}(v)}=\ip{\phi(w),v}.
  \end{equation*}
\end{warpHTML}
\end{minted}
  \caption{Different content depending on context}\label{fig:1}
\end{figure}

\section{Advanced configuration}
\label{sec:advanc-conf}

\subsection{Styling}
\label{sec:styling}

\lwarp\ provides bare-bones styling via \texttt{lwarp.css}.
You can provide your own \texttt{css} and load it by putting
\begin{minted}{tex}
\CSSFilename{my-classy-style.css}
\end{minted}
in the preamble.

If you do this, it is a good idea to start from
\texttt{lwarp.css} by putting
\begin{minted}{css}
@import url("lwarp.css");
\end{minted}
at the top of your own style sheet.  See
section~\ref{sec:resources} for examples.

\subsection{Javascript}
\label{sec:javascript}

Again, \lwarp\ gives bare-bones navigation for multi-page
web-sites.  If you want to improve things with javascript,
you can inject some into the document with these steps:

\begin{enumerate}
\item Copy the auto-generated file \verb+lwarp_mathjax.txt+
  to something like \verb+my_mathjax.txt+.
\item  At the end of \verb+my_mathjax.txt+, put something like:
\begin{alltt}
    \textless{}script type="text/javascript"
    src="my-clever-nav.js"\textgreater
    \textless/script\textgreater
\end{alltt}
\item  Load it by adding
\begin{minted}{tex}
\MathJaxFilename{my_mathjax.txt}
\end{minted}
  to the preamble.
\end{enumerate}


See section~\ref{sec:resources} for an example.
  
\section{Resources}
\label{sec:resources}

Here are some examples:

\begin{tabular}{lllll}
  This document
      &\href{https://people.bath.ac.uk/feb/lwarp/lwarp-intro.tex}{\LaTeX}
             &\href{https://people.bath.ac.uk/feb/lwarp/lwarp-intro.html}{\textsc{html}}
  &\href{https://people.bath.ac.uk/feb/lwarp/lwarp-intro.css}{\textsc{css}}&\\
  An exercise sheet
      &\href{https://people.bath.ac.uk/feb/lwarp/M216.01.tex}{\LaTeX}
             &\href{https://people.bath.ac.uk/feb/lwarp/M216.01.html}{\textsc{html}}
  &\href{https://people.bath.ac.uk/feb/lwarp/exercise.css}{\textsc{css}}&\\
  Lecture notes
      &\href{https://people.bath.ac.uk/feb/lwarp/M216-notes.tex}{\LaTeX}
             &\href{https://people.bath.ac.uk/feb/ma20216/notes}{\textsc{html}}
  &\href{https://people.bath.ac.uk/feb/lwarp/M216-notes.css}{\textsc{css}}
  &\href{https://people.bath.ac.uk/feb/lwarp/navigation.js}{\textsc{js}}\\            
\end{tabular}

\end{document}
