UseLATEX/UseLATEX.tex

% -*- latex -*-

\documentclass{article}

\newcommand{\UseLATEXVersion}{1.9.5}
\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{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*{\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, and gif 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{LATEX2HTML\_CONVERTER} 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} command.

  \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}
  %$

  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.

  Once you establish the images directory, CMake will automatically find
  all files with known image extensions (currently eps, pdf, png, jpeg, and
  jpg) in it and add makefile targets to use ImageMagick's
  \textprog{convert} to convert the file times to those appropriate for the
  build. (One exception is that \textprog{ps2pdf} will be used when
  converting eps to pdf to get around a problem where ImageMagick drops the
  bounding box information.)  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{convert}.  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.

  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{Create a PDF by Default}
  \label{sec:CreateAPDFByDefault}

  By default, when you use \ald and then run make with no arguments, the
  dvi file will be created. You have to specifically build the pdf target
  to use \textprog{pdflatex} to create a pdf file. However, oftentimes we
  want the pdf to be generated by default. To do that, simply use the
  \textcmake{DEFAULT\_PDF} option to \ald:

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

  If you still want to use the \textprog{latex} program to compile your
  documents but by default want to create pdf files (that is, build the
  safepdf target by default), then use the \textcmake{DEFAULT\_SAFEPDF}
  option to \ald:

  \begin{CodeListing}
ADD_LATEX_DOCUMENT(MyDoc.tex
  BIBFILES MyDoc.bib
  IMAGE_DIRS images
  DEFAULT_SAFEPDF
  )
  \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} command. 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 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}

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

  \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. To do this, you must call \ald multiple
  times. However, if you do this, the dvi, pdf, etc. targets will be
  generated multiple times, and that is illegal in CMake.  To get around
  this, you need to mangle the names of the targets that \ald creates. To
  do this, use the \textcmake{MANGLE\_TARGET\_NAMES} option.

  \begin{CodeListing}
ADD_LATEX_DOCUMENT(MyDoc1.tex MANGLE_TARGET_NAMES)
ADD_LATEX_DOCUMENT(MyDoc2.tex MANGLE_TARGET_NAMES)
  \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\_*}.

  If you still want the simple, short targets to build all of the
  documents, you can add them yourself with custom targets that depend on
  the targets created by \ald

  \begin{CodeListing}
ADD_CUSTOM_TARGET(dvi)
ADD_DEPENDENCIES(MyDoc1_dvi MyDoc2_dvi)
ADD_CUSTOM_TARGET(pdf)
ADD_DEPENDENCIES(MyDoc1_pdf MyDoc2_pdf)
ADD_CUSTOM_TARGET(ps)
ADD_DEPENDENCIES(MyDoc1_ps MyDoc2_ps)
  \end{CodeListing}

  \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/index.php}{http://www.imagemagick.org/script/index.php},
  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{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{convert} program.

  A common 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.

  Another common error is that \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.

  \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(GRI_COMPILE)
  # 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.

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

  
  \section{Acknowledgments}

  Thanks to all of the following contributors.

  \begin{description}
  \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[\O{}ystein S. Haaland] Support for making glossaries.
  \item[Sven Klomp] Help with \synctex support.
  \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[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[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}