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.

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

@@ -1,6 +1,6 @@
 # File: UseLATEX.cmake
 # CMAKE commands to actually use the LaTeX compiler
-# Version: 2.4.5
+# Version: 2.7.0
 # Author: Kenneth Moreland <kmorel@sandia.gov>
 #
 # Copyright 2004, 2015 Sandia Corporation.
@@ -42,17 +42,18 @@
 # add_latex_document(<tex_file>
 #                    [BIBFILES <bib_files>]
 #                    [INPUTS <input_tex_files>]
-#                    [IMAGE_DIRS] <image_directories>
-#                    [IMAGES] <image_files>
-#                    [CONFIGURE] <tex_files>
-#                    [DEPENDS] <tex_files>
-#                    [MULTIBIB_NEWCITES] <suffix_list>
+#                    [IMAGE_DIRS <image_directories>]
+#                    [IMAGES <image_files>]
+#                    [CONFIGURE <tex_files>]
+#                    [DEPENDS <tex_files>]
+#                    [MULTIBIB_NEWCITES <suffix_list>]
 #                    [USE_BIBLATEX]
 #                    [USE_INDEX]
 #                    [INDEX_NAMES <index_names>]
 #                    [USE_GLOSSARY] [USE_NOMENCL]
 #                    [FORCE_PDF] [FORCE_DVI] [FORCE_HTML]
-#                    [TARGET_NAME] <name>
+#                    [TARGET_NAME <name>]
+#                    [INCLUDE_DIRECTORIES <directories>]
 #                    [EXCLUDE_FROM_ALL]
 #                    [EXCLUDE_FROM_DEFAULTS])
 #       Adds targets that compile <tex_file>.  The latex output is placed
@@ -113,8 +114,39 @@
 #       support the extra auxiliary files created with the \newcite command
 #       in the multibib package.
 #
+#       INCLUDE_DIRECTORIES provides a list of directories in which LaTeX
+#       should look for input files. It accepts both files relative to the
+#       binary directory and absolute paths.
+#
 # History:
 #
+# 2.7.0 Add INCLUDE_DIRECTORIES parameters. (Thanks to Eric Dönges.)
+#
+# 2.6.1 Fix issue with detecting long undefined reference warnings that
+#       LaTeX "helpfully" split across lines (and which fowled up our
+#       regex).
+#
+# 2.6.0 Skip image conversion targets that are not used when a force option
+#       is given. This helps prevent errors for missing conversion programs
+#       that are not needed. (Thanks to Martin Wetzel.)
+#
+# 2.5.0 Parse biber output for warnings.
+#
+#       For regular bibtex, you get warnings about undefined references
+#       when you run latex. However, when using biber, biber itself prints
+#       out the said warning and latex sees nothing. Thus, when using biber
+#       the regular output is now suppressed and the log file is scanned
+#       for potential issues.
+#
+# 2.4.9 Use biblatex.cfg file if it exists and the USE_BIBLATEX option is ON.
+#
+# 2.4.8 Fix synctex issue with absolute paths not being converted.
+#
+# 2.4.7 Fix some issues with spaces in the path of the working directory where
+#       LaTeX is executed.
+#
+# 2.4.6 Fix parse issue with older versions of CMake.
+#
 # 2.4.5 Fix issues with files and paths containing spaces.
 #
 # 2.4.4 Improve error reporting message when LaTeX fails.
@@ -422,10 +454,6 @@ endfunction(latex_get_filename_component)
 # Functions that perform processing during a LaTeX build.
 #############################################################################
 function(latex_execute_latex)
-  if(NOT LATEX_TARGET)
-    message(SEND_ERROR "Need to define LATEX_TARGET")
-  endif()
-
   if(NOT LATEX_WORKING_DIRECTORY)
     message(SEND_ERROR "Need to define LATEX_WORKING_DIRECTORY")
   endif()
@@ -438,11 +466,15 @@ function(latex_execute_latex)
     message(SEND_ERROR "Need to define LATEX_OUTPUT_FILE")
   endif()
 
