UseLATEX/UseLATEX.tex

% -*- latex -*-

\documentclass{article}

\newcommand{\UseLATEXVersion}{2.4.4}
\newcommand{\SANDNumber}{SAND 2008-2743P}

% This wonderful package allows hyphenation in tt fonts and hyphenation of
% words with underscores in them.
\usepackage[htt]{hyphenat}

\usepackage{fancyvrb}
\usepackage{color}
\usepackage{hologo}
\usepackage{xspace}

\usepackage{hyperref}
\hypersetup{pdftitle={UseLATEX.cmake: LaTeX Document Building Made Easy}}
\hypersetup{pdfauthor={Kenneth Moreland}}

% Simple commands that establish the font for various elements.
\newcommand*{\textfile}[1]{\textsf{#1}}
\newcommand*{\textprog}[1]{\textfile{#1}}
\newcommand*{\textlatexpackage}[1]{\textsf{#1}}
\newcommand*{\textcmake}[1]{\texttt{#1}}
\newcommand*{\textcmakevar}[1]{\textcmake{#1}}
\newcommand*{\textmaketarget}[1]{#1}
\newcommand*{\textvar}[1]{\textit{#1}}
\CustomVerbatimCommand{\textlatex}{Verb}{}

% Simple commands that insert some standard text.
\newcommand*{\UseLATEX}{\textfile{UseLATEX.cmake}\xspace}
\newcommand*{\latex}{\LaTeX\xspace}
\newcommand*{\bibtex}{\textsc{Bib}\TeX\xspace}
\newcommand*{\miktex}{Mik\TeX\xspace}
\newcommand*{\mactex}{Mac\TeX\xspace}
\ifdefined\synctex
  \renewcommand*{\synctex}{SyncTeX\xspace}
\else
  \newcommand*{\synctex}{SyncTeX\xspace}
\fi
\newcommand*{\xelatex}{\Hologo{XeLaTeX}\xspace}
\newcommand*{\lualatex}{\Hologo{LuaLaTeX}\xspace}
\newcommand*{\ald}{\textcmake{add\_latex\_document}\xspace}

% Environments for listing CMake and other types of code.
\definecolor{listingframecolor}{cmyk}{0,0,0,0.25}
\CustomVerbatimEnvironment{CodeListing}{Verbatim}{
  frame=single,
  rulecolor=\color{listingframecolor},
  framesep=6pt}
\newcommand*{\includeCodeListing}[2][]{\VerbatimInput[
  frame=single,
  rulecolor=\color{listingframecolor},
  framesep=4pt,#1]{#2}}

\begin{document}

  \sloppy

  \title{UseLATEX.cmake: \latex Document Building Made Easy}
  \author{Kenneth Moreland}
  \date{Version \UseLATEXVersion}
  \maketitle

  \tableofcontents

  %-----------------------------------------------------------------------------

  \section{Description}
  \label{sec:Description}

  Compiling \latex files into readable documents is actually a very
  involved process. Although CMake comes with \textfile{FindLATEX.cmake},
  it does nothing for you other than find the commands associated with
  \latex. I like using CMake to build my \latex documents, but creating
  targets to do it is actually a pain. Thus, I've compiled a bunch of
  macros that help me create targets in CMake into a file I call
  ``\UseLATEX.'' Here are some of the things \UseLATEX handles:

  \begin{itemize}
  \item Runs \latex multiple times to resolve links.
  \item Can run \textprog{bibtex}, \textprog{makeindex}, and
    \textprog{makeglossaries} to make bibliographies, indexes, and/or
    glossaries.
  \item Optionally runs configure on your \latex files to replace
    \textcmake{@\textvar{VARIABLE}@} with the equivalent CMake variable.
  \item Automatically finds png, jpeg, eps, pdf, svg, tiff, gif, bmp, and
    other image files and converts them to formats \textprog{latex} and
    \textprog{pdflatex} understand.
  \end{itemize}

  %-----------------------------------------------------------------------------

  \section{Download}
  \label{sec:Download}

  \UseLATEX is currently posted to the CMake Wiki at
  \begin{quote}
    \href{http://public.kitware.com/Wiki/CMakeUserUseLATEX}{http://public.kitware.com/Wiki/CMakeUserUseLATEX}.
  \end{quote}

  %-----------------------------------------------------------------------------

  \section{Basic Usage}
  \label{sec:BasicUsage}

  Using \UseLATEX is easy. For a basic \latex file, simply include the file
  in your \textfile{CMakeLists.txt} and use the \ald command to make
  targets to build your document. For an example document in the file
  \textfile{MyDoc.tex}, you could establish a build with the following
  simple \textfile{CMakeLists.txt}.

  \begin{CodeListing}
project(MyDoc NONE)

include(UseLATEX.cmake)
add_latex_document(MyDoc.tex)
  \end{CodeListing}

  The \ald adds the following targets to create a readable document from
  \textfile{MyDoc.tex}:

  \begin{description}
    \item[\textmaketarget{dvi}] Creates \textfile{MyDoc.dvi}.
    \item[\textmaketarget{pdf}] Creates \textfile{MyDoc.pdf} using
      \textprog{pdflatex}. Requires the \textcmakevar{PDFLATEX\_COMPILER}
      CMake variable to be set.
    \item[\textmaketarget{ps}] Creates \textfile{MyDoc.ps}. Requires the
      \textcmakevar{DVIPS\_CONVERTER} CMake variable to be set.
    \item[\textmaketarget{safepdf}] Creates \textfile{MyDoc.pdf} from
      \textfile{MyDoc.ps} using \textprog{ps2pdf}. Many publishers prefer
      pdfs are created this way. Requires the
      \textcmakevar{PS2PDF\_CONVERTER} CMake variable to be set.
    \item[\textmaketarget{html}] Creates html pages. Requires the
      \textcmakevar{HTLATEX\_COMPILER} CMake variable to be set.
    \item[\textmaketarget{clean}] To CMake's default \textmaketarget{clean}
      target, the numerous files that \latex often generates are added.
    \item[\textmaketarget{auxclean}] Deletes the auxiliary files from
      \latex, but not the generated input files.  Sometimes \latex gets
      itself in a bad state where the auxiliary files need to be deleted to
      successfully build again, and this target does that without also
      deleting other build files (such as converted image files or files
      from unrelated targets in the same directory).
  \end{description}

  One caveat about using \UseLATEX is that you are required to do an
  out-of-source build. That is, CMake must be run in a directory other than
  the source directory. This is necessary as latex is very picky about file
  locations, and the relative locations of some generated or copied files
  can only be maintained if everything is copied to a separate directory
  structure.  For more details and hints on workarounds, see the
  ``\hyperref[sec:Why_does_UseLATEX_have_to_copy_my_tex_files]{Why does
    \UseLATEX have to copy my tex files?}'' frequently asked question in
  Section~\ref{sec:Why_does_UseLATEX_have_to_copy_my_tex_files}.

  \subsection{Using a Bibliography}
  \label{sec:UsingABibliography}

  For any technical document, you will probably want to maintain a \bibtex
  database of papers you are referencing in the paper. You can incorporate
  your .bib files by adding them after the \textcmake{BIBFILES} argument to
  the \ald command.

  \begin{CodeListing}
add_latex_document(MyDoc.tex BIBFILES MyDoc.bib)
  \end{CodeListing}

  This will automatically add targets to build your bib file and link it
  into your document. To use the \bibtex file in your \latex file, just do
  as you normally would with \textlatex|\cite| commands and bibliography
  commands:

  \begin{CodeListing}
\bibliographystyle{plain}
\bibliography{MyDoc}
  \end{CodeListing}

  You can list as many bibliography files as you like.

  \subsection{Incoporating Images}
  \label{sec:IncoporatingImages}

  To be honest, incorporating images into \latex documents can be a real
  pain. This is mostly because the format of the images needs to depend on
  the version of \latex you are running (\textprog{latex}
  vs. \textprog{pdflatex}). With these CMake macros, you only need to
  convert your raster graphics to png or jpeg format and your vector
  graphics to eps or pdf format. Place them all in a common directory
  (e.g. images) and then use the \textcmake{IMAGE\_DIRS} option to the \ald
  macro to point to them. \UseLATEX will take care of the rest.

  \begin{CodeListing}
add_latex_document(MyDoc.tex
  BIBFILES MyDoc.bib
  IMAGE_DIRS images
  )
  \end{CodeListing}

  If you want to break up your image files in several different
  directories, you can do that, too. Simply provide multiple directories
  after the \textcmake{IMAGE\_DIRS} option.

  \begin{CodeListing}
add_latex_document(MyDoc.tex
  BIBFILES MyDoc.bib
  IMAGE_DIRS icons figures
  )
  \end{CodeListing}

  Alternatively, you could list all of your image files separatly with the
  \textcmake{IMAGES} option.

  \begin{CodeListing}
set(MyDocImages
  logo.eps
  icons/next.png
  icons/previous.png
  figures/flowchart.eps
  figures/team.jpeg
  )
add_latex_document(MyDoc.tex
  IMAGES ${MyDocImages}
  )
  \end{CodeListing}
  %$

  For every image file specified and found with the \textcmake{IMAGE\_DIRS} and \textcmake{IMAGES} options, \UseLATEX adds makefile targets to use ImageMagick's \textprog{magick} or \textprog{convert} to convert the file types to those appropriate for the build.\footnote{The \textprog{convert} program was essentially renamed \textprog{magick} in ImageMagick 7.0. Most, but not all, recent installations provide both. \UseLATEX looks for both just in case.}
  If you do not have ImageMagick, you can get it for free from \href{http://www.imagemagick.org}{http://www.imagemagick.org}.
  CMake will also give you a \textcmakevar{LATEX\_SMALL\_IMAGES} option that, when on, will downsample raster images.
  This can help speed up building and viewing documents.
  It will also make the output image sizes smaller.

  \UseLATEX will occasionally use a conversion program other than
  ImageMagick's \textprog{magick}.  For example, \textprog{ps2pdf} will be
  used when converting eps to pdf to get around a problem where ImageMagick
  drops the bounding box information.  When available, the
  \textprog{pdftops} from the Poppler utilities will be used to convert pdf
  to eps because it better preserves vector graphics and color spaces.  At
  any rate, you do not need to worry about setting the appropriate image
  conversion program.  \UseLATEX will automatically select the best one and
  issue errors or warnings if there is a problem.

  The \textcmake{IMAGE\_DIRS} option tries to identify image files by their
  extensions. The current list of image extensions \UseLATEX checks for is:
  .bmp, .bmp2, .bmp3, .dcm, .dcx, .ico, .gif, .jpeg, .jpg, .eps, .pdf,
  .pict, .png, .ppm, .tif, and .tiff. If you are trying to use an image
  format that is supported by ImageMagick but is not recognized by
  \UseLATEX, you can specify the files directly with the \textcmake{IMAGES}
  option instead. \UseLATEX will assume that any file specified with the
  \textcmake{IMAGES} option is an image file regardless of its extension.

  Both the \textcmake{IMAGE\_DIRS} and \textcmake{IMAGES} can be used
  together. The combined set of image files will be processed. If you wish
  to provide a separate eps file and pdf or png file, that is OK,
  too. \UseLATEX will handle that by copying over the correct file instead
  of converting.

  Depending on what program is launched to build your \latex file (either
  \textprog{latex} or \textprog{pdflatex}, and \UseLATEX supports both), a
  particular format for your image is required.  As stated, \UseLATEX
  handles the necessary conversions for you.  However, you will not know in
  advance what file extension is used on the image.  That is no problem.
  Simply leave out the file extension in the file name argument to
  \textlatex|\includegraphics| and \latex will find the file with the
  appropriate extension for you.

  Note that in order to ensure that the resulting image files are placed in
  the appropriate directory, you are required to give \emph{relative} paths
  for images and image directories.  For example, \textcmake{IMAGE\_DIRS
    \$\{CMAKE\_CURRENT\_SOURCE\_DIR\}/images} will fail.  Use
  \textcmake{IMAGE\_DIRS images} instead.

  \subsection{Selecting a Default Build}
  \label{sec:SelectingADefaultBuild}

  By default, when you use \ald and then run make with no arguments,
  \textprog{pdflatex} is used to create a pdf file. You can of course
  always specify a target described at the top of
  Section~\ref{sec:BasicUsage} to build a different document
  format. However, for convenience you can change the default build.

  \UseLATEX defines the CMake variable \textcmakevar{LATEX\_DEFAULT\_BUILD}
  that controls which build is performed by default. Valid values for this
  variable are \textcmake{pdf}, \textcmake{dvi}, \textcmake{ps},
  \textcmake{safepdf}, and \textcmake{html}. This variable is usually
  initialized to \textcmake{pdf}, but you can override this behavior by
  setting the \textcmakevar{LATEX\_DEFAULT\_BUILD} environment variable
  before the first configuration. Thus, if you have a preference for a
  particular default build, you can set your system environment to use it
  by default for all \UseLATEX builds.

  \subsection{Force a Type of Build}
  \label{sec:ForceATypeOfBuild}

  \UseLATEX does its best to make \latex builds as portable as possible,
  but there might be a number of technical reasons why a particular
  document can only be built using one type of system. If that is the case,
  it is best if the configuration only supports one type of build.

  \ald has several options to force the document generation to a particular
  type of build. If you give the option \textcmake{FORCE\_PDF}, only the
  pdf targets that use the \textprog{pdflatex} command are created.

  \begin{CodeListing}
add_latex_document(MyDoc.tex
  BIBFILES MyDoc.bib
  IMAGE_DIRS images
  FORCE_PDF
  )
  \end{CodeListing}

  Likewise, the \textcmake{FORCE\_DVI} option restricts \ald to targets that
  use the \textprog{latex} command. In addition to building dvi files,
  \textcmake{FORCE\_DVI} also allows ps generation from the dvi files and
  ``safe'' pdf generation from the ps files.

  \begin{CodeListing}
add_latex_document(MyDoc.tex
  BIBFILES MyDoc.bib
  IMAGE_DIRS images
  FORCE_PS
  )
  \end{CodeListing}

  Finally, the \textcmake{FORCE\_HTML} option will restrict targets that are
  used for html generation.

  \begin{CodeListing}
add_latex_document(MyDoc.tex
  BIBFILES MyDoc.bib
  IMAGE_DIRS images
  FORCE_HTML
  )
  \end{CodeListing}

  The behavior is undefined if more than one force option is given.

  \subsection{Create Nothing by Default}
  \label{sec:CreateNothingByDefault}

  Sometimes it is desirable to disable the building of your \latex document
  by default (that is, not build it with the \textmaketarget{all} target).
  This is convenient when including \latex documentation with some other
  source to build such as when you are documenting a library.  To remove
  all targets from the default, simply add the
  \textcmake{EXCLUDE\_FROM\_ALL} option to \ald.

  \begin{CodeListing}
add_latex_document(MyDoc.tex
  BIBFILES MyDoc.bib
  IMAGE_DIRS images
  EXCLUDE_FROM_ALL
  )
  \end{CodeListing}

  \subsection{\synctex-Enabled Editors}
  \label{sec:SynctexEnabledEditors}

  Some implementations of \latex compilers have a feature called \synctex
  that allows an editor or viewer to link between the compiled version of
  the document (such as a pdf) and the original \latex source code.  The
  most common way to do this is to add \textprog{-synctex=1} to the
  \textprog{pdflatex} command.  This will create a file named
  \textfile{\emph{$\langle$base-name$\rangle$}.synctex.gz} where each part
  of the final document points to the original \latex files.

  However, there is a problem.  \UseLATEX copies all of the input \latex
  source files to an out-of-source build directory (see
  Section~\ref{sec:Why_does_UseLATEX_have_to_copy_my_tex_files} for more
  information on why).  But the \latex compiler does not know that.  Thus,
  the created \textfile{\emph{$\langle$base-name$\rangle$}.synctex.gz} will
  point to the temporary files in the build directory rather than your
  original source files.

  \UseLATEX can add commands to the make targets that ``correct'' the
  \textfile{\emph{$\langle$base-name$\rangle$}.synctex.gz}.  To add these
  commands, simply turn on the \textcmakevar{LATEX\_USE\_SYNCTEX} in
  \textprog{ccmake} or equivalent CMake configuring tool.  When this option
  is on, the \textprog{-synctex=1} argument is added to the \latex compile
  commands (settable with the \textcmakevar{LATEX\_SYNCTEX\_FLAGS}
  variable) and a command is added to targets that will find files in
  \textfile{\emph{$\langle$base-name$\rangle$}.synctex.gz} and change their
  paths to the original files in the source directory.

  %-----------------------------------------------------------------------------

  \section{Package Support}
  \label{sec:PackageSupport}

  Modern \latex distributions provide a great many packages to provide
  additional features to the document building process.  A great many more
  packages are available in online package distributions.  The vast
  majority of these packages provide features that are self contained
  within the \latex call itself.  That is, the build process does not have
  to change to accommodate these packages.

  That said, there are a small number of packages that require
  supplementary programs to be run or to otherwise change the build
  process.  These packages require special options to \ald, which are
  documented here.

  \subsection{Making an Index}
  \label{sec:MakingAnIndex}

  You can make an index in a \latex document by using the
  \textlatexpackage{makeidx} package. However, this package requires you to
  run the \textprog{makeindex} program. Simply add the
  \textcmake{USE\_INDEX} option anywhere in the \ald arguments, and
  \textprog{makeindex} will automatically be added to the build.

  \begin{CodeListing}
add_latex_document(MyDoc.tex
  BIBFILES MyDoc.bib
  IMAGE_DIRS images
  USE_INDEX
  )
  \end{CodeListing}

  \subsection{Making Multiple Indexes}
  \label{sec:MakingMultipleIndexes}

  The \textlatexpackage{multind} package allows you to create multiple
  indexes in a single \latex document. For example, when documenting a
  software library you might want to have a general index of terms and a
  second index of function names.

  The way the \textlatexpackage{multind} package works is that it creates a
  separate index file for each of the indexes being created, and the
  \textprog{makeindex} program must be run independently on each of them.
  To get \UseLATEX to run \textprog{makeindex} on all of the required index
  file, list all of the indexes created with the \textcmake{INDEX\_NAMES}
  option of \ald. For example, in a \latex document that declares two
  indexes like the following

  \begin{CodeListing}
\usepackage{multind}
\makeindex{general}
\makeindex{functions}
  \end{CodeListing}

  you would name the indexes in \ald like the following.

  \begin{CodeListing}
add_latex_document(MyDoc.tex
  BIBFILES MyDoc.bib
  IMAGE_DIRS images
  USE_INDEX
  INDEX_NAMES general functions
  )
  \end{CodeListing}

  \subsection{Making a Glossary}
  \label{sec:MakingAGlossary}

  There are multiple ways to make a glossary in a \latex document, but the
  \textlatexpackage{glossaries} package provides one of the most convenient
  ways of doing so.  Like the \textlatexpackage{makeidx} package,
  \textlatexpackage{glossaries} requires running \textprog{makeindex} or
  \textprog{xindy} for building auxiliary files.  However, building the
  glossary files can be more complicated as there can be different sets of
  glossary files with different extensions.  \UseLATEX will handle that for
  you.  It does it in a way similar to the \textprog{makeglossary} command,
  but in a more portable way.  Simply add the \textcmake{USE\_GLOSSARY}
  option anywhere in the \ald arguments, and the glossary creating will be
  handled for you.

  \begin{CodeListing}
add_latex_document(MyDoc.tex
  BIBFILES MyDoc.bib
  IMAGE_DIRS images
  USE_GLOSSARY
  )
  \end{CodeListing}

  \subsection{Nomenclature Support}
  \label{sec:NomenclatureSupport}

  The \textlatexpackage{nomencl} package provides a mechanism to collect
  nomenclature and print it together in a single section.  The
  \textlatexpackage{nomencl} behaves very similarly to
  \textlatexpackage{glossaries} (described in
  Section~\ref{sec:MakingAGlossary}) including running the
  \textprog{makeindex} command.  However, the arguments to
  \textprog{makeindex} are a bit different (to avoid clashes with creating
  glossaries), and unfortunately \textlatexpackage{nomencl} provides no
  hints in the auxiliary file about it.  Thus, \UseLATEX provides a special
  \textcmake{USE\_NOMENCL} option to \ald to add the necessary commands to
  build the nomenclature.

  \begin{CodeListing}
add_latex_document(MyDoc.tex
  BIBFILES MyDoc.bib
  IMAGE_DIRS images
  USE_NOMENCL
  )
  \end{CodeListing}

  It should be noted that this feature only works with
  \textlatexpackage{nomencl} version 4.0 or later.  The
  \textlatexpackage{nomencl} package changed how \textprog{makeindex} is
  called to make it compatible with indices and glossaries.  The correct
  version of \textlatexpackage{nomencl} is easily identified as the one
  that uses the \textlatex|\makenomenclature| and
  \textlatex|\printnomenclature| commands (as opposed to the old
  \textlatex|\makeglossary| and \textlatex|\printglossary| commands).  If
  you are using an older version of \textlatexpackage{nomencl}, you are
  best off to update for a number of reasons.

  \subsection{\textlatexpackage{multibib} Support}
  \label{sec:multibibSupport}

  The \textlatexpackage{multibib} package provides a mechanism to create a
  set of distinct bibliographies that are not necessarily associated with
  sections of the document.  Part of the operation of this package creates
  multiple \latex auxiliary files that need to be processed independently
  with \bibtex.  Consequently, the build needs to be modified to run
  \bibtex multiple times with different inputs.  This can be achieved with
  the \textcmake{MULTIBIB\_NEWCITES} argument to \ald.

  As an example, consider the following usage of the
  \textlatexpackage{multibib} package, partially taken from its
  documentation.  It creates a set of distinct citation commands named
  \textlatex|own|, \textlatex|submitted|, and \textlatex|internal| with the
  section heads \textlatex|Own Work|, \textlatex|Submitted Work|, and
  \textlatex|Master Theses and Ph.D. Theses| respectively.  They
  collectively use the bibliography files \textfile{own.bib},
  \textfile{submitted.bib}, \textfile{techreports.bib}, and
  \textfile{theses.bib}.

  \begin{CodeListing}
\newcites{own,submitted,internal}%
  {Own Work,%
   Submitted Work,%
   {Technical Reports, Master Theses and Ph.D. Theses}}
  \end{CodeListing}
  \begin{CodeListing}
\bibliographyown{own.bib}
  \end{CodeListing}
  \begin{CodeListing}
\bibliographysubmitted{submitted.bib}
  \end{CodeListing}
  \begin{CodeListing}
\bibliographyinternal{techreports.bib,theses.bib}
  \end{CodeListing}

  The three suffixes specified to the \textlatex|\newcite| command and the
  four bibliography files referenced must all be specified in the \ald
  command with the \textcmake{MULTIBIB\_NEWCITES} and \textcmake{BIBFILES}
  arguments, respectively.

  \begin{CodeListing}
add_latex_document(MyDoc.tex
  BIBFILES own.bib submitted.bib techreports.bib theses.bib
  MULTIBIB_NEWCITES own submitted internal
  )
  \end{CodeListing}

  \subsection{\textlatexpackage{biblatex} Support}
  \label{sec:biblatexSupport}

  The \textlatexpackage{biblatex} package provides an alternate mechanism
  for building bibliographies that has many options not available to the
  standard bibliography commands. The package (typically) requires an
  external program named \textprog{biber}, which is an alternative to the
  standard \textprog{bibtex} command.

  Thus, to support the \textlatexpackage{biblatex} package, the build
  system must run \textprog{biber} instead of \textprog{bibtex}. This is
  done simply with \UseLATEX by adding the \textcmake{USE\_BIBLATEX} option
  to \ald.

  \begin{CodeListing}
add_latex_document(MyDoc.tex
  BIBFILES MyDoc.bib
  USE_BIBLATEX
  )
  \end{CodeListing}


  %-----------------------------------------------------------------------------

  \section{Advanced Configurations}
  \label{sec:AdvancedConfigurations}

  This document has heretofore described using \UseLATEX for a single
  \latex document and associated files (bibliographies, images, indices,
  etc.).  However there are many configurations to document building that
  extend beyond this simple scenario including multipart files, multiple
  documents, and depended builds.

  \subsection{Multipart \latex Files}
  \label{sec:MultipartLatexFiles}

  Often, it is convenient to split a \latex document into multiple files
  and use the \latex \textlatex|\input| or \textlatex|\include| command to
  put them back together. To do this, all the files have to be located
  together. \UseLATEX can take care of that, too. Simply add the
  \textcmake{INPUTS} argument to \ald to copy these files along with the
  target tex file. Build dependencies to these files is also established.

  \begin{CodeListing}
add_latex_document(MyDoc.tex
  INPUTS Chapter1.tex Chapter2.tex Chapter3.tex Chapter4.tex
  BIBFILES MyDoc.bib
  IMAGE_DIRS images
  USE_INDEX
  )
  \end{CodeListing}

  As far as \UseLATEX is concerned, input files do not necessarily have to
  be tex files.  For example, you might be including the contents of a text
  file into your document with the \textlatex|\VerbatimInput| command of
  the \textlatexpackage{fancyvrb} package.  In fact, you could also add
  graphic files as inputs, but you would not get the extra conversion
  features described in Section~\ref{sec:IncoporatingImages}.

  \subsection{Configuring \latex Files}
  \label{sec:ConfiguringLatexFiles}

  Sometimes it is convenient to control the build options of your tex file
  with CMake variables. You can achieve this by using the
  \textcmake{CONFIGURE} argument to \ald.

  \begin{CodeListing}
add_latex_document(MyDoc.tex
  INPUTS Chapter1.tex Chapter2.tex Chapter3.tex Chapter4.tex
  CONFIGURE MyDoc.tex
  BIBFILES MyDoc.bib
  IMAGE_DIRS images
  USE_INDEX
  )
  \end{CodeListing}

  In the above example, in addition to copying \textfile{MyDoc.tex} to the
  binary directory, \UseLATEX will configure \textfile{MyDoc.tex}. That is,
  it will find all occurrences of \textcmake{@\textvar{VARIABLE}@} and
  replace that string with the current CMake variable
  \textcmakevar{\textvar{VARIABLE}}.

  With the \textcmake{CONFIGURE} argument you can list the target tex file
  (as shown above) as well as any other tex file listed in the
  \textcmake{INPUTS} argument.

  \begin{CodeListing}
add_latex_document(MyDoc.tex
  INPUTS Ch1Config.tex Ch1.tex Ch2Config.tex
         Ch2.tex Ch3Config Ch3.tex
  CONFIGURE Ch1Config.tex Ch2Config.tex Ch3Config.tex
  BIBFILES MyDoc.bib
  IMAGE_DIRS images
  USE_INDEX
  )
  \end{CodeListing}

  Be careful when using the \textcmake{CONFIGURE} option. Unfortunately,
  the \textlatex|@| symbol is used by \latex in some places. For example,
  when establishing a tabular environment, an \textlatex|@| is used to
  define the space between columns. If you use it more than once, then
  \UseLATEX will erroneously replace part of the definition of your columns
  for a macro (which is probably an empty string). This can be particularly
  troublesome to debug as \latex will give an error in a place that, in the
  original document, is legal. Hence, it is best to only configure tex
  files that contain very little text of the actual document and instead
  are mostly setup and options.

  \subsection{Building Multiple \latex Documents}
  \label{sec:BuldingMultipleLatexDocuments}

  The most common use for \UseLATEX is to build a single document, such as
  a paper you are working on. However, some use cases involve building
  several documents at one time.

  Multiple \latex documents in the same CMake project can be created by
  simply calling \ald multiple times. Each call to \ald will create its own
  set of unique targets that will be added as dependencies of
  \textmaketarget{dvi}, \textmaketarget{pdf}, \textmaketarget{ps},
  \textmaketarget{safepdf} and \textmaketarget{html}.

  Consider the following code.

  \begin{CodeListing}
add_latex_document(MyDoc1.tex)
add_latex_document(MyDoc2.tex)
  \end{CodeListing}

  In the example above, the first call to \ald will create targets named
  \textmaketarget{MyDoc1\_dvi}, \textmaketarget{MyDoc1\_pdf},
  \textmaketarget{MyDoc1\_ps}, etc. whereas the second call will create
  targets named \textmaketarget{MyDoc2\_*}. Calling \textmaketarget{dvi},
  \textmaketarget{pdf}, etc. will execute the respective targets for the
  two documents.

  The \textcmake{EXCLUDE\_FROM\_DEFAULTS} option suppresses these links to the
  document's targets.

  \begin{CodeListing}
add_latex_document(MyDoc1.tex)
add_latex_document(MyDoc2.tex)
add_latex_document(MyDoc3.tex EXCLUDE_FROM_DEFAULTS)
  \end{CodeListing}

  In this augmented example, MyDoc1 and MyDoc2 are built when targets such
  as \textmaketarget{dvi} and \textmaketarget{pdf} are called, but MyDoc3
  is not. Note, however, that in this example MyDoc3 is still built as part
  of the \textmaketarget{all} target that CMake sets as the default build
  target. Use \textcmake{EXCLUDE\_FROM\_ALL} to remove a document from the
  default \textmaketarget{all} build. \textcmake{EXCLUDE\_FROM\_ALL} and
  \textcmake{EXCLUDE\_FROM\_DEFAULTS} can be used together or
  independently.

  An issue that can come up in larger builds with multiple \latex documents
  is a name collision. If two subdirectories each have a \latex document
  with the same \textfile{.tex} file in it, then the respective calls to
  \ald will create the same target names, which CMake does not allow. One
  way around this problem is to rename the files to be unique (so that \ald
  will create unique target names). But a more convenient way is to use the
  \textcmake{TARGET\_NAME} option to change the target names. For example,
  consider the following use of \textcmake{TARGET\_NAME}.

  \begin{CodeListing}
add_latex_document(doc.tex TARGET_NAME MyDoc1)
  \end{CodeListing}

  This will change the behavior of \ald to create targets named
  \textmaketarget{MyDoc1\_dvi}, \textmaketarget{MyDoc1\_pdf},
  \textmaketarget{MyDoc1\_ps}, etc. instead of \textmaketarget{doc\_dvi},
  \textmaketarget{doc\_pdf}, \textmaketarget{doc\_ps}, etc.

  \subsection{Identifying Dependent Files}
  \label{sec:IdentifyingDependentFiles}

  In some circumstances, CMake's configure mechanism is not sufficient for
  creating input files.  Input \latex files might be auto-generated by any
  number of other mechanisms.

  If this is the case, simply add the appropriate CMake commands to
  generate the input files, and then add that file to the DEPENDS option of
  \ald.  To help you build the CMake commands to place the generated files
  in the correct place, you can use the LATEX\_GET\_OUTPUT\_PATH convenience
  function to get the output path.

  \begin{CodeListing}
latex_get_output_path(output_dir)

add_custom_command(OUTPUT ${output_dir}/generated_file.tex
  COMMAND tex_file_generate_exe
  ARGS ${output_dir}/generated_file.tex
  )

add_latex_document(MyDoc.tex DEPENDS generated_file.tex)
  \end{CodeListing}

  %-----------------------------------------------------------------------------

  \section{Frequently Asked Questions}
  \label{sec:FrequentlyAskedQuestions}

  This section includes resolutions to common questions and issues
  concerning use of \UseLATEX and with \latex in general.

  \subsection{How do I process \latex files on Windows?}
  \label{sec:How_do_I_process_latex_files_on_Windows}

  I have successfully used two different ports of LaTeX for windows: the
  \href{http://www.cygwin.com/}{cygwin} port
  (\href{http://www.cygwin.com/}{http://www.cygwin.com/}) and the
  \href{http://www.miktex.org/}{\miktex} port
  (\href{http://www.miktex.org/}{http://www.miktex.org/}).

  If you use the cygwin port of \latex, you must also use the cygwin port
  of CMake, make, and ImageMagick. If you use the \miktex port of \latex,
  you must use the CMake from
  \href{http://www.cmake.org/HTML/Download.html}{http://www.cmake.org/HTML/Download.html},
  the ImageMagick port from
  \href{http://www.imagemagick.org/script/binary-releases.php#windows}{http://www.imagemagick.org/script/binary-releases.php\#windows},
  and a native build tool like MSVC or the GNU make port at
  \href{http://unxutils.sourceforge.net/}{http://unxutils.sourceforge.net/}.
  \emph{Do not use the ``native'' CMake program with any cygwin programs or
  the cygwin CMake program with any non-cygwin programs.} This issue at
  hand is that the cygwin ports create and treat filenames differently then
  other windows programs.\footnote{If you are careful, you can use the
  cygwin version of make with the windows ports of CMake, \latex, and
  ImageMagick.  It is an easy way around the problems described in
  Section~\ref{sec:Why_is_convert_failing_on_Windows}.}

  Also be aware that if you have images in your document, there are
  numerous problems that can occur on Windows with the ImageMagick
  \textprog{convert} program. See
  Section~\ref{sec:Why_is_convert_failing_on_Windows} for more information.

  \subsection{How do I process \latex files on Mac OS X?}
  \label{sec:How_do_I_process_latex_files_on_Mac_OS_X}

  Using \latex on Mac OS X is fairly straightforward because this OS is
  built on top of Unix.  By using the Terminal program or X11 host, you can
  run \latex much like any other Unix variant.  The only real issue is that
  \latex and some of the supporting programs like CMake and ImageMagick are
  not typically installed (whereas on Linux they often are).

  Most applications port fairly easily to Mac OS so long as you are willing
  to use them as typical Unix or X11 programs.  To make things even easier,
  I recommend taking advantage of a Mac porting project to make this
  process even easier.  \href{http://www.macports.org}{MacPorts}
  (\href{http://www.macports.org}{http://www.macports.org}) is a good tool
  providing a comprehensive set of tool ports including \latex, CMake, and
  ImageMagick.  The \href{http://www.finkproject.org/}{fink project} and
  \href{http://finkcommander.sourceforge.net/}{FinkCommander}
  (\href{http://finkcommander.sourceforge.net/}{http://finkcommander.sourceforge.net/})
  is a similar although less active project.

  \subsection{How do I process with \xelatex?}
  \label{sec:How_do_I_process_with_XeLaTeX}

  \UseLATEX was not designed with \xelatex in mind, but the
  interface of that program is similar enough to \latex that you should be
  able to use it. Simply change the \textcmakevar{PDFLATEX\_COMPILER} CMake
  variable to the \textprog{xelatex} program and build the
  \textmaketarget{pdf} target.

  \subsection{How do I process with \lualatex?}
  \label{sec:How_do_I_process_with_LuaLaTeX}

  \UseLATEX was not designed with \lualatex in mind, but the
  interface of that program is similar enough to \latex that you should be
  able to use it. Simply change the \textcmakevar{PDFLATEX\_COMPILER} CMake
  variable to the \textprog{lualatex} program and build the
  \textmaketarget{pdf} target.

  \subsection{Why does \UseLATEX have to copy my tex files?}
  \label{sec:Why_does_UseLATEX_have_to_copy_my_tex_files}

  \UseLATEX cannot process your tex file without copying it.  As explained
  in Section~\ref{sec:BasicUsage}, \latex is very picky about file locations.
  The relative locations of files that your input files point to, and all
  but the most simple \latex files point to other files, must remain
  consistent.

  \UseLATEX will often have to modify at least one file either through
  configurations or image format and size conversions.  When creating new
  files, \UseLATEX will have to copy either all of the files or none of the
  files.  Since configuring and writing over an original file is
  unacceptable, \UseLATEX forces you to configure it such that \latex
  builds in a different directory than where you have placed the original.
  If you do not specify a seperate directory, you get an error like the
  following.

  \begin{CodeListing}
CMake Error at UseLATEX.cmake:377 (MESSAGE):
  LaTeX files must be built out of source or you must set
  LATEX_OUTPUT_PATH.
  \end{CodeListing}

  The best way around this problem is do an ``out of source'' build, which
  is really the preferred method of using CMake in general.  To do an out
  of source build, create a new build directory, go to that directory, and
  run cmake from there, pointing to the source directory.

  If for some reason an out of source build is not feasable or desireable,
  you can set the \textcmakevar{LATEX\_OUTPUT\_PATH} variable to a
  directory other than \textfile{.} (the local directory).  If you are
  building a \latex document in the context of a larger project for which
  you wish to support in source builds, consider pragmatically setting the
  \textcmakevar{LATEX\_OUTPUT\_PATH} CMake cache variable from within your
  \textfile{CMakeLists.txt}.

  \subsection{How can \latex find a file not a tex, image, or bibliography?}
  \label{sec:How_can_latex_find_a_file_not_a_tex_image_or_bibliography}

  The most common files included from a \latex tex file are other tex
  files, images, and bibliographies, all of which are handled with options
  to \ald.

  But what happens if the \latex build includes some other type of file?
  For example, the \textlatexpackage{fancyvrb} package can import a text
  file with the \textlatex|\VerbatimInput| command to be formatted in a
  teletype font.  Other examples occur, such as program formatting packages
  that can read in source code files.

  As far as \UseLATEX is concerned, these types of files are simply other
  inputs to \latex and handled in the same way as included tex files.  They
  can be included by adding them to the \textcmake{INPUTS} argument as
  described in Section~\ref{sec:MultipartLatexFiles}.

  If an inputted file does not immediately exist but is generated by some
  other process, then the file should be generated in the output directory
  and added to the \textcmake{DEPENDS} of the build as described in
  Section~\ref{sec:IdentifyingDependentFiles}.

  \subsection{Why is convert failing on Windows?}
  \label{sec:Why_is_convert_failing_on_Windows}

  Assuming that you have correctly downloaded and installed an appropriate
  version of ImageMagick (as specified in
  Section~\ref{sec:How_do_I_process_latex_files_on_Windows}), there are several
  other problems that users can run into the created build files attempt to
  run the \textprog{magick} or \textprog{convert} program.

  A common error is that \textprog{magick} or \textprog{convert} not finding a file that is clearly there.

  \begin{CodeListing}
convert: unable to open image `filename'
  \end{CodeListing}

  If you notice that the drive letter is stripped off of the filename
  (i.e. \textfile{C:}), then you are probably mixing the Cygwin version of
  \textprog{convert} with the non-cygwin CMake. The cygwin version of
  \textprog{convert} uses the colon (:), as a directory separator for
  inputs. Thus, it assumes the output file name is really two input files
  separated by the colon. Switch to the non-cygwin port of ImageMagick to
  fix this.

  If you are using nmake, you may also see the following error:

  \begin{CodeListing}
convert.exe: unable to open image `C:': Permission denied.
  \end{CodeListing}

  I don't know what causes this error, but it appears to have something to
  do with some strange behavior of nmake when quoting the convert
  executable. The easiest solution is to use a different build program
  (such as make or MSVC's IDE or a unix port of make). If anyone finds away
  around this problem, please contribute back.

  Another possible error seen is

  \begin{CodeListing}
Invalid Parameter - filename
  \end{CodeListing}

  This is probably because CMake has found the wrong \textprog{convert} program.
  Windows is installed with a program named \textprog{convert} in \textfile{\%SYSTEMROOT\%$\backslash$system32}.
  This \textprog{convert} program is used to change the filesystem type on a hard drive.
  Since the windows \textfile{convert} is in a system binary directory, it is usually found in the path before the installed ImageMagick \textfile{convert} program.
  (Don't get me started about the logic behind this.)
  Make sure that the \textcmakevar{IMAGEMAGICK\_CONVERT} CMake variable is pointing to the correct \textprog{convert} program.
  Or better yet, make sure you have ImageMagick 7.0 or higher and use the \textprog{magick} program instead of \textprog{convert}.
  Recent versions of \UseLATEX should give a specific warning about this with instructions on how to fix it.

  \subsection{How do I automate plot generation with command line programs?}
  \label{How_do_I_automate_plot_generation_with_command_line_programs}

  \latex is often used in conjunction with plotting programs that run on
  the command line like \textprog{gri} or \textprog{gnuplot}.  Although
  there is no direct support for these programs in \UseLATEX, it is
  straightforward to use these programs.

  One way to use a plotting program is simply to run it yourself to
  generate the plot and then incorporate the image file into your \latex
  document as you would any other image file (see
  Section~\ref{sec:IncoporatingImages}).  This the easiest way to
  incorporate these plots since it does not require additional CMake code.
  It also ensures consistency of how the plot looks (often the plots will
  look different if created on different platforms), and it provides the
  opportunity to edit the image to make it look better for publication.

  Another way to use these plotting programs is to automatically run them
  when building the \latex document.  This is convenient if you frequently
  change the data you are plotting or if you are creating many plots.  To
  automate running the plotting program build one or more targets to
  generate these files and then add these targets as \latex dependencies
  (see Section~\ref{sec:IdentifyingDependentFiles} for information on
  adding dependencies).  Here is an example of creating the targets for
  converting a directory of \textprog{gri} files and incorporating the
  resulting files in a \latex document.

  \begin{CodeListing}
# Set GRI executable
set(GRI_COMPILE "/usr/bin/gri")
# Set the location of data files
set(DATA_DIR data)
# Set the location of the directory for image files
set(IMAGE_DIR graphics)

# Get a list of gri files
file(GLOB_RECURSE GRI_FILES "*.gri")

foreach(file ${GRI_FILES})
  get_filename_component(basename "${file}" NAME_WE)
  # Replace stings in gri file so data files can be found
  file(READ
    ${CMAKE_CURRENT_SOURCE_DIR}/${IMAGE_DIR}/${basename}.gri
    file_contents
    )
  string(REPLACE "${DATA_DIR}" "${IMAGE_DIR}/${DATA_DIR}"
    changed_file_contents ${file_contents}
    )
  file(WRITE
    ${CMAKE_CURRENT_BINARY_DIR}/${IMAGE_DIR}/${basename}.gri
    ${changed_file_contents}
    )

  # Command to run gri
  if(GRI_COMPILE)
    add_custom_command(
      OUTPUT
        ${CMAKE_CURRENT_BINARY_DIR}/${IMAGE_DIR}/${basename}.eps
      DEPENDS
        ${CMAKE_CURRENT_BINARY_DIR}/${IMAGE_DIR}/${basename}.gri
        ${CMAKE_CURRENT_BINARY_DIR}/${IMAGE_DIR}/${DATA_DIR}
      COMMAND
        ${GRI_COMPILE}
      ARGS
        -output
        ${CMAKE_CURRENT_BINARY_DIR}/${IMAGE_DIR}/${basename}.eps
        ${CMAKE_CURRENT_BINARY_DIR}/${IMAGE_DIR}/${basename}.gri
      )
  endif()
  # Make a list of all gri files (for ADD_LATEX_DOCUMENT depend)
  set(ALL_GRI_FILES ${ALL_GRI_FILES}
    ${CMAKE_CURRENT_BINARY_DIR}/${IMAGE_DIR}/${basename}.eps
    )
endforeach(file)

# Copy over all data files needed to generate gri graphs
add_custom_command(
  OUTPUT  ${CMAKE_CURRENT_BINARY_DIR}/${IMAGE_DIR}/${DATA_DIR}
  DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/${IMAGE_DIR}/${DATA_DIR}
  COMMAND ${CMAKE_COMMAND} -E copy_directory
          ${CMAKE_CURRENT_SOURCE_DIR}/${IMAGE_DIR}/${DATA_DIR}
          ${CMAKE_CURRENT_BINARY_DIR}/${IMAGE_DIR}/${DATA_DIR}
  )

add_latex_document(MyDoc.tex
  IMAGE_DIRS ${IMAGE_DIR}
  DEPENDS ${ALL_GRI_FILES}
  )
  \end{CodeListing}

  \subsection{Why does make stop after each image conversion?}
  \label{sec:Why_does_make_stop_after_each_image_conversion}

  There is a bug in the ImageMagick convert version 6.1.8 that
  inappropriatly returns a failure condition even when the image convert
  was successful. The problem might also occur in other ImageMagick
  versions. Try updating your installation of ImageMagick.

  \subsection{How do I resolve \textbackslash{}write 18 errors with \textlatexpackage{pstricks} or \textlatexpackage{pdftricks}?}
  \label{sec:How_do_I_resolve_write_18_errors_with_pstricks_or_pdftricks}

  A \textlatex|\write18| command is \latex's obtuse syntax for running a
  command on your system.  Commands in the \textlatexpackage{pstricks} and
  \textlatexpackage{pdftricks} packages may need to run commands on your
  system to, for example, convert graphics from one format to another.

  Unfortunately, allowing \latex to run commands on your system can be
  considered a security issue.  Some versions of \latex such as \miktex
  disable the feature by default.  Thus, in order to use packages that rely
  on \textlatex|\write18|, you may have to enable the feature, typically
  with a command line option.  For \miktex, this command line option is
  \textcmake{--enable-write18}.

  You can instruct \UseLATEX to pass any flag to \latex by adding it to the
  \textcmakevar{LATEX\_COMPILER\_FLAGS} CMake variable.  One way to do this
  is through the CMake GUI.  Simply go to the advanced variables, find
  \textcmakevar{LATEX\_COMPILER\_FLAGS}, and add
  \textcmake{--enable-write18} (or equivalent flag) to the list of
  arguments.

  You can also automatically add this flag by setting the flag in your
  \textfile{CMakeLists.txt} file.  For example:

  \begin{CodeListing}
set(LATEX_COMPILER_FLAGS
  "-interaction=nonstopmode --enable-write18"
  CACHE STRING "Flags passed to latex."
  )
include(UseLATEX.cmake)
  \end{CodeListing}

  The disadvantage of this latter approach is the reduction of portability.
  This addition could cause a failure for any \latex implementation that
  does not support the \textcmake{--enable-write18} flag (for which there
  are many).

  \subsection{Why is \UseLATEX complaining about image file names?}
  \label{sec:Why_is_UseLATEX_complaining_about_image_file_names}

  If you have an image file with a filename that contains multiple periods,
  for example \textfile{my.image.pdf}, \UseLATEX will issue a warning like
  the following.

  \begin{CodeListing}
Some LaTeX distributions have problems with image file names
with multiple extensions.  Consider changing my.image.pdf to
something like my-image.pdf.
  \end{CodeListing}

  This is because, just as the warning reports, some versions of \latex
  have problems with including image filenames with multiple extensions.
  For example, if you tried to include \textfile{my.image.pdf} with a
  command like
  \begin{CodeListing}
\includegraphics{my.image}
  \end{CodeListing}
  then some versions of \latex will respond that the image extension
  \textfile{.image} is not recognized or that the file \textfile{my.image}
  is not found because it fails to look for files with valid extensions.

  Although it is inadvisable (per Section~\ref{sec:IncoporatingImages}),
  you might try to get around the problem by specifying the extension like
  this.
  \begin{CodeListing}
\includegraphics{my.image.pdf}
  \end{CodeListing}
  This might work, or it might just make \latex complain that it does not
  recognize images with extension \textfile{.image.pdf}.

  In the end, the best solution is to simply use filenames that will not
  trouble \latex.  Even though some \latex distributions (like \mactex)
  seem to handle this extension ambiguity correctly, others clearly do
  not.  Thus, even if your \latex distribution handles these image
  filenames correctly, it is still a bad idea in case you need to change
  distributions or build on other computers.  Your best course of action is
  to simply heed the warning and rename your files.

  \subsection{Why are there no \textcmake{FORCE\_PS} or \textcmake{FORCE\_SAFEPDF} options?}
  \label{sec:Why_are_there_no_FORCE_PS_or_FORCE_SAFEPDF_options}

  Because you should just use the \textcmake{FORCE\_DVI} option instead.

  Both the \textmaketarget{ps} and \textmaketarget{safepdf} targets are
  built by first creating a \textfile{.dvi} file using the standard
  \textprog{latex} program. The \textfile{.dvi} file is then converted to
  \textfile{.ps} and subsequently to a \textfile{.pdf} file. Thus, you can
  just enable the \textcmake{FORCE\_DVI} option to force \UseLATEX on this
  build path.

  The force options are really disabling compile paths that do not work for
  your document. For example, \textprog{pdflatex} does not support all
  postscript packages, so that program can fail for some documents. The
  \textcmake{FORCE\_DVI} ensures that the document can only be built in
  ways that support the postscript features.

  \subsection{Why is my image file not being automatically converted?}
  \label{sec:Why_is_my_image_file_not_being_automatically_converted}

  \UseLATEX has the ability to find image files and automatically convert
  them to a format \latex understands. Usually this conversion happens with
  the ImageMagick \textprog{magick} program.

  Users occasionally report that image formats that should be supported
  because ImageMagick can convert them are ignored by \UseLATEX. This can
  happen even when the \textcmake{IMAGE\_DIRS} option points to the
  directory containing the image files.

  The problem here is that \UseLATEX only considers files in
  \textcmake{IMAGE\_DIRS} directories that it identifies as a bona fide
  image. This prevents \UseLATEX from picking up another type of file, such
  as a README text file, and erroneously trying to do image conversion on
  it.

  \UseLATEX checks for image files by looking for a known set of image
  extensions. This extension list is maintained separately from
  ImageMagick's extension list and is generally a small subset of all the
  potential formats ImageMagick supports. Consequently, it is possible for
  \UseLATEX to ignore an image file that could be converted.

  You can work around this problem by specifying images independently with
  the \textcmake{IMAGES} option. \UseLATEX will assume any image specified
  under the \textcmake{IMAGES} option is in fact an image that can be
  converted with ImageMagick regardless of the extension. See
  Section~\ref{sec:IncoporatingImages} for more details.

  If there is a file extension that you think should be added to the list
  of image extensions to check, send a note to the \UseLATEX maintainers.

  \subsection{Why is the \textcmake{MANGLE\_TARGET\_NAMES} option deprecated?}
  \label{sec:Why_is_the_MANGLE_TARGET_NAMES_option_deprecated}

  The original concept for \UseLATEX was part of a build system for a
  single document. As such, \ald created generically named targets (like
  \textmaketarget{dvi} and \textmaketarget{pdf}). This became problematic
  when \UseLATEX was used in larger projects that built multiple targets.
  The multiple documents would each try to create their own
  \textmaketarget{dvi}, \textmaketarget{pdf}, etc. targets, and this would
  create CMake errors when they conflicted with each other.

  To solve this problem, in 2006 the \textcmake{MANGLE\_TARGET\_NAMES} was
  added to \ald. When this option was given, \ald would create ``mangled''
  targets that are unique to the name of the document so that they would
  not conflict with each other.

  This option solved the problem for projects building multiple documents,
  but a couple of undesirable elements were later discovered. The first was
  that \latex documents built with the \textcmake{MANGLE\_TARGET\_NAMES}
  option were never built by default. To build the document, the user had
  to specifically request the target, which had an unwieldy name, to be
  built or to explicitly set up dependencies to those targets. The second
  and more serious issue was that if a project incorporated one or more
  sub-projects (not uncommon) and more than one of these projects used
  \UseLATEX, you were likely to get conflicting targets again.

  Consequently, in 2015 a change was made to \ald to mangle all targets.
  The \UseLATEX package establishes a single set of default target names
  (\textmaketarget{dvi}, \textmaketarget{pdf}, etc.), and \ald sets up
  dependencies from these default targets to the mangled target names.
  Thus, when \UseLATEX is used for a single document, the same simple
  targets work fine. When multiple documents are added, the default targets
  are automatically set up for all documents without conflicts. See
  Section~\ref{sec:BuldingMultipleLatexDocuments} for more details on
  building multiple \latex documents in a project.

  So, \textcmake{MANGLE\_TARGET\_NAMES} is deprecated because it is
  redundant. All targets are mangled. The only difference is that \ald
  establishes dependencies to the default target names. If these dependency
  targets are not desired, use the \textcmake{EXCLUDE\_FROM\_DEFAULTS}
  option. (Once again, see Section~\ref{sec:BuldingMultipleLatexDocuments}
  for more details.)

  \subsection{What is the point of the default \latex arguments?}
  \label{sec:What_is_the_point_of_the_default_latex_arguments}

  The \latex commands (e.g. \textprog{latex} and \textprog{pdflatex}) were originally designed to be run interactively.
  The \textfile{tex} file is fed to the interpreter and verbose responses are generated.
  When an error is encountered, \latex stops and provides a prompt to type commands to resolve the problem.
  This interactive mode of building a \latex file is problematic when attempting to automate it in a batch or build system.
  Thus, the \textcmakevar{LATEX\_COMPILER\_FLAGS} and \textcmakevar{PDFLATEX\_COMPILER\_FLAGS}, which contain the command line flags passed to the \latex program, are initialized to modify the behavior to work better in a build system.

  The first flag added is \mbox{\textcmake{-interaction=batchmode}}.
  This flag does two major things.
  The first thing this flag does is hide most of the \latex output.
  A typical \latex build contains extremely verbose status messages that provide all sorts of useless information.
  Any important information (like a syntax error) is easily lost.
  Instead, you have to consult the \textfile{.log} file to see the full output.
  Because important warnings can be hidden along with the unimportant, \UseLATEX performs several greps of the log file after the build to look for the most important warnings encountered with \latex.

  The second thing the \mbox{\textcmake{-interaction=batchmode}} flag does is to change the behavior of \latex when an error occurs.
  Rather than enter an interactive prompt, the \latex program simply quits.
  This is how pretty much every build system expects a compiler to behave.

  The second flag added is \mbox{\textcmake{-file-line-error}}.
  For some odd reason the default behavior of \latex is to simply print out a message and leave it you to trace the location of the error.
  Instead, this flag instructs \latex to prepend the filename and line number to every error to simplify finding the error.

  \subsection{Why do the \textprog{ps2pdf} arguments have the \textcmake{\#} character in them?}
  \label{sec:Why_do_the_ps2pdf_arguments_have_the_hash_character_in_them}

  When calling the \textprog{ps2pdf} program, it is typical to use several arguments that are passed to the underlying ghostscript system.
  These arguments often take the form of an option followed by an equal (\textcmake{=}) character and then the value for that option.
  For example, arguments like \mbox{\textcmake{-dCompatibilityLevel=1.3}}, \mbox{\textcmake{-dEmbedAllFonts=true}}, and \mbox{\textcmake{-dColorImageFilter=/FlateEncode}} are common.
  This is a standard convention for command line arguments in systems using Unix-like shells.

  In truth, the \textprog{ps2pdf} program and its variants are actually shell scripts that provide a simplified interface for calling the \textprog{gs} ghostscript program.
  On Unix-like systems they are naturally enough implemented as shell scripts.
  However, the standard Windows port instead uses \textprog{bat} scripts, which are native to that system.
  Unfortunately, the interpreter for \textprog{bat} scripts treats the \textcmake{=} character as special.
  Ultimately it will split the arguments on the \textcmake{=} character, and that will lead to strange errors from \textprog{ps2pdf}.
  For example, on Windows the \mbox{\textcmake{-dCompatibilityLevel=1.3}} argument will be split into the arguments \mbox{\textcmake{-dCompatibilityLevel}} and \mbox{\textcmake{1.3}}.
  \textprog{ps2pdf} will think \mbox{\textcmake{1.3}} is referring to the input file name and give an obtuse error about the file not being found.

  The workaround is that \textprog{gs} (and therefore all its derived scripts like \textprog{ps2pdf}) support using the \textcmake{\#} character in lieu of \textcmake{=}.
  Thus, on Windows machines, \UseLATEX defaults to an alternate set of arguments for \textprog{ps2pdf} that use \textcmake{\#} in them.

  An issue you might encounter is that the \textcmake{\#} character is also frequently treated as special by script and build interpreter.
  It is most often used to define a comment.
  For this reason the \textcmake{\#} variant is only used on Windows where it is most likely to be needed.
  The build systems I have tried seem pretty resilient to using \textcmake{\#} in commands.
  If you have issues running \textprog{ps2pdf} with either character, you can attempt to resolve the problem by switching back and forth.
  If you do notice a problem, please let us know so that we can fix it for other users.

  %-----------------------------------------------------------------------------


  \section{Acknowledgments}

  Thanks to all of the following contributors.

  \begin{description}
  \item[Matthias Bach] Instructions for using \lualatex.
  \item[Martin Baute] Check for Windows version of convert being used
    instead of ImageMagick's version.
  \item[Izaak Beekman]
    Help in fixing the order of arguments for \textcmakevar{LATEX\_SMALL\_IMAGES} with Imagemagick 7.0.
  \item[Arnout Boelens] Example of using gri in conjunction with \latex.
  \item[Mark de Wever] Fixes for interactions between the
    \textprog{makeglossaries} and \bibtex commands.
  \item[Alin Elena] Suggestions on removing dependence on makeglossaries
    command.
  \item[Myles English] Support for the \textlatexpackage{nomencl} package.
  \item[Tomasz Grzegurzko] Support for htlatex.
  \item[\O{}ystein S. Haaland] Support for making glossaries.
  \item[Sven Klomp] Help with \synctex support.
  \item[Nikos Koukis]
    Suggestions for default \textprog{latex} options.
  \item[Thimo Langbehn] Support for pstricks with the
    \textcmake{--enable-write18} option.
  \item[Antonio LaTorre] Support for the \textlatexpackage{multibib}
    package.
  \item[Edwin van Leeuwen] Fix for a bug when copying \bibtex files.
  \item[Dan Lipsa] Support for the \textlatexpackage{multind} package.
  \item[Lukasz Lis] Workaround for problem with ImageMagick dropping the
    BoundingBox of eps files by using the \textprog{ps2pdf} program
    instead.
  \item[Eric Noulard] Support for any file extension on \latex input files.
  \item[Theodore Papadopoulo] \textcmake{DEPENDS} parameter for \ald and
    help in identifying some dependency issues.
  \item[Jorge Gerardo Pe\~{n}a Pastor] Support for SVG files.
  \item[Julien Schueller] Check for existence of Imagemagick convert only
    when used.
  \item[David Tracey] Support for using \textprog{biber} command with the
    \textcmake{USE\_BIBLATEX} option.
  \item[Raymod Wan] \textcmake{DEFAULT\_SAFEPDF} option.
  \end{description}

  This work was primarily done at Sandia National Laboratories.  Sandia is
  a multiprogram laboratory operated by Sandia Corporation, a Lockheed
  Martin Company, for the United States Department of Energy's National
  Nuclear Security Administration under contract DE-AC04-94AL85000.

  This document is released as technical report \SANDNumber.

  %-----------------------------------------------------------------------------

  \appendix

  \section{Sample CMakeLists.txt}
  \label{sec:SampleCMakeLists.txt}

  Following is a sample listing of CMakeLists.txt.  In fact, it is the
  CMakeLists.txt that is used to build this document.

  \includeCodeListing{CMakeLists.txt}

  %% \section{UseLATEX.cmake Listing}
  %% \label{sec:UseLATEX.cmakeListing}

  %% \includeCodeListing[fontsize=\footnotesize]{UseLATEX.cmake}

\end{document}