\documentclass{article}
\usepackage{latexml}
\usepackage{hyperref}
%\usepackage{../sty/latexmldoc}
\usepackage{latexmldoc}
\input{latexmlreleases}
\usepackage{listings}
% Should the additional keywords be indexed?
\lstdefinestyle{shell}{language=bash,escapechar=@,
%  basicstyle=\ttfamily\small,%
  frame=single,
  basicstyle=\ttfamily,%
   morekeywords={latexml,latexmlpost,latexmlmath},
   moredelim=[is][\itshape]{\%}{\%}}

\newcommand{\PDFIcon}{\includegraphics{pdf}}

\title{\LaTeXML\ \emph{A \LaTeX\ to XML/HTML/MathML Converter}}
\lxKeywords{LaTeXML, LaTeX to XML, LaTeX to HTML, LaTeX to MathML, LaTeX to ePub, converter}
%============================================================
\begin{lxNavbar}
\lxRef{top}{\includegraphics{../graphics/latexml}}\\
\includegraphics{../graphics/mascot}\\
\lxContextTOC\\
% Direct link to manual from navbar
\vspace{1cm}
\URL[\hspace{4em}\LARGE The\ Manual]{./manual/}
\end{lxNavbar}
%============================================================
\lxDocumentID{ltxsite}
\begin{document}
\label{top}
\maketitle

%============================================================
\emph{Now available}:  \htmlref{\LaTeXML\ \CurrentRelease}{get}!

In the process of developing the
\href{https://dlmf.nist.gov/}{Digital Library of Mathematical Functions},
we needed a means of transforming
the \LaTeX\ sources of our material into XML which would be used
for further manipulations, rearrangements and construction of the web site.
In particular, a true `Digital Library' should focus on the \emph{semantics}
of the material, and so we should convert the mathematical material into both
content and presentation MathML.
At the time, we found no software suitable to our needs, so we began
development of \LaTeXML\ in-house.  

The approach is to emulate TeX as far as possible (in Perl), converting
the \TeX\ or (\LaTeX) document into \LaTeXML's XML format. That format
is modelled on the typical document structure found in \LaTeX, and inspired by
HTML, MathML, OpenMath and others.  That abstract document is then further
transformed into HTML of various flavors, with MathML and SVG,
or into JATS or ePub or \ldots.
Of course, emulating \TeX\ is kinda hard,
there are many clever \LaTeX\ package developers,
and the Web moves quickly,
so there are gaps in fidelity and coverage.

\paragraph*{Examples} of \LaTeXML's work include:
\index{examples}%
\begin{description}
\item[\href{examples/tabular/tabular.html}{LaTeX tabular}]
    from the \LaTeX\ manual, p.205.
    (\href{examples/tabular/tabular.tex}{\TeX},
     \href{examples/tabular/tabular.pdf}{\PDFIcon})
\item[\href{https://dlmf.nist.gov/}{DLMF}]
   The Digital Library of Mathematical Functions was the
   primary instigator for this project.
\item[\href{manual/}{\LaTeXML\ Manual}]
   The \LaTeXML\ User's manual (\href{manual.pdf}{\PDFIcon}).
\item[These pages] were produced using \LaTeXML, as well.
\end{description}
See also
\begin{description}
\item[\url{https://latexml.mathweb.org/editor}] an online editor/showcase
  of things that \LaTeXML\ can do.
\item[\url{https://arxmliv.kwarc.info}] An experiment processing
  the entire \url{https://arXiv.org}.
\end{description}

% In brief, \texttt{latexml} is a program, written in Perl, that attempts to
% faithfully mimic \TeX's behavior, but produces XML instead of dvi.
% The document model of the target XML makes explicit the model implied
% by \LaTeX.
% The processing and model are both extensible; you can define
% the mapping between \TeX\ constructs and the XML fragments to be created.
% A postprocessor, \texttt{latexmlpost} converts this
% XML into other formats such as HTML or XHTML, with options
% to convert the math into MathML (currently only presentation) or images.

% \emph{Caveats}: It isn't finished, there are gaps in the coverage,
% particularly in missing implementations of the many useful \LaTeX\ packages.
% But is beginning to stabilize and interested parties
% are invited to try it out, give feedback and even to help out.


% %============================================================
% \section{Examples}\label{examples}\index{examples}
% At the moment, the best example of \LaTeXML's output is 
% the \href{https://dlmf.nist.gov/}{DLMF} itself.
% There is, of course, a fair amount of insider, special case,
% code, but it shows what can be done.

% Some highlights:
% \begin{description}
% \item[\href{examples/tabular/tabular.html}{LaTeX tabular}]
%     from the \LaTeX\ manual, p.205.
%     (\href{examples/tabular/tabular.tex}{\TeX},
%      \href{examples/tabular/tabular.pdf}{\PDFIcon})
% \item[\url{https://latexml.mathweb.org/editor}] an online editor/showcase
%   of things that \LaTeXML\ can do.
% \item[\url{https://arxmliv.kwarc.info}] An experiment processing
%   the entire \url{https://arXiv.org}.
% \end{description}
% And, of course
% \begin{description}
% \item[\href{https://dlmf.nist.gov/}{DLMF}]
%    The Digital Library of Mathematical Functions was the
%    primary instigator for this project.
% \item[\href{manual/}{\LaTeXML\ Manual}]
%    The \LaTeXML\ User's manual (\href{manual.pdf}{\PDFIcon}).
% \item[And these pages] were produced using \LaTeXML, as well.
% \end{description}

%============================================================
\section{Usage}\label{ussage}
In most cases, all that should be needed to convert
a \TeX\ file, \textit{mydoc}\texttt{.tex} to XML, and
then to HTML would be:
\begin{lstlisting}[style=shell]
   latexml --dest=%mydoc%.xml %mydoc%
   latexmlpost --dest=%somewhere/mydoc%.html %mydoc%.xml
\end{lstlisting}
This will carry out the default transformation into HTML5,
which represents mathematics using MathML.
Different file extensions (or the \verb|--format| option) imply different output formats,
including XHTML, HTML4 w/images for math, JATS, TEI.
There are also options to split large documents into several pages, or to combine multiple
documents into a single site.  See the command documentation, below.

The functionality of \texttt{latexml} and \texttt{latexmlpost} are conveniently
combined into the single executable \texttt{latexmlc}, without creating the
intermediate XML file.  The above commands are equivalent to
\begin{lstlisting}[style=shell]
   latexmlc --dest=%somewhere/mydoc%.html %mydoc%
\end{lstlisting}
Moreover, \texttt{latexmlc} provides extra functionality
such as the creation of ePub documents:
\begin{lstlisting}[style=shell]
   latexmlc --dest=%mydoc%.epub %mydoc%
\end{lstlisting}
\emph{However}, be aware that a future merging and renaming will occur in
the not-too-distant future, resulting in a single executable \texttt{latexml}
which will combine all functionality.

\subsection{Documentation}
If you want to dig deeper:
\begin{description}
\item[\href{manual/}{LaTeXML Manual}] (\href{manual.pdf}{\PDFIcon}).
\item[\href{manual/commands/latexml.html}{\texttt{latexml}}]
    describes the \texttt{latexml} command.
\item[\href{manual/commands/latexmlpost.html}{\texttt{latexmlpost}}]
   describes the \texttt{latexmlpost} command for postprocessing.
\item[\href{manual/commands/latexmlc.html}{\texttt{latexmlc}}]
   describes the \texttt{latexmlc} command.
\end{description}

% Possibly, eventually, want to expose:
%   https://www.mathweb.org/wiki/????
% But, it doesn't have anything in it yet.


%============================================================
\section{Get \LaTeXML}\label{get}\index{get}
\def\GitHub{\href{https://github.com/}{GitHub}}
\def\MacPorts{\href{https://www.macports.org}{MacPorts}}
\def\MacTeX{\href{https://tug.org/mactex/}{MacTeX}}
\def\Chocolatey{\href{https://chocolatey.org}{Chocolatey}}
\def\MikTeX{\href{https://MiKTeX.org}{MikTeX}}


\subsection{Quick Start}\label{get.quick}
\subsubsection{Current Release}\label{get.current}
The current release is \textbf{\CurrentDownload}. (see the \href{Changes}{Change Log}).
\emph{Prebuilt packages sometimes lag behind the latest release.}

Most people will want to install a prebuilt release,
and some version of \TeX. Choose the appropriate
Operating system, repository type and context from the table below.
This will install all necessary prerequisites, unless otherwise noted.

\par\noindent
\begin{centering}
\begin{tabular}{lll}
\textit{Platform}
  & \textit{Command}
  & \textit{Details}\\\hline
%============================
\textbf{\textit{Linux}}\\
%\hspace{4em}
RPM-based
  & \begin{minipage}{3in}
 \begin{lstlisting}[style=shell]
sudo dnf install LaTeXML
\end{lstlisting}
\end{minipage}
  & \htmlref{RPM-based}{get.linux.rpm}\\
\multicolumn{1}{r}{\textit{or}}
  &\begin{minipage}{3in}
 \begin{lstlisting}[style=shell]
sudo yum install LaTeXML
\end{lstlisting}
\end{minipage}
  & \\
%%
Debian
  &\begin{minipage}{3in}
 \begin{lstlisting}[style=shell]
sudo apt-get install latexml
\end{lstlisting}
\end{minipage}
  & \htmlref{Debian}{get.linux.debian}\\
% Arch linux?
%============================
\hline
\multicolumn{2}{l}{\textbf{\textit{MacOS} \MacPorts}}\\
w/\MacTeX
  &\begin{minipage}{3in}
 \begin{lstlisting}[style=shell]
sudo port install LaTeXML +mactex
\end{lstlisting}
\end{minipage}
  & \htmlref{MacOS}{get.macos.macports} (\MacTeX\ preinstalled)\\
%%
w/TeXlive
  &\begin{minipage}{3in}
 \begin{lstlisting}[style=shell]
sudo port install texlive-latex
sudo port install LaTeXML
\end{lstlisting}
\end{minipage}
  & \htmlref{MacOS}{get.macos.macports}\\
%%
w/o \TeX
  &\begin{minipage}{3in}
 \begin{lstlisting}[style=shell]
sudo port install LaTeXML
\end{lstlisting}
\end{minipage}
  & \htmlref{MacOS}{get.macos.macports}\\
%============================
\hline
\textbf{\textit{Windows}}\\
\Chocolatey
  & \begin{minipage}{3in}
\begin{lstlisting}[style=shell]
choco install latexml
\end{lstlisting}
\end{minipage}
  & \htmlref{Chocalatey}{get.windows.chocolatey}; may need \TeX\\
%%
\href{https://strawberryperl.com}{Strawberry}
  & \begin{minipage}{3in}
 \begin{lstlisting}[style=shell]
cpan LaTeXML
\end{lstlisting}
\end{minipage}
  & \htmlref{Strawberry-Perl}{get.windows.strawberry}; may need \TeX, ImageMagick\\
%============================
\hline
\textbf{\textit{Any}}\\
CPAN
  & \begin{minipage}{3in}
\begin{lstlisting}[style=shell]
cpan LaTeXML
\end{lstlisting}
\end{minipage}
   & \htmlref{CPAN}{get.cpan}; may need \TeX, ImageMagick, libxml2,libxslt\\
%%% NOTE: Development version!!!
%============================
\hline
\end{tabular}
\end{centering}
Note that there is \emph{no} implied endorsement of any of these systems.

\subsubsection[Development version]{Development version or from Source}\label{get.development}
If you want to use the `bleeding edge' development version with the latest patches and improvements,
you may fetch the source from \GitHub.
(The same installation instructions apply if you are using source from a release tarball.)

\paragraph*{Prerequisites}
will need to be \textbf{pre}-installed (including any optional ones);
see \ref{get.prerequisites}.

It may be expedient, when a prebuilt \LaTeXML\ is available,
to first simply install \LaTeXML\ from your system's repositories
(See the commands below specific to your system).
Then uninstall it 
(often by using the OS' package manager with the \texttt{remove} sub-command
instead of \texttt{install});
This generally leaves the prerequisites installed.

\paragraph*{Clone}
the development source from github:
\begin{lstlisting}[style=shell]
git clone https://github.com/brucemiller/LaTeXML.git
cd LaTeXML
\end{lstlisting}
(Keep up-to-date by occasionally running 
\lstinline[style=shell]{git pull} and rebuilding.)

\subparagraph*{Alternatively, a zip} can be downloaded from
\href{https://github.com/brucemiller/LaTeXML/archive/master.zip}{LaTeXML-master.zip},
and unpacked:
\begin{lstlisting}[style=shell]
unzip LaTeXML-master.zip
cd LaTeXML-master
\end{lstlisting}
\subparagraph{or, a tarball} can be downloaded from \CurrentDownload, and unpacked:
\begin{lstlisting}[style=shell]
tar zxvf LaTeXML-@\CurrentVersion@.tar.gz
cd LaTeXML-@\CurrentVersion@
\end{lstlisting}

\paragraph*{Build}
\LaTeXML\ in its source directory using the standard Perl procedure
(On Windows, use \texttt{dmake} instead of \texttt{make}):
\begin{lstlisting}[style=shell]
perl Makefile.PL
make
make test
\end{lstlisting}
The tests should complete without error (some tests may be `skipped').

Append the following options to the \texttt{perl Makefile.PL} command, if desired:
\begin{description}
\item[PREFIX=\textit{perldir}] specifies a nonstandard place to install LaTeXML
\item[TEXMF=\textit{texdidr}] specifies a where to install \LaTeXML's \TeX\ style files.
\end{description}
(See \texttt{perl perlmodinstall} for more details and options.)

\paragraph*{Install} \LaTeXML\ to where the OS can find the files
\begin{lstlisting}[style=shell]
sudo make install
\end{lstlisting}
(Alternatively, you can run directly from the build directory, eg.
\texttt{\textit{latexmldir}/blib/script/latexml}.)

\subsection{Prerequisites}\label{get.prerequisites}
\LaTeXML\ requires several Perl modules to do its job.  Most
are automatically installed by the platform-specific installation or CPAN.
However, CPAN will \emph{not} install the required C libraries needed for
\texttt{XML::LibXML}, and \texttt{XML::LibXSLT}.
If \texttt{libxml2} and \texttt{libxslt} are are not already installed,
follow the instructions at \href{http://www.xmlsoft.org}{XMLSoft} to
download and install the most recent versions of \texttt{libxml2} and \texttt{libxslt}.
Note that Strawberry Perl, on Windows, already includes these libraries
(but ActiveState does not).

\subparagraph{Recommend} to install prerequisites from prebuilt packages
for your system, if available, rather than from scratch.

\paragraph{Optional Prerequisites} will be wanted by most users,
but are not required because they are sometimes difficult to find or install,
or to allow for minimal installs.
\begin{description}
\item[\TeX] Virtually all users of \LaTeXML\ will want to install \TeX.  \LaTeXML\ 
\emph{should} find whatever \TeX-installation you have, and will
use \TeX's style files directly in some cases, providing broader coverage,
particularly for the more complex styles like \texttt{babel} and \texttt{tikz}.
Moreover, if \TeX\ is present when \LaTeXML\ is being installed,
\LaTeXML\ will install a couple of its own style files that can be used
with regular \TeX, or \LaTeX\ runs;
So if you are going to install \TeX, install it first!
See \href{https://www.tug.org}{\TeX\ Users Group} for more options.

Note that \LaTeXML\ will use, for its own purposes, the style files from whatever
\TeX\ system, if any, it finds at runtime.

\item[Image::Magick] provides a handy library of image manipulation routines.
When they are present \LaTeXML\ is able to carry out more image processing,
such as transformations by the \texttt{graphicx} package, and conversion of math to images;
otherwise, some such operations will not be supported.

See \ref{get.imagemagick} for installation and usage issues.

\item[Graphics::Magick] is an \emph{alternative} to \texttt{Image::Magick} that \LaTeXML\ will
use if is found on the system; it may (or may not ) be easier to install, although it
is less widely available.

\item[UUID::Tiny] generates unique identifiers that can be used to make better ePub documents
  (it can be installed using \htmlref{CPAN}{get.cpan.prereq}).

\item[perl-doc]\label{get.perl-doc}
 On \emph{some} compact distributions the perl documentation modules
 are not installed by default (eg.~debian minimal). These modules help generate
 readable command-line documentation for the \LaTeXML\ tools. Thus you \emph{may}
 want to install an extra package (\texttt{perl-doc} on debian minimal) to enable this feature. 

\end{description}
\emph{Note to packagers:} If you are preparing a compiled installation package (such as rpm or deb) for
\LaTeXML, and the above packages are easily installable in your distribution,
you probably should include them as dependencies of \LaTeXML.

\subsection{Linux systems}\label{get.linux}
\subsubsection[RPM-based systems]{RPM-based systems}\label{get.linux.rpm}
\index{rpm}\index{Fedora}\index{Redhat}\index{Centos}
Current (or recent) releases of \LaTeXML\ should be available from
the Fedora (and probably others including Redhat Enterprise Linux, CentOS, Scientific Linux\ldots)
repositories (Thanks Mike Petullo).

\paragraph*{Install prebuilt} \LaTeXML, including all prerequisites including texlive for \TeX\ with:
\begin{lstlisting}[style=shell]
sudo dnf install LaTeXML
\end{lstlisting}
(use \texttt{yum} instead \texttt{dnf}, on some systems):

\paragraph*{Install \emph{only} prerequisites}\label{get.linux.rpm.prereq}
(including the optional ones) with:
\begin{lstlisting}[style=shell]
sudo dnf install \
  perl-Archive-Zip perl-DB_File perl-File-Which \
  perl-Getopt-Long perl-Image-Size perl-IO-String perl-JSON-XS \
  perl-libwww-perl perl-Parse-RecDescent perl-Pod-Parser \
  perl-Text-Unidecode perl-Test-Simple perl-Time-HiRes perl-URI \
  perl-XML-LibXML perl-XML-LibXSLT \
  perl-UUID-Tiny texlive ImageMagick ImageMagick-perl
\end{lstlisting}
(use \texttt{yum} instead \texttt{dnf}, on some systems):

\subsubsection{Debian-based systems}\label{get.linux.debian}\index{Debian}
For Debian-based systems (including Ubuntu), the deb repositories
are generally used for software installation.
\LaTeXML\ is available from Debian's \emph{unstable} repositories
(the version in the stable repositories may be quite old)
(Thanks Peter Ralph and Atsuhito Kohda).

\paragraph*{Install prebuilt} \LaTeXML, including its required and optional prerequisites
including \TeX, with:
\begin{lstlisting}[style=shell]
sudo apt-get install latexml
\end{lstlisting}

\paragraph*{Install \emph{only} prerequisites}\label{get.linux.debian.prereq}
(including optional ones) with:
\begin{lstlisting}[style=shell]
sudo apt-get install   \
  libarchive-zip-perl libfile-which-perl libimage-size-perl  \
  libio-string-perl libjson-xs-perl libtext-unidecode-perl \
  libparse-recdescent-perl liburi-perl libuuid-tiny-perl libwww-perl \
  libxml2 libxml-libxml-perl libxslt1.1 libxml-libxslt-perl  \
  texlive-latex-base imagemagick libimage-magick-perl
\end{lstlisting}
See note \ref{get.perl-doc} about optional installation of \texttt{perl-doc}.

\subsubsection{Archlinux \& friends}\label{get.linux.arch}\index{Arch}
For Archlinux and derivatives, it is most convenient to install from sources via \htmlref{CPANM}{get.cpanm}. 
Nonetheless, a package can be found in the \href{https://aur.archlinux.org/}{Archlinux User Repository}.
Furthermore, most dependencies can be found in the official repositories.

\paragraph*{Install from AUR} (Arch User Repositories)
using the \href{https://aur.archlinux.org/packages/perl-latexml/}{perl-latexml} package. 

\paragraph*{Install \emph{only} prerequisites,} with:
\begin{lstlisting}[style=shell]
sudo pacman -S db imagemagick perl perl-algorithm-diff \
   perl-archive-zip perl-file-which perl-image-size \
   perl-io-string perl-libwww perl-json-xs \
   perl-parse-recdescent perl-xml-libxml perl-xml-libxslt \
   texlive-core
\end{lstlisting}
Additionally, install the \href{https://archlinux.org/packages/community/x86_64/perl-text-unidecode/}{perl-text-unidecode}
community package. 

\subsection{MacOS}\label{get.macos}\index{Apple Macintosh}

\subsubsection{MacPorts}\label{get.macos.macports}
For Apple Macintosh systems, the  \MacPorts\
repository is perhaps the most convenient way to install \LaTeXML;
(Thanks devens, Mojca, Sean and Andrew Fernandes).
Download and install \MacPorts\ from that site.
Since some users prefer \MacTeX\ and don't want a duplicate (large) texlive,
and others prefer texlive, there are several ways to install \LaTeXML\. 

\paragraph*{Install using MacTeX} (already installed), including prerequisites with:
\begin{lstlisting}[style=shell]
sudo port install LaTeXML +mactex
\end{lstlisting}

\paragraph*{Install with TeXLive} and other prerequisites with:
\begin{lstlisting}[style=shell]
sudo port install texlive-latex
sudo port install LaTeXML
\end{lstlisting}
You may want to select a more complete \TeX package than \texttt{texlive-latex}.

\paragraph*{Install without \TeX} using
\begin{lstlisting}[style=shell]
sudo port install LaTeXML
\end{lstlisting}

\paragraph*{Install \emph{only} prerequisites}\label{get.macos.macports.prereq}
(including optional ones except \TeX) with:
\begin{lstlisting}[style=shell]
sudo port install \
  p5-archive-zip p5-file-which p5-getopt-long p5-image-size \
  p5-io-string p5-json-xs p5-text-unidecode p5-libwww-perl \
  p5-parse-recdescent p5-time-hires p5-uri p5-xml-libxml \
  p5-xml-libxslt p5-perlmagick
\end{lstlisting}

\subsection{Windows}\label{get.windows}\index{windows}
As with MacOS, there is no single \TeX\ package that we can assume
you'll want to use, so we include no dependency in the following.
You'll probably want to preinstall a version of your choice;
\MikTeX\ is popular.

\subsubsection{Windows using Chocolatey}\label{get.windows.chocolatey}
\paragraph*{Install \Chocolatey\ prebuilt} \LaTeXML\ as well as all prerequisites
(including ImageMagick)(Thanks Ronald Tse), using:
\begin{lstlisting}[style=shell]
choco install latexml
\end{lstlisting}

\subsubsection{Windows using Strawberry Perl}\label{get.windows.strawberry}
\href{https://strawberryperl.com}{Strawberry Perl},
comes with \emph{many} of our prerequisites pre-installed,
and provides other needed commands (\texttt{perl}, \texttt{cpan}, \texttt{dmake}).

\paragraph*{Install under Strawberry}\label{get.windows.strawberry} from CPAN,
after installing the \TeX-system of your choice (if desired),
and ImageMagick (see \ref{get.windows.imagemagick}),
using:
\begin{lstlisting}[style=shell]
cpan LaTeXML
\end{lstlisting}

Installing the optional package \texttt{Image::Magick} on Windows seems to be problematic,
so we have omitted it from these instructions.
You may want to try \href{https://www.imagemagick.org/}{ImageMagick}, but
you're on your own, there!  You may  have better luck with \texttt{Graphics::Magick}.

\paragraph*{Installi \emph{only} prerequisites  under Strawberry,}\label{get.windows.strawberry.prereq}
except for \TeX, and ImageMagick (see \ref{get.windows.imagemagick}),
using:
\begin{lstlisting}[style=shell]
cpan Image::Size Parse::RecDescent UUID::Tiny
\end{lstlisting}

\subsubsection*{Failing Installation with MiKTeX and administrative rights}\label{get.windows.miktexbug}

Note that when trying to install with administrative rights rights on Windows, a 
MikTeX warning sometimes causes a test to fail with an error
``kpsewhich: warning: running with administrator privileges''.
This warning is something LaTeXML has no control over, and is specific to the MikTeX toolchain.
To workaround the problem, you can set the \lstinline{LATEXML_KPSEWHICH_MIKTEX_ADMIN}
and \lstinline{LATEXML_TEST_TEXLIVE} environment variables and try to force an installation.

\paragraph*{Using Chocolatey}
\begin{lstlisting}[style=shell]
$Env:LATEXML_KPSEWHICH_MIKTEX_ADMIN=true ; $Env:LATEXML_TEST_TEXLIVE="0"; choco install latexml
\end{lstlisting}

\paragraph*{Using CPAN}
\begin{lstlisting}[style=shell]
$Env:LATEXML_KPSEWHICH_MIKTEX_ADMIN=true ; $Env:LATEXML_TEST_TEXLIVE="0"; cpan latexml
\end{lstlisting}

\subsection{CPAN installation}\label{get.cpan}
The following command will install \LaTeXML\ and its Perl prerequisites,
but you may need to pre-install \texttt{libxml2} and  \texttt{libxslt} (See \ref{get.prerequisites}),
as well as optionally \TeX\, ImageMagick, if desired.
\begin{lstlisting}[style=shell]
cpan LaTeXML
\end{lstlisting}

\paragraph*{Install \emph{only}  prerequisites}\label{get.cpan.prereq}
(excluding  \texttt{libxml2},  \texttt{libxslt}, \TeX, ImageMagick)
using:
\begin{lstlisting}[style=shell]
cpan Archive::Zip DB_File File::Which Getopt::Long Image::Size \
  IO::String JSON::XS LWP MIME::Base64 Parse::RecDescent \
  Pod::Parser Text::Unidecode Test::More URI \
  XML::LibXML XML::LibXSLT UUID::Tiny
\end{lstlisting}

\subsection{CPANM Installation}\label{get.cpanm}
On certain linux machines, you may not want to install \LaTeXML\ (or its dependencies)
system-wide, or you may simply lack the required root rights to do so. 
In such a case, it is convenient to install the \emph{development} version and 
dependencies into the home directory using a tool called 
\href{ https://github.com/miyagawa/cpanminus}{cpanminus}.

\paragraph*{Bootstrap cpanminus,} if you haven't previously,
with the following commands
\begin{lstlisting}[style=shell]
# Download and install cpanminus
curl -L https://cpanmin.us | perl - App::cpanminus

# Setup a directory in ~/perl5 to contain all perl dependencies
~/perl5/bin/cpanm --local-lib=~/perl5 local::lib && eval $(perl -I ~/perl5/lib/perl5/ -Mlocal::lib)
\end{lstlisting}

\paragraph*{Install prerequisites}
(excluding  \texttt{libxml2},  \texttt{libxslt}, \TeX, ImageMagick)
using:
\begin{lstlisting}[style=shell]
cpanm git://github.com/brucemiller/LaTeXML.git
\end{lstlisting}
This automatically fetches the latest version from GitHub and installs 
missing dependencies. 

\subsection{ImageMagick Issues}\label{get.imagemagick}
Although \href{https://imagemagick.com/}{ImageMagick} is a useful and powerful tool,
it often presents installation and usage challenges, particularly its Perl binding
and when used in conjunction with Ghostscript.

\paragraph*{ImageMagick Versions} for the ImageMagick binaries and the Perl binding must match;
often those available from CPAN are out-of-sync.
Ideally, you should install the current versions of both ImageMagick and the perl binding
from your OS/platform distribution, if available.
Next best solution is to get the same versions from the same source
following the instructions at \href{https://www.imagemagick.org/}{ImageMagick}
to download and install the latest version of ImageMagick being sure to enable
and build the Perl binding along with it.

\paragraph*{Installing ImageMagick under Windows}\label{get.windows.imagemagick}
seems to work best by downloading and installing the main ImageMagick binary
appropriate for your Windows system
from \href{https://imagemagick.org/script/binary-releases.php#windows}{ImageMagick}.
Then fetch the \texttt{PerlMagick} tarball \emph{with the same version} from
\href{https://imagemagick.com/download/perl/}{ImageMagick/perl}.
Use the following commands to compile and install the PerlMagick,
with X.XX being the version you downloaded:
\begin{lstlisting}[style=shell]
tar -zxvf PerlMagick-X.XX.tar.gz
cd PerlMagick-X.XX
perl Makefile.PL
dmake
dmake test
dmake install
\end{lstlisting}

\paragraph*{ImageMagick Security} is also an issue, due to the possibility of embadding
malicious code in postscript, pdf and other image formats.
For a certain range of versions of ImageMagick and Ghostscript, a security policy was set
which inhibited processing of pdf files; the problem appears to be fixed recent versions.
If you see \texttt{operation not allowed by the security policy}, see the discussion
at \href{https://stackoverflow.com/a/53180170}{stackoverflow}.

\expandafter\ifx\expandafter#\AllReleases#\else
\subsection{Archived Releases:}\label{get.archive}
\AllReleases.
\fi
%============================================================
\section{Contacts \& Support}\label{contact}

\paragraph{\LaTeXML\ Mailing List}\label{contact.list}
is a low-volume mailing list for questions, support and comments.
See \href{https://lists.informatik.uni-erlangen.de/mailman/listinfo/latexml}{\texttt{latexml-project}} for subscription information.

\paragraph{Github Issue-Tracker}\label{contact.git}
at \href{https://github.com/brucemiller/LaTeXML/}{https://github.com/brucemiller/LaTeXML/},
allows you to report Issues with \LaTeXML,
as well as browse the code, see the latest changes, and check-out the current code.

%  There is a Trac bug-tracking system for reporting bugs, or checking the
%  status of previously reported bugs at
%  \href{https://trac.mathweb.org/LaTeXML/}{Bug-Tracker}.

% To report bugs, please:
% \begin{itemize}
% \item \href{https://trac.mathweb.org/register/register}{Register} a Trac account
%   (preferably give an email so that you'll get notifications about activity regarding the bug).
% \item \href{https://trac.mathweb.org/LaTeXML/newticket}{Create a ticket}
% \end{itemize} 

\paragraph{Thanks} to our friends at
the \href{https://kwarc.info}{KWARC Research Group}
for hosting the mailing list, the original Trac system and svn repository,
as well as general moral support.

\paragraph{Authors} are
\href{mailto:bruce.miller@nist.gov}{Bruce Miller},
\href{mailto:deyan.ginev@gmail.com}{Deyan Ginev}.
%============================================================
\section{License \& Notices}\label{notices}

\paragraph{License:}
  This software was developed at the National Institute of Standards and
Technology by employees of the Federal Government in the course of their
official duties. Pursuant to title 17 Section 105 of the United States
Code, this software is not subject to copyright protection in the U.S.
and is in the \textbf{public domain}.

To the extent that any copyright protections may be considered to be held
by the authors of this sofware in some jurisdiction outside the United
States, the authors hereby waive those copyright protections and dedicate
the software to the public domain. Thus, this license may be considered equivalent to
\href{https://creativecommons.org/about/cc0}{Creative Commons 0: "No Rights Reserved"}.

Note that, according to
\href{https://www.gnu.org/licences/license-list.html#PublicDomain}{Gnu.org},
public domain is compatible with GPL.

We would appreciate acknowledgement if the software is used.

\paragraph{Contributor Notice:}
  Contributions of software patches and enhancements to this project
are welcome; such contributions are assumed to be under the same terms
as the software itself.  Specifically, if you contribute code, documention,
text samples or any other material, you are asserting and acknowledging that:
you are the copyright holder of the material or that it is in the public domain;
it does not contain any patented material; and that you waive any copyright
protections and dedicate the material to the public domain.

\paragraph{Disclaimer:}
  \LaTeXML\ is an experimental system provided by NIST as a public service.

The software is expressly provided "AS IS." NIST makes NO warranty of
any kind, express, implied, in fact or arising by operation of law,
including, without limitation, the implied warranty of
merchantability, fitness for a particular purpose, non-infringement
and data accuracy. nist neither represents nor warrants that the
operation of the software will be uninterrupted or error-free, or that
any defects will be corrected. NIST does not warrant or make any
representations regarding the use of the software or the results
thereof, including but not limited to the correctness, accuracy,
reliability, or usefulness of the software.

You are solely responsible for determining the appropriateness of
using and distributing the software and you assume all risks
associated with its use, including but not limited to the risks and
costs of program errors, compliance with applicable laws, damage to or
loss of data, programs or equipment, and the unavailability or
interruption of operation. This software is not intended to be used in
any situation where a failure could cause risk of injury or damage to
property.

\paragraph{Privacy Notice:}
We adhere to \href{https://www.nist.gov/public_affairs/privacy.cfm}{NIST's Privacy, Security and Accessibility Policy}.
%============================================================

\end{document}