+  if(NOT LATEX_LOG_FILE)
+    message(SEND_ERROR "Need to define LATEX_LOG_FILE")
+  endif()
+
   set(full_command_original "${LATEX_FULL_COMMAND}")
 
   # Chose the native method for parsing command arguments. Newer versions of
   # CMake allow you to just use NATIVE_COMMAND.
-  if (CMAKE_VERSION VERSION_GREATER_EQUAL 3.9)
+  if (CMAKE_VERSION VERSION_GREATER 3.8)
     set(separate_arguments_mode NATIVE_COMMAND)
   else()
     if (WIN32)
@@ -457,12 +489,14 @@ function(latex_execute_latex)
   # we also want to make sure that we strip out any escape characters that can
   # foul up the WORKING_DIRECTORY argument.
   separate_arguments(LATEX_FULL_COMMAND UNIX_COMMAND "${LATEX_FULL_COMMAND}")
-  separate_arguments(LATEX_WORKING_DIRECTORY UNIX_COMMAND "${LATEX_WORKING_DIRECTORY}")
+  separate_arguments(LATEX_WORKING_DIRECTORY_SEP UNIX_COMMAND "${LATEX_WORKING_DIRECTORY}")
 
   execute_process(
     COMMAND ${LATEX_FULL_COMMAND}
-    WORKING_DIRECTORY ${LATEX_WORKING_DIRECTORY}
+    WORKING_DIRECTORY "${LATEX_WORKING_DIRECTORY_SEP}"
     RESULT_VARIABLE execute_result
+    OUTPUT_VARIABLE ignore
+    ERROR_VARIABLE ignore
     )
 
   if(NOT ${execute_result} EQUAL 0)
@@ -473,10 +507,9 @@ function(latex_execute_latex)
     message("\n\nLaTeX command failed")
     message("${full_command_original}")
     message("Log output:")
-    file(READ ${LATEX_WORKING_DIRECTORY}/${LATEX_TARGET}.log log_output)
+    file(READ "${LATEX_WORKING_DIRECTORY}/${LATEX_LOG_FILE}" log_output)
     message("${log_output}")
-    message(FATAL_ERROR
-      "Successfully executed LaTeX, but LaTeX returned an error.")
+    message(FATAL_ERROR "Executed LaTeX, but LaTeX returned an error.")
   endif()
 endfunction(latex_execute_latex)
 
@@ -675,6 +708,8 @@ function(latex_correct_synctex)
   if(NOT LATEX_BINARY_DIRECTORY)
     message(SEND_ERROR "Need to define LATEX_BINARY_DIRECTORY")
   endif()
+  message("${LATEX_BINARY_DIRECTORY}")
+  message("${LATEX_SOURCE_DIRECTORY}")
 
   set(synctex_file ${LATEX_BINARY_DIRECTORY}/${LATEX_TARGET}.synctex)
   set(synctex_file_gz ${synctex_file}.gz)
@@ -692,13 +727,24 @@ function(latex_correct_synctex)
     message("Reading synctex file.")
     file(READ ${synctex_file} synctex_data)
 
-    message("Replacing relative with absolute paths.")
-    string(REGEX REPLACE
-      "(Input:[0-9]+:)([^/\n][^\n]*)"
-      "\\1${LATEX_SOURCE_DIRECTORY}/\\2"
-      synctex_data
-      "${synctex_data}"
-      )
+    message("Replacing output paths with input paths.")
+    foreach(extension tex cls bst clo sty ist fd)
+      # Relative paths
+      string(REGEX REPLACE
+        "(Input:[0-9]+:)([^/\n][^\n]\\.${extension}*)"
+        "\\1${LATEX_SOURCE_DIRECTORY}/\\2"
+        synctex_data
+        "${synctex_data}"
+        )
+
+      # Absolute paths
+      string(REGEX REPLACE
+        "(Input:[0-9]+:)${LATEX_BINARY_DIRECTORY}([^\n]*\\.${extension})"
+        "\\1${LATEX_SOURCE_DIRECTORY}\\2"
+        synctex_data
+        "${synctex_data}"
+        )
+    endforeach(extension)
 
     message("Writing synctex file.")
     file(WRITE ${synctex_file} "${synctex_data}")
@@ -717,6 +763,39 @@ function(latex_correct_synctex)
 endfunction(latex_correct_synctex)
 
 function(latex_check_important_warnings)
+  # Check for biber warnings/errors if that was run
+  set(bib_log_file ${LATEX_TARGET}.blg)
+  if(EXISTS ${bib_log_file})
+    file(READ ${bib_log_file} bib_log)
+    if(bib_log MATCHES "INFO - This is Biber")
+      message("\nChecking ${bib_log_file} for Biber warnings/errors.")
+
+      string(REGEX MATCHALL
+        "[A-Z]+ - [^\n]*"
+        biber_messages
+        "${bib_log}")
+
+      set(found_error)
+      foreach(message ${biber_messages})
+        if(NOT message MATCHES  "^INFO - ")
+          set(found_error TRUE)
+          message("${message}")
+        endif()
+      endforeach(message)
+
+      if(found_error)
+        latex_get_filename_component(log_file_path ${bib_log_file} ABSOLUTE)
+        message("\nConsult ${log_file_path} for more information on Biber output.")
+      else()
+        message("No known important Biber output found.")
+      endif(found_error)
+    else() # Biber output not in log file
+      message("Skipping biber checks (biber not used)")
+    endif()
+  else() # No bib log file
+    message("Skipping bibliography checks (not run)")
+  endif()
+
   set(log_file ${LATEX_TARGET}.log)
 
   message("\nChecking ${log_file} for important warnings.")
@@ -733,15 +812,15 @@ function(latex_check_important_warnings)
 
   file(READ ${log_file} log)
 
-  # Check for undefined references
+  # Check for declared LaTeX warnings
   string(REGEX MATCHALL
-    "\n[^\n]*Reference[^\n]*undefined[^\n]*"
-    reference_warnings
+    "\nLaTeX Warning:[^\n]*"
+    latex_warnings
     "${log}")
-  if(reference_warnings)
+  if(latex_warnings)
     set(found_error TRUE)
-    message("\nFound missing reference warnings.")
-    foreach(warning ${reference_warnings})
+    message("\nFound declared LaTeX warnings.")
+    foreach(warning ${latex_warnings})
       string(STRIP "${warning}" warning_no_newline)
       message("${warning_no_newline}")
     endforeach(warning)
@@ -1239,19 +1318,23 @@ function(latex_process_images dvi_outputs_var pdf_outputs_var)
       make_directory("${path}")
 
       # Do conversions for dvi.
-      latex_convert_image(output_files "${file}" .eps "${convert_flags}"
-        "${LATEX_DVI_IMAGE_EXTENSIONS}" "${ARGN}")
-      list(APPEND dvi_outputs ${output_files})
+      if(NOT LATEX_FORCE_PDF)
+          latex_convert_image(output_files "${file}" .eps "${convert_flags}"
+            "${LATEX_DVI_IMAGE_EXTENSIONS}" "${ARGN}")
+          list(APPEND dvi_outputs ${output_files})
+      endif ()
 
       # Do conversions for pdf.
-      if(is_raster)
-        latex_convert_image(output_files "${file}" .png "${convert_flags}"
-          "${LATEX_PDF_IMAGE_EXTENSIONS}" "${ARGN}")
-        list(APPEND pdf_outputs ${output_files})
-      else()
-        latex_convert_image(output_files "${file}" .pdf "${convert_flags}"
-          "${LATEX_PDF_IMAGE_EXTENSIONS}" "${ARGN}")
-        list(APPEND pdf_outputs ${output_files})
+      if(NOT LATEX_FORCE_DVI AND NOT LATEX_FORCE_HTML)
+        if(is_raster)
+          latex_convert_image(output_files "${file}" .png "${convert_flags}"
+            "${LATEX_PDF_IMAGE_EXTENSIONS}" "${ARGN}")
+          list(APPEND pdf_outputs ${output_files})
+        else()
+          latex_convert_image(output_files "${file}" .pdf "${convert_flags}"
+            "${LATEX_PDF_IMAGE_EXTENSIONS}" "${ARGN}")
+          list(APPEND pdf_outputs ${output_files})
+        endif()
       endif()
     else()
       message(WARNING "Could not find file ${CMAKE_CURRENT_SOURCE_DIR}/${file}.  Are you sure you gave relative paths to IMAGES?")
@@ -1349,6 +1432,7 @@ function(parse_add_latex_arguments command latex_main_input)
     CONFIGURE
     DEPENDS
     INDEX_NAMES
+    INCLUDE_DIRECTORIES
     )
   cmake_parse_arguments(
     LATEX "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
@@ -1407,10 +1491,10 @@ function(add_latex_targets_internal)
     set(latex_build_command
       ${CMAKE_COMMAND}
         -D LATEX_BUILD_COMMAND=execute_latex
-        -D LATEX_TARGET=${LATEX_TARGET}
         -D LATEX_WORKING_DIRECTORY="${output_dir}"
         -D LATEX_FULL_COMMAND="${latex_build_command}"
         -D LATEX_OUTPUT_FILE="${LATEX_TARGET}.dvi"
+        -D LATEX_LOG_FILE="${LATEX_TARGET}.log"
         -P "${LATEX_USE_LATEX_LOCATION}"
       )
   endif()
@@ -1423,14 +1507,39 @@ function(add_latex_targets_internal)
     set(pdflatex_build_command
       ${CMAKE_COMMAND}
         -D LATEX_BUILD_COMMAND=execute_latex
-        -D LATEX_TARGET=${LATEX_TARGET}
         -D LATEX_WORKING_DIRECTORY="${output_dir}"
         -D LATEX_FULL_COMMAND="${pdflatex_build_command}"
         -D LATEX_OUTPUT_FILE="${LATEX_TARGET}.pdf"
+        -D LATEX_LOG_FILE="${LATEX_TARGET}.log"
         -P "${LATEX_USE_LATEX_LOCATION}"
       )
   endif()
 
+  if(LATEX_INCLUDE_DIRECTORIES)
+    # The include directories needs to start with the build directory so
+    # that the copied files can be found. It also needs to end with an
+    # empty directory so that the standard system directories are included
+    # after any specified.
+    set(LATEX_INCLUDE_DIRECTORIES . ${LATEX_INCLUDE_DIRECTORIES} "")
+
+    # CMake separates items in a list with a semicolon. Lists of
+    # directories on most systems are separated by colons, so we can do a
+    # simple text replace. On Windows, directories are separated by
+    # semicolons, but we replace them with the $<SEMICOLON> generator
+    # expression to make sure CMake treats it as a single string.
+    if(CMAKE_HOST_WIN32)
+      string(REPLACE ";" "$<SEMICOLON>" TEXINPUTS "${LATEX_INCLUDE_DIRECTORIES}")
+    else()
+      string(REPLACE ";" ":" TEXINPUTS "${LATEX_INCLUDE_DIRECTORIES}")
+    endif()
+
+    # Set the TEXINPUTS environment variable
+    set(latex_build_command
+      ${CMAKE_COMMAND} -E env TEXINPUTS=${TEXINPUTS} ${latex_build_command})
+    set(pdflatex_build_command
+      ${CMAKE_COMMAND} -E env TEXINPUTS=${TEXINPUTS} ${pdflatex_build_command})
+  endif()
+
   if(NOT LATEX_TARGET_NAME)
     # Use the main filename (minus the .tex) as the target name. Remove any
     # spaces since CMake cannot have spaces in its target names.
@@ -1578,17 +1687,30 @@ function(add_latex_targets_internal)
   endif()
 
   if(LATEX_BIBFILES)
+    set(suppress_bib_output)
     if(LATEX_USE_BIBLATEX)
       if(NOT BIBER_COMPILER)
         message(SEND_ERROR "I need the biber command.")
       endif()
       set(bib_compiler ${BIBER_COMPILER})
       set(bib_compiler_flags ${BIBER_COMPILER_ARGS})
+
+      if(NOT BIBER_COMPILER_ARGS MATCHES ".*-q.*")
+        # Only suppress bib output if the quiet option is not specified.
+        set(suppress_bib_output TRUE)
+      endif()
+
+      if(LATEX_USE_BIBLATEX_CONFIG)
+        list(APPEND auxiliary_clean_files ${output_dir}/biblatex.cfg)
+        list(APPEND make_dvi_depends ${output_dir}/biblatex.cfg)
+        list(APPEND make_pdf_depends ${output_dir}/biblatex.cfg)
+      endif()
     else()
       set(bib_compiler ${BIBTEX_COMPILER})
       set(bib_compiler_flags ${BIBTEX_COMPILER_ARGS})
     endif() 
     if(LATEX_MULTIBIB_NEWCITES)
+      # Suppressed bib output currently not supported for multibib
       foreach (multibib_auxfile ${LATEX_MULTIBIB_NEWCITES})
         latex_get_filename_component(multibib_target ${multibib_auxfile} NAME_WE)
         set(make_dvi_command ${make_dvi_command}
@@ -1601,12 +1723,25 @@ function(add_latex_targets_internal)
           ${output_dir}/${multibib_target}.aux)
       endforeach (multibib_auxfile ${LATEX_MULTIBIB_NEWCITES})
     else()
+      set(full_bib_command
+        ${bib_compiler} ${bib_compiler_flags} ${LATEX_TARGET})
+      if(suppress_bib_output)
+        set(full_bib_command
+          ${CMAKE_COMMAND}
+          -D LATEX_BUILD_COMMAND=execute_latex
+          -D LATEX_WORKING_DIRECTORY="${output_dir}"
+          -D LATEX_FULL_COMMAND="${full_bib_command}"
+          -D LATEX_OUTPUT_FILE="${LATEX_TARGET}.bbl"
+          -D LATEX_LOG_FILE="${LATEX_TARGET}.blg"
+          -P "${LATEX_USE_LATEX_LOCATION}"
+          )
+      endif()
       set(make_dvi_command ${make_dvi_command}
         COMMAND ${CMAKE_COMMAND} -E chdir ${output_dir}
-        ${bib_compiler} ${bib_compiler_flags} ${LATEX_TARGET})
+        ${full_bib_command})
       set(make_pdf_command ${make_pdf_command}
         COMMAND ${CMAKE_COMMAND} -E chdir ${output_dir}
-        ${bib_compiler} ${bib_compiler_flags} ${LATEX_TARGET})
+        ${full_bib_command})
     endif()
 
     foreach (bibfile ${LATEX_BIBFILES})
@@ -1876,6 +2011,11 @@ function(add_latex_document latex_main_input)
       latex_copy_input_file(${bib_file})
     endforeach (bib_file)
 
+    if (LATEX_USE_BIBLATEX AND EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/biblatex.cfg)
+      latex_copy_input_file(biblatex.cfg)
+      set(LATEX_USE_BIBLATEX_CONFIG TRUE)
+    endif()
+
     foreach (input ${LATEX_INPUTS})
       latex_copy_input_file(${input})
     endforeach(input)

UseLATEX.tex

@@ -2,7 +2,7 @@
 
 \documentclass{article}
 
-\newcommand{\UseLATEXVersion}{2.4.5}
+\newcommand{\UseLATEXVersion}{2.7.0}
 \newcommand{\SANDNumber}{SAND 2008-2743P}
 
 % This wonderful package allows hyphenation in tt fonts and hyphenation of
@@ -88,6 +88,8 @@
   \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}
 
   %-----------------------------------------------------------------------------
@@ -734,11 +736,8 @@ add_latex_document(doc.tex TARGET_NAME MyDoc1)
   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)
@@ -751,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}
@@ -1275,6 +1301,7 @@ my.image.pdf to something like my-image.pdf.
   \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.

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