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.

UseLATEX.cmake

@@ -1,6 +1,6 @@
 # File: UseLATEX.cmake
 # CMAKE commands to actually use the LaTeX compiler
-# Version: 2.5.0
+# 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,22 @@
 #       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
@@ -797,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)
@@ -1303,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?")
@@ -1413,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})
@@ -1495,6 +1515,31 @@ function(add_latex_targets_internal)
       )
   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.

UseLATEX.tex

@@ -2,7 +2,7 @@
 
 \documentclass{article}
 
-\newcommand{\UseLATEXVersion}{2.5.0}
+\newcommand{\UseLATEXVersion}{2.7.0}
 \newcommand{\SANDNumber}{SAND 2008-2743P}
 
 % This wonderful package allows hyphenation in tt fonts and hyphenation of
@@ -736,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)
@@ -753,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}
@@ -1277,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

@@ -90,8 +90,8 @@ fi
 
 echo -n "Extracting notes for $version..."
 version_notes=`sed -n "/# $version/,/# [0-9]/{
-/# [0-9]/d
-s/^#       //
+s/^# $version *//
+/^# [0-9]/d
 s/^# *//
 p
 }" UseLATEX.cmake`
@@ -105,6 +105,8 @@ else
     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`" ]

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.