UseLATEX/UseLATEX.tex

% -*- latex -*-

\documentclass{article}

\newcommand{\UseLATEXVersion}{1.7.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*{\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, and pdf 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{Usage}
  \label{sec:Usage}

  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.
  \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.

  \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 convert to
  convert the file times to those appropriate for the build. 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.

  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{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 the current version of
  CMake.\footnote{CMake version 2.4 as of this writing.} 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{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} 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.  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{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{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 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:Usage}, \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{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 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).

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

  
  \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[\O{}ystein S. Haaland] Support for making glossaries.
  \item[Thimo Langbehn] Support for pstricks with the
    \textcmake{--enable-write18} option.
  \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[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}