Get first line of release notes

The previous version of release-version.sh was dropping the first
line of the release notes. This change adds that first line to
the release notes.

.gitignore

@@ -0,0 +1,3 @@
+*.swp
+*~
+

README

@@ -1,34 +0,0 @@
-Compiling LaTeX files into readable documents is actually a very involved
-process.  Although CMake comes with 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.cmake".  Here
-are some of the things UseLATEX.cmake handles:
-
-* Runs LaTeX multiple times to resolve links.
-
-* Can run bibtex, makeindex, and makeglossaries to make bibliographies,
-  indexes, and/or glossaries.
-
-* Optionally runs configure on your latex files to replace @VARIABLE@ with
-  the equivalent CMake variable.
-
-* Automatically finds png, jpeg, eps, and pdf files and converts them to
-  formats latex and pdflatex understand.
-
-This repository contains the CMake macros in the UseLATEX.cmake file.  To
-get started, copy this file to your own LaTeX project and include it in
-your build process.
-
-You will also find a LaTeX document, UseLATEX.tex, that contains all of the
-documentation for UseLATEX.cmake.  You will also find a CMake build file,
-CMakeLists.txt, that uses UseLATEX.cmake to build UseLATEX.tex.  It also
-serves as a good example for using UseLATEX.cmake.
-
-You can find the latest information on UseLATEX.cmake on the CMake Wiki at
-the following URL.
-
-    http://www.cmake.org/Wiki/CMakeUserUseLATEX
-
-

README.md

@@ -0,0 +1,42 @@
+Compiling LaTeX files into readable documents is actually a very involved
+process. Although CMake comes with 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.cmake](UseLATEX.cmake). Here are some of the
+things [UseLATEX.cmake](UseLATEX.cmake) handles:
+
+  * Runs LaTeX multiple times to resolve links.
+  * Can run bibtex, makeindex, and makeglossaries to make bibliographies,
+    indexes, and/or glossaries.
+  * Optionally runs configure on your latex files to replace `@VARIABLE@`
+    with the equivalent CMake variable.
+  * Automatically finds png, jpeg, eps, and pdf files and converts them to
+    formats latex and pdflatex understand.
+
+## Download
+
+The files can be downloaded directly from the UseLATEX project page. If you
+are viewing this from a web page, you can follow the following links.
+
+  * Click here to get a copy of [UseLATEX.cmake](https://gitlab.kitware.com/kmorel/UseLATEX/raw/master/UseLATEX.cmake).
+  * Click here to get the documentation [UseLATEX.pdf](https://gitlab.kitware.com/kmorel/UseLATEX/raw/master/UseLATEX.pdf).
+  
+## Repository
+
+This repository contains the CMake macros in the
+[UseLATEX.cmake](UseLATEX.cmake) file. To get started, copy this file to
+your own LaTeX project and include it in your build process.
+
+You will also find a LaTeX document, [UseLATEX.tex](UseLATEX.tex), that
+contains all of the documentation for [UseLATEX.cmake](UseLATEX.cmake). You
+will also find a CMake build file, [CMakeLists.txt](CMakeLists.txt), that
+uses [UseLATEX.cmake](UseLATEX.cmake) to build
+[UseLATEX.tex](UseLATEX.tex). It also serves as a good example for using
+[UseLATEX.cmake](UseLATEX.cmake).
+
+There has been some requests to incorporate UseLATEX.cmake into the CMake
+repository and distribution. Nobody thinks this is a bad idea, but it
+hasn't yet happened mostly out of laziness. Keep bugging me to show
+interest in moving UseLATEX.cmake. (See the author contact information at
+the top of [UseLATEX.cmake](UseLATEX.cmake).)

UseLATEX.tex

@@ -2,7 +2,7 @@
 
 \documentclass{article}
 
-\newcommand{\UseLATEXVersion}{2.0.0}
+\newcommand{\UseLATEXVersion}{2.7.0}
 \newcommand{\SANDNumber}{SAND 2008-2743P}
 
 % This wonderful package allows hyphenation in tt fonts and hyphenation of
@@ -85,9 +85,11 @@
     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.
+  \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.
+  \item Reduces \latex's overly verbose output and searches for messages
+    that are more likely to require attention.
   \end{itemize}
 
   %-----------------------------------------------------------------------------
@@ -133,7 +135,7 @@ add_latex_document(MyDoc.tex)
       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.
+      \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
@@ -199,7 +201,7 @@ add_latex_document(MyDoc.tex
 
   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.
+  after the \textcmake{IMAGE\_DIRS} option.
 
   \begin{CodeListing}
 add_latex_document(MyDoc.tex
@@ -225,27 +227,14 @@ add_latex_document(MyDoc.tex
   \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.
+  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{convert}.  For example, \textprog{ps2pdf} will be
+  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
@@ -254,6 +243,21 @@ add_latex_document(MyDoc.tex
   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
@@ -280,9 +284,9 @@ add_latex_document(MyDoc.tex
 
   \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
+  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
@@ -403,7 +407,7 @@ add_latex_document(MyDoc.tex
 
   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
+  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.
 
@@ -415,6 +419,39 @@ add_latex_document(MyDoc.tex
   )
   \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}
 
@@ -521,6 +558,28 @@ add_latex_document(MyDoc.tex
   )
   \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}
@@ -652,6 +711,24 @@ add_latex_document(MyDoc3.tex EXCLUDE_FROM_DEFAULTS)
   \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}
 
@@ -659,11 +736,8 @@ add_latex_document(MyDoc3.tex EXCLUDE_FROM_DEFAULTS)
   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.
+  If this is the case, simply add the appropriate CMake commands to generate the input files, and then add that file to the \textcmake{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)
@@ -676,6 +750,33 @@ add_custom_command(OUTPUT ${output_dir}/generated_file.tex
 add_latex_document(MyDoc.tex DEPENDS generated_file.tex)
   \end{CodeListing}
 
+  \subsection{Adding Include Directories}
+  \label{sec:AddingIncludeDirectories}
+
+  It is usually best practice to collect \latex input files in a single directory with a logical set of subdirectories, which can be referenced within the \latex document using relative paths.
+  However, it is sometimes convenient to search for files in directories other than the build directory.
+
+  For example, let us say that we have two reports that you want to combine into a single combined report.
+  For any number of technical reasons, it could be desirable to place the two original reports untouched in subdirectories and have the tex file for the combine report in the main directory and including the sub-reports.
+  However, if those sub-reports are including files that are relative to their respective subdirectories, for example including images for figures, then \latex will produce an error because it will be looking for those files in the main directory.
+
+  We can get around this problem by using the \textcmake{INCLUDE\_DIRECTORIES} option to \ald.
+  Simply add the subdirectories to the \textcmake{INCLUDE\_DIRECTORIES} list and \latex will look for included files locally in those directories.
+  Here is an example of how that might look to include image files.
+
+  \begin{CodeListing}
+add_latex_document(UberReport.tex
+  INPUTS report1/Report1.tex report2/Report2.tex
+  IMAGE_DIRS report1/images report2/images
+  INCLUDE_DIRECTORIES report1 report2
+  )
+  \end{CodeListing}
+
+  Note that the \textcmake{INCLUDE\_DIRECTORIES} option should be used with care.
+  If a file with the same name exists in multiple included directories, \latex might not pick up the file you are expecting.
+  (\latex will first look in the build directory, then the directories listed in \textcmake{INCLUDE\_DIRECTORIES} in the order given, and then system directories.)
+  Thus, in the previous example if both reports had image files with the same name, the second report will likely include images from the first report.
+
   %-----------------------------------------------------------------------------
 
   \section{Frequently Asked Questions}
@@ -698,7 +799,7 @@ add_latex_document(MyDoc.tex DEPENDS generated_file.tex)
   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},
+  \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
@@ -819,10 +920,9 @@ CMake Error at UseLATEX.cmake:377 (MESSAGE):
   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.
+  run the \textprog{magick} or \textprog{convert} program.
 
-  A common error is that \textprog{convert} not finding a file that
-  is clearly there.
+  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'
@@ -854,17 +954,14 @@ convert.exe: unable to open image `C:': Permission denied.
 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. Recent versions of \UseLATEX
-  should give a specific warning about this with instructions on how to fix
-  it.
+  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}
@@ -1011,8 +1108,8 @@ include(UseLATEX.cmake)
 
   \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.
+with multiple extensions or spaces.  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
@@ -1043,6 +1140,57 @@ something like my-image.pdf.
   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}
 
@@ -1086,6 +1234,57 @@ something like my-image.pdf.
   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.
+
   %-----------------------------------------------------------------------------
 
 
@@ -1097,20 +1296,26 @@ something like my-image.pdf.
   \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[Eric D\"{o}nges] Support for include directories.
   \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.
@@ -1120,6 +1325,8 @@ something like my-image.pdf.
   \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}
 

scripts/release-version.sh

@@ -0,0 +1,183 @@
+#!/bin/bash
+#
+# Checks to make sure that the version number is consistent across all
+# files, then issues the git commands to tag the version.
+
+# A simple function to ask the user if they want to continue.
+function ask_keep_going {
+    read -ep "Are you sure you want to continue? [y/N] " keep_going
+    if [ "$keep_going" != "y" -a "$keep_going" != "Y" ]
+    then
+	echo "Aborting"
+	exit 1
+    fi
+    echo
+}
+
+# Run in repo base directory
+cd `dirname $0`/..
+
+echo "Fetching origin..."
+git fetch origin
+echo
+
+# Extract the version number from UseLATEX.cmake
+version_line=`head -n 3 UseLATEX.cmake | tail -n 1`
+
+version=`echo $version_line | sed -n 's/# Version: \([0-9]*\.[0-9]*\.[0-9]*\)/\1/p'`
+
+if [ -z $version ]
+then
+    echo "Could not extract version number from UseLATEX.cmake."
+    echo "The third line should be of the form '# Version: X.X.X'."
+    exit 1
+fi
+
+echo "Found version $version in UseLATEX.cmake"
+echo
+
+echo -n "Checking for $version in UseLATEX.tex..."
+if fgrep -q '\newcommand{\UseLATEXVersion}{'$version'}' UseLATEX.tex
+then
+    echo "OK"
+else
+    echo "FAIL"
+    echo
+    echo "Could not find $version in UseLATEX.tex."
+    echo "There should be a line in UseLATEX.tex like the following:"
+    echo '    \newcommand{\UseLATEXVersion}{'$version'}'
+    echo "Add it."
+    exit 1
+fi
+
+echo -n "Checking for $version in UseLATEX.pdf..."
+if pdftotext UseLATEX.pdf - | grep -q 'Version *'$version
+then
+    echo "OK"
+else
+    echo "FAIL"
+    echo
+    echo "Could not find $version in UseLATEX.pdf (using pdftotext)."
+    echo "Rebuild the pdf documentation and copy it to the working repo."
+    exit 1
+fi
+
+git_version_tag="Version$version"
+echo -n "Checking for git tag $git_version_tag..."
+if git rev-list $git_version_tag.. > /dev/null 2>&1
+then
+    echo "FAIL"
+    echo
+    echo "Version tag $git_version_tag already exists in git repository."
+    echo "Either change the version in UseLATEX.cmake or remove the version"
+    echo "tag (with 'git tag -d $git_version_tag')."
+    exit 1
+else
+    echo "OK"    
+fi
+
+echo -n "Checking for tabs in UseLATEX.cmake..."
+if fgrep -q "$(printf '\t')" UseLATEX.cmake
+then
+    echo "FAIL"
+    echo
+    echo "Tab characters were found in UseLATEX.cmake. For consistent style"
+    echo "replace all tab characters with spaces to the desired column."
+    exit 1
+else
+    echo "OK"
+fi
+
+echo -n "Extracting notes for $version..."
+version_notes=`sed -n "/# $version/,/# [0-9]/{
+s/^# $version *//
+/^# [0-9]/d
+s/^# *//
+p
+}" UseLATEX.cmake`
+if [ \( $? -eq 0 \) -a \( -n "$version_notes" \) ]
+then
+    echo "OK"
+else
+    echo "FAIL"
+    echo
+    echo "Could not find the notes for this release in the History list."
+    echo "Make sure an item has been added to the release history."
+    ask_keep_going
+fi
+version_notes="
+$version_notes"
+
+echo -n "Checking that the working directory is clean..."
+if [ -z "`git status --porcelain`" ]
+then
+    echo "OK"
+else
+    echo "FAIL"
+    echo
+    echo "There are uncommitted changes to your repository. Make sure that the"
+    echo "working directory is clean before running this script."
+    exit 1
+fi
+
+echo -n "Checking that we are on the master branch..."
+if [ "`git rev-parse --abbrev-ref HEAD`" = "master" ]
+then
+    echo "OK"
+else
+    echo "FAIL"
+    echo
+    echo "Not currently on the master branch."
+    ask_keep_going
+fi
+
+echo -n "Checking that we are up to date on master..."
+if git merge-base --is-ancestor origin/master HEAD
+then
+    echo "OK"
+else
+    echo "FAIL"
+    echo
+    echo "The local repository does not have the latest version from the"
+    echo "central repository. This is OK if you are retroactively tagging"
+    echo "a version but might be in error if you are tagging new changes."
+    ask_keep_going
+fi
+
+echo -n "Checking that master is up to date on origin..."
+if git merge-base --is-ancestor HEAD origin/master
+then
+    echo "OK"
+else
+    echo "FAIL"
+    echo
+    echo "Your latest changes do not appear to be in the central repository."
+    echo "It is recommended to update the remote repository before tagging"
+    echo "a version."
+    ask_keep_going
+fi
+
+# We are finished with all the checks. Do the tag.
+echo -n "Tagging with $git_version_tag..."
+if git tag --annotate --edit --message="UseLATEX.cmake Release $version
+$version_notes
+
+# Write a message for tag:
+#   $git_version_tag
+# Lines starting with '#' will be ignored.
+" $git_version_tag
+then
+    echo "OK"
+else
+    echo "FAIL"
+    echo
+    echo "Could not tag repository for some reason."
+    exit 1
+fi
+
+echo
+echo "Finished tagging to version $version."
+echo "To push the tags to the remote repository, execute"
+echo
+echo "    git push --tags"
+echo

tests/Bibliography/CMakeLists.txt

@@ -0,0 +1,14 @@
+cmake_minimum_required(VERSION 2.8.4)
+
+project(Bibliography NONE)
+
+include(../../UseLATEX.cmake)
+
+add_latex_document(DocWithBib.tex
+  BIBFILES References.bib
+  )
+
+add_latex_document(DocWithBibLatex.tex
+  BIBFILES References.bib
+  USE_BIBLATEX
+  )

tests/Bibliography/DocWithBib.tex

@@ -0,0 +1,10 @@
+\documentclass{article}
+
+\begin{document}
+
+This document tests citations such as these \cite{Moreland2008}.
+
+\bibliographystyle{plain}
+\bibliography{References}
+
+\end{document}

tests/Bibliography/DocWithBibLatex.tex

@@ -0,0 +1,14 @@
+\documentclass{article}
+
+\usepackage[backend=biber]{biblatex}
+
+\addbibresource{References.bib}
+
+\begin{document}
+
+This document tests citations through the biblatex package such as these
+\cite{Moreland2008}.
+
+\printbibliography
+
+\end{document}

tests/Bibliography/README

@@ -0,0 +1,4 @@
+This test exercises the ability to build documents with bibliographies
+built from bib files. There are two documents. The first builds the
+bibliography with the typical bibtex program. The second uses the
+biblatex package and builds the bibliography with biber.

tests/Bibliography/References.bib

@@ -0,0 +1,7 @@
+@techreport{Moreland2008,
+	Author = {Kenneth Moreland},
+	Title = {{UseLATEX.cmake}: {\LaTeX} Document Building Made Easy},
+	Institution = {Sandia National Laboratories},
+	Number = {SAND 2008-2743P},
+	Year = {2008}
+}

tests/DefaultTargets/CMakeLists.txt

@@ -4,7 +4,7 @@ project(DefaultTargets NONE)
 
 include(../../UseLATEX.cmake)
 
-add_latex_document(DefaultDvi.tex FORCE_DVI)
-add_latex_document(DefaultPdf.tex FORCE_PDF)
-add_latex_document(DefaultHtml.tex FORCE_HTML)
-add_latex_document(NoDefault.tex EXCLUDE_FROM_ALL)
+add_latex_document(DefaultDvi.tex IMAGE_DIRS images FORCE_DVI)
+add_latex_document(DefaultPdf.tex IMAGE_DIRS images FORCE_PDF)
+add_latex_document(DefaultHtml.tex IMAGE_DIRS images FORCE_HTML)
+add_latex_document(NoDefault.tex IMAGE_DIRS images EXCLUDE_FROM_ALL)

tests/DefaultTargets/DefaultDvi.tex

@@ -1,9 +1,15 @@
 \documentclass{article}
 
+\usepackage{graphicx}
+
 \begin{document}
 
 \Large
 \noindent
 This document builds \textbf{\Huge dvi} by default.
 
+\includegraphics[width=2in]{images/Circles_pdf}
+\includegraphics[width=2in]{images/Circles_eps}
+\includegraphics[width=2in]{images/Cool2WarmBar}
+
 \end{document}

tests/DefaultTargets/DefaultHtml.tex

@@ -1,9 +1,15 @@
 \documentclass{article}
 
+\usepackage{graphicx}
+
 \begin{document}
 
 \Large
 \noindent
 This document builds \textbf{\Huge html} by default.
 
+\includegraphics[width=2in]{images/Circles_pdf}
+\includegraphics[width=2in]{images/Circles_eps}
+\includegraphics[width=2in]{images/Cool2WarmBar}
+
 \end{document}

tests/DefaultTargets/DefaultPdf.tex

@@ -1,9 +1,15 @@
 \documentclass{article}
 
+\usepackage{graphicx}
+
 \begin{document}
 
 \Large
 \noindent
 This document builds \textbf{\Huge pdf} by default.
 
+\includegraphics[width=2in]{images/Circles_pdf}
+\includegraphics[width=2in]{images/Circles_eps}
+\includegraphics[width=2in]{images/Cool2WarmBar}
+
 \end{document}

tests/DefaultTargets/NoDefault.tex

@@ -1,9 +1,15 @@
 \documentclass{article}
 
+\usepackage{graphicx}
+
 \begin{document}
 
 \Large
 \noindent
 This document should \emph{\Huge not} be built by default.
 
+\includegraphics[width=2in]{images/Circles_pdf}
+\includegraphics[width=2in]{images/Circles_eps}
+\includegraphics[width=2in]{images/Cool2WarmBar}
+
 \end{document}

tests/File Name Spaces/CMakeLists.txt

@@ -0,0 +1,8 @@
+cmake_minimum_required(VERSION 2.8.4)
+
+project(FileNameSpaces NONE)
+
+include(../../UseLATEX.cmake)
+
+add_latex_document("My Document.tex"
+  )

tests/File Name Spaces/My Document.tex

@@ -0,0 +1,9 @@
+\documentclass{article}
+
+\usepackage{graphicx}
+
+\begin{document}
+
+This is some text.
+
+\end{document}

tests/File Name Spaces/README

@@ -0,0 +1,4 @@
+This test checks to make sure there are no problems with compiling a LaTeX
+file in a directory with spaces in the name or a file with spaces in the
+name. LaTeX itself is pretty intolerant about including files with spaces
+in the name, but our CMake code should not be.

tests/FindWarnings/CMakeLists.txt

@@ -0,0 +1,15 @@
+cmake_minimum_required(VERSION 2.8.4)
+
+project(FindWarnings NONE)
+
+include(../../UseLATEX.cmake)
+
+add_latex_document(UndefinedReference.tex)
+
+add_latex_document(UndefinedReferenceLong.tex)
+
+add_latex_document(Natbib.tex)
+
+add_latex_document(Overfull.tex)
+
+add_latex_document(DuplicateLabel.tex)

tests/FindWarnings/DuplicateLabel.tex

@@ -0,0 +1,9 @@
+\documentclass{article}
+
+\begin{document}
+
+Define the label once. \label{DefinedTwice}
+
+Define the label again. \label{DefinedTwice}
+
+\end{document}

tests/FindWarnings/Natbib.tex

@@ -0,0 +1,9 @@
+\documentclass{article}
+
+\usepackage{natbib}
+
+\begin{document}
+
+This is an undefined citation: \cite{NoSuchCite}.
+
+\end{document}

tests/FindWarnings/Overfull.tex

@@ -0,0 +1,7 @@
+\documentclass{article}
+
+\begin{document}
+
+This is an overfull box: \framebox[14in]{Box too big.}
+
+\end{document}

tests/FindWarnings/README

@@ -0,0 +1,4 @@
+This test exercises the ability for UseLATEX.cmake to make sure that
+important warnings from LaTeX are printed (whereas unimportant are
+suppressed). Each of the documents should compile successfully, but they
+all have a warning that should be reported clearly in the build.

tests/FindWarnings/UndefinedReference.tex

@@ -0,0 +1,7 @@
+\documentclass{article}
+
+\begin{document}
+
+This is an undefined reference: \ref{sec:DoesNotExist}.
+
+\end{document}

tests/FindWarnings/UndefinedReferenceLong.tex

@@ -0,0 +1,7 @@
+\documentclass{article}
+
+\begin{document}
+
+This is an undefined reference: \ref{sec:AVeryLongReferenceNameThatCausesTheWarningLineToBreakAcrossLines}.
+
+\end{document}

tests/ImageTypes/ImageTypes.tex

@@ -4,14 +4,26 @@
 
 \begin{document}
 
-\fbox{\includegraphics[width=2in]{images/Circles}}
+\fbox{\includegraphics[width=2in]{images/Circles_svg}}
 SVG
 
+\fbox{\includegraphics[width=2in]{images/Circles_pdf}}
+PDF
+
+\fbox{\includegraphics[width=2in]{images/Circles_eps}}
+EPS
+
 \fbox{\includegraphics[width=2in]{images/RainbowBar}}
 TIFF
 
 \fbox{\includegraphics[width=2in]{images/Cool2WarmBar}}
 GIF
 
+\fbox{\includegraphics[width=2in]{images/Blue2TanBar}}
+BMP
+
+\fbox{\includegraphics[width=2in]{images/Green2RedDivBar}}
+PPM
+
 
 \end{document}

tests/IncludeDirectories/CMakeLists.txt

@@ -0,0 +1,16 @@
+cmake_minimum_required(VERSION 2.8.4)
+
+project(IncludeDirectory NONE)
+
+include(../../UseLATEX.cmake)
+
+set(UseLATEX_TEST_NAME "adding include directories")
+
+add_latex_document(IncludeStuff.tex
+  INPUTS CopiedInput.tex copied-subdir/CopiedInSubdir.tex
+  INCLUDE_DIRECTORIES
+    copied-subdir
+    ${CMAKE_CURRENT_SOURCE_DIR}
+    ${CMAKE_CURRENT_SOURCE_DIR}/uncopied-subdir
+  CONFIGURE IncludeStuff.tex CopiedInput.tex copied-subdir/CopiedInSubdir.tex
+  )

tests/IncludeDirectories/CopiedInput.tex

@@ -0,0 +1,4 @@
+% -*- latex -*-
+
+% This should only compile if working with the "copied" version of the latex file.
+This is a copied input for @UseLATEX_TEST_NAME@.

tests/IncludeDirectories/IncludeStuff.tex

@@ -0,0 +1,22 @@
+% -*- latex -*-
+
+\documentclass{article}
+
+\begin{document}
+
+% Make a line that will get a parse error if this file is not configured. This makes sure that the configured file is read first.
+Running tests for @UseLATEX_TEST_NAME@.
+
+Included from CopiedInput:
+\input{CopiedInput}
+
+Included from copied-subdir/CopiedInSubdir:
+\input{CopiedInSubdir}
+
+Included from source dir:
+\input{UncopiedInput}
+
+Included from source subdirectory:
+\input{UncopiedInSubdir}
+
+\end{document}

tests/IncludeDirectories/README

@@ -0,0 +1,3 @@
+This test makes sure that the INCLUDE_DIRECTORIES option works correctly.
+It tests to make sure that it works against directories that are copied to
+the build directory and those that remain in the source directory.

tests/IncludeDirectories/UncopiedInput.tex

@@ -0,0 +1,3 @@
+% -*- latex -*-
+
+This comes from a file in the source directory.

tests/IncludeDirectories/copied-subdir/CopiedInSubdir.tex

@@ -0,0 +1,4 @@
+% -*- latex -*-
+
+% This should only compile if working with the "copied" version of the latex file.
+This is a copied input for @UseLATEX_TEST_NAME@.

tests/IncludeDirectories/uncopied-subdir/UncopiedInSubdir.tex

@@ -0,0 +1,3 @@
+% -*- latex -*-
+
+This comes from a file in a source subdirectory.

tests/MultiDocuments/CMakeLists.txt

@@ -0,0 +1,7 @@
+cmake_minimum_required(VERSION 2.8.4)
+
+project(MultiDocuments NONE)
+
+add_subdirectory(subdir1)
+add_subdirectory(subdir2)
+add_subdirectory(subdir2_2)

tests/MultiDocuments/README

@@ -0,0 +1,10 @@
+This tests appropriate behavior when a project (or multi-project) tries to
+create multiple documents with multiple add_latex_document calls. It also
+creates them in separate subdirectories, with each subdirectory
+independently loading UseLATEX.cmake. This is typical in a large project
+that might bring in several subprojects.
+
+When running this project, 3 documents should be built, one in each
+subdirectory. You should not get errors or warnings about a target being
+defined multiple times. You should be able to build using the pdf, dvi, ps,
+and safepdf targets.

tests/MultiDocuments/subdir1/CMakeLists.txt

@@ -0,0 +1,6 @@
+include(../../../UseLATEX.cmake)
+
+add_latex_document(Subdirectory1.tex
+  IMAGE_DIRS images
+  INPUTS IncludedFile.tex
+  )

tests/MultiDocuments/subdir1/IncludedFile.tex

@@ -0,0 +1 @@
+This text comes from an included file.

tests/MultiDocuments/subdir1/Subdirectory1.tex

@@ -0,0 +1,15 @@
+\documentclass{article}
+
+\usepackage{graphicx}
+
+\begin{document}
+
+\textbf{Document from subdirectory 1}
+
+Here is an image:
+\fbox{\includegraphics[width=2in]{images/Cool2WarmBar}}
+
+This included file should show up on the next page.
+\include{IncludedFile}
+
+\end{document}

tests/MultiDocuments/subdir2/CMakeLists.txt

@@ -0,0 +1,3 @@
+include(../../../UseLATEX.cmake)
+
+add_latex_document(Subdirectory2.tex)

tests/MultiDocuments/subdir2/Subdirectory2.tex

@@ -0,0 +1,7 @@
+\documentclass{article}
+
+\begin{document}
+
+\textbf{Document from subdirectory 2}
+
+\end{document}

tests/MultiDocuments/subdir2_2/CMakeLists.txt

@@ -0,0 +1,5 @@
+include(../../../UseLATEX.cmake)
+
+add_latex_document(Subdirectory2.tex
+  TARGET_NAME RenamedTargetForSubdirectory2_2
+  )

tests/MultiDocuments/subdir2_2/Subdirectory2.tex

@@ -0,0 +1,7 @@
+\documentclass{article}
+
+\begin{document}
+
+\textbf{Document from subdirectory 2\_2}
+
+\end{document}

tests/MultiIndex/CMakeLists.txt

@@ -0,0 +1,14 @@
+cmake_minimum_required(VERSION 2.8.4)
+
+project(MultiIndex NONE)
+
+include(../../UseLATEX.cmake)
+
+add_latex_document(SingleIndex.tex
+  USE_INDEX
+  )
+
+add_latex_document(MultiIndex.tex
+  USE_INDEX
+  INDEX_NAMES terms people
+  )

tests/MultiIndex/MultiIndex.tex

@@ -0,0 +1,25 @@
+\documentclass{article}
+
+\usepackage{blindtext}
+
+\usepackage{multind}
+\makeindex{terms}
+\makeindex{people}
+
+\begin{document}
+
+\index{terms}{foo}
+\index{terms}{bar}
+\index{terms}{baz}
+
+\index{people}{Homer}
+\index{people}{Marge}
+\index{people}{Bart}
+\index{people}{Lisa}
+\index{people}{Maggie}
+
+\blindtext
+
+\printindex{terms}{Term Index}
+\printindex{people}{People Index}
+\end{document}

tests/MultiIndex/README

@@ -0,0 +1,4 @@
+This test exercises the building of files that use multiple indices with
+the multind package. For completeness, making a single index with the
+makeindex package is also tested. If both documents builds, then the test
+passes.

tests/MultiIndex/SingleIndex.tex

@@ -0,0 +1,18 @@
+\documentclass{article}
+
+\usepackage{blindtext}
+
+\usepackage{makeidx}
+\makeindex
+
+\begin{document}
+
+\index{foo}
+\index{bar}
+\index{baz}
+
+\blindtext
+
+\printindex
+
+\end{document}

tests/MultiIndex/multind.sty

@@ -0,0 +1,65 @@
+% indexes document style option for producing multiple indexes
+% for use with the modified bbok style, CHbook.sty
+% Written by F.W. Long, Version 1.1, 12 August 1991.
+
+% Modified by F.W. Long, Version 1.1a, 29 August 1991
+% to get the index heading correctly spaced.
+
+% Modified by F.W. Long, Version 1.1b, 31 August 1991
+% to remove the abbreviation \ix (which should be in the document, not here).
+
+% Modified \makeindex and \index commands to allow multiple indexes
+% in both cases the first parameter is the index name.
+% They now work more like \@starttoc and \addcontentsline.
+% \index is no longer defined inside \makeindex but determines
+% whether the appropriate file is defined before writing to it.
+
+\def\makeindex#1{\begingroup
+  \makeatletter
+  \if@filesw \expandafter\newwrite\csname #1@idxfile\endcsname
+  \expandafter\immediate\openout \csname #1@idxfile\endcsname #1.idx\relax
+  \typeout{Writing index file #1.idx }\fi \endgroup}
+
+\def\index#1{\@bsphack\begingroup
+               \def\protect##1{\string##1\space}\@sanitize
+               \@wrindex{#1}}
+
+% \@wrindex now checks that the appropriate file is defined.
+
+\def\@wrindex#1#2{\let\thepage\relax
+   \xdef\@gtempa{\@ifundefined{#1@idxfile}{}{\expandafter
+      \write\csname #1@idxfile\endcsname{\string
+      \indexentry{#2}{\thepage}}}}\endgroup\@gtempa
+   \if@nobreak \ifvmode\nobreak\fi\fi\@esphack}
+
+% Modified \printindex command to allow multiple indexes.
+% This now takes over much of the work of \theindex.
+% Again, the first parameter is the index name.
+% The second parameter is the index title (as printed).
+
+\newif\if@restonecol
+\def\printindex#1#2{\@restonecoltrue\if@twocolumn\@restonecolfalse\fi
+  \columnseprule \z@ \columnsep 35pt
+  \newpage \twocolumn[{\Large\bf #2 \vskip4ex}]
+  \markright{\uppercase{#2}}
+  \addcontentsline{toc}{section}{#2}
+  \@input{#1.ind}}
+
+% The following index commands are taken from book.sty.
+% \theindex is modified to not start a chapter.
+
+\def\theindex{\parindent\z@
+ \parskip\z@ plus .3pt\relax\let\item\@idxitem}
+\def\@idxitem{\par\hangindent 40pt}
+\def\subitem{\par\hangindent 40pt \hspace*{20pt}}
+\def\subsubitem{\par\hangindent 40pt \hspace*{30pt}}
+\def\endtheindex{\if@restonecol\onecolumn\else\clearpage\fi}
+\def\indexspace{\par \vskip 10pt plus 5pt minus 3pt\relax}
+
+% the command \ix allows an abbreviation for the general index
+
+%\def\ix#1{#1\index{general}{#1}}
+
+% define the \see command from makeidx.sty
+
+\def\see#1#2{{\em see\/} #1}