Fix latex issues via value added scripts

.decent_ci-Linux.yaml

@@ -6,7 +6,7 @@ compilers:
      - "TGZ"
      - "IFW"
     release_build_cmake_extra_flags: -DENABLE_REGRESSION_TESTING:BOOL=ON -DBUILD_DOCS:BOOL=ON
-    cmake_extra_flags: -DLINK_WITH_PYTHON=ON -DBUILD_DOCS:BOOL=ON -DTEX_INTERACTION="nonstopmode" -DBUILD_FORTRAN=ON -DBUILD_PACKAGE:BOOL=ON -DBUILD_TESTING:BOOL=ON -DENABLE_REGRESSION_TESTING:BOOL=ON -DREGRESSION_BASELINE_PATH:PATH=$REGRESSION_BASELINE -DREGRESSION_SCRIPT_PATH:PATH=$REGRESSION_DIR -DREGRESSION_BASELINE_SHA:STRING=$REGRESSION_BASELINE_SHA -DCOMMIT_SHA=$COMMIT_SHA -DENABLE_GTEST_DEBUG_MODE:BOOL=OFF -DBUILD_PERFORMANCE_TESTS:BOOL=ON -DVALGRIND_ANALYZE_PERFORMANCE_TESTS:BOOL=ON
+    cmake_extra_flags: -DLINK_WITH_PYTHON=ON -DDOCUMENTATION_BUILD="BuildWithAll" -DTEX_INTERACTION="nonstopmode" -DBUILD_FORTRAN=ON -DBUILD_PACKAGE:BOOL=ON -DBUILD_TESTING:BOOL=ON -DENABLE_REGRESSION_TESTING:BOOL=ON -DREGRESSION_BASELINE_PATH:PATH=$REGRESSION_BASELINE -DREGRESSION_SCRIPT_PATH:PATH=$REGRESSION_DIR -DREGRESSION_BASELINE_SHA:STRING=$REGRESSION_BASELINE_SHA -DCOMMIT_SHA=$COMMIT_SHA -DENABLE_GTEST_DEBUG_MODE:BOOL=OFF -DBUILD_PERFORMANCE_TESTS:BOOL=ON -DVALGRIND_ANALYZE_PERFORMANCE_TESTS:BOOL=ON
     collect_performance_results: true
     s3_upload: doc/pdf
     s3_upload_bucket: energyplus

CMakeLists.txt

@@ -103,8 +103,8 @@ if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
     "MinSizeRel" "RelWithDebInfo")
 endif()
 
-# we are making *a Python 3 Interpreter* a required dependency, so find it here
-find_package(PythonInterp 3 REQUIRED)
+# we are making *a Python 3.6 Interpreter* a required dependency, so find it here
+find_package(PythonInterp 3.6 REQUIRED)
 
 if( BUILD_TESTING )
   option( ENABLE_REGRESSION_TESTING "Enable Regression Tests" OFF )
@@ -337,6 +337,7 @@ if( BUILD_PACKAGE )
 endif()
 
 if (BUILD_DOCS)
+  set(DOCS_TESTING ${BUILD_TESTING} CACHE INTERNAL "" FORCE)
   add_subdirectory(doc)
 endif()
 

doc/CMakeLists.txt

@@ -4,6 +4,13 @@ cmake_minimum_required(VERSION 3.5.1)
 
 set_property(GLOBAL PROPERTY USE_FOLDERS ON)
 
+if(NOT EXISTS ${PYTHON_EXECUTABLE})
+  # we are making *a Python 3.6 Interpreter* a required dependency, so find it here
+  find_package(PythonInterp 3.6 REQUIRED)
+endif()
+
+option( DOCS_TESTING "Test the docs for issues" OFF )
+
 # this _should_ find the xelatex compiler, but for some reason it isn't populating for me
 find_package(LATEX)
 # so we'll create a cache variable which will be available to the add_subdirectory call below
@@ -14,7 +21,7 @@ string(REPLACE pdflatex xelatex XELATEX ${PDFLATEX_COMPILER})
 set(TEX_INTERACTION "batchmode" CACHE STRING "Choose the interaction mode for TeX.")
 set_property(CACHE TEX_INTERACTION PROPERTY STRINGS "nonstopmode" "batchmode")
 if( EXISTS ${XELATEX} )
-# and if it does, just add the doc/CMakeLists commands
+  # and if it does, just add the doc/CMakeLists commands
   # let's create a folder to drop ONLY PDFs in once they are built, this will allow easy upload to s3
   file(MAKE_DIRECTORY ${PROJECT_BINARY_DIR}/pdf)
   file(COPY ${PROJECT_SOURCE_DIR}/index.html DESTINATION ${PROJECT_BINARY_DIR}/pdf)

doc/acknowledgments/src/notices-and-acknowledgments/other-software-included-or-referenced.tex

@@ -128,7 +128,7 @@ \subsection{MODELISAR Notice}\label{modelisar-notice}
 
 This file is licensed by the copyright holders under the BSD License\footnote{\url{http://www.opensource.org/licenses/bsd-license.html\textgreater}}:
 
-\begin{center}\rule{0.5\linewidth}{\linethickness}\end{center}
+\begin{center}\rule{0.5\linewidth}{0.4pt}\end{center}
 
 Redistribution and use in source and binary forms, with or withoutmodification, are permitted provided that the following conditions are met:
 

doc/cmake/doc-targets.cmake

@@ -11,5 +11,13 @@ macro( CREATE_DOC_TARGET SOURCE_FILENAME OUTPUT_FILENAME )
     )
 
   add_dependencies(docs zPDF_${OUTPUT_FILENAME})
+
   set_target_properties(zPDF_${OUTPUT_FILENAME} PROPERTIES FOLDER Documentation)
+
+  if (DOCS_TESTING)
+    add_custom_command(TARGET zPDF_${OUTPUT_FILENAME}
+      POST_BUILD
+      COMMAND ${PYTHON_EXECUTABLE} "${PROJECT_SOURCE_DIR}/tools/parse_latex_log.py" "${PROJECT_SOURCE_DIR}/${SOURCE_FILENAME}/${SOURCE_FILENAME}.log" "${PROJECT_SOURCE_DIR}/${SOURCE_FILENAME}" "${PROJECT_BINARY_DIR}/${OUTPUT_FILENAME}_errors.json"
+      )
+  endif()
 endmacro()

doc/engineering-reference/src/climate-sky-and-solar-shading-calculations/climate-calculations.tex

@@ -76,7 +76,7 @@ \subsection{Sky Radiation Modeling}\label{sky-radiation-modeling}
 \begin{table}[hbtp]
 \centering
 \begin{tabular}{cl}
-\textbf{Author}   & \epsilon_{sky, clear} \\ \\
+\textbf{Author}   & $\epsilon_{sky, clear}$ \\ \\
 Clark \& Allen    & $= 0.787 + 0.764 \ln\left(T_{dp}/273\right)$ \\ \\
 Martin \& Berdahl & $= 0.758 + 0.521 \left(T_{dp}/100\right) + 0.625  \left(T_{dp} / 100\right)^2$ \\ \\
 Brunt             & $= 0.618 + 0.056 \left(P_{wv}\right)^{0.5}$ \\ \\
@@ -111,10 +111,10 @@ \subsection{Sky Radiation Modeling}\label{sky-radiation-modeling}
 \noindent Example:
 \newline
 
-Clear sky ($N=0$), $T_{db} = 20 + 273.15 = \SI{293.15}{\kelivin}$, $T_{dp} = 10 + 273.15 = \SI{283.15}{\kelvin}$
+Clear sky ($N=0$), $T_{db} = 20 + 273.15 = \SI{293.15}{\kelvin}$, $T_{dp} = 10 + 273.15 = \SI{283.15}{\kelvin}$
 \newline
 
-$\epsilon_{sky} = \left(0.787 + 0.764  \ln\left(283.15/273\right)\right)  \left(1 + 0.0224  N - 0.0035  N^2 + 0.00028  N^3) = 0.815$
+$\epsilon_{sky} = \left(0.787 + 0.764  \ln\left(283.15/273\right)\right)  \left(1 + 0.0224  N - 0.0035  N^2 + 0.00028  N^3 \right) = 0.815$
 \newline
 
 $IR_H = 0.815  5.6697E-8  293.15^4 = \SI{341.2}{\watt\per\meter\squared}$

doc/engineering-reference/src/climate-sky-and-solar-shading-calculations/shading-module.tex

@@ -173,8 +173,8 @@ \subsection{Shadow Projection}\label{shadow-projection}
 \begin{enumerate}
     \item Polygon Clipping: The shadow algorithm is based on coordinate transformation methods similar to Groth and Lokmanhekim and the shadow overlap method of Walton.
     \item Pixel Counting: GPU-rendering based calculations based on the method developed by Jones et al 2011.
-    \item Scheduled: Pre-calculated sunlit fractions are input through a schedule in the \textbf{\hyperref[surfacePropertylocalEnvironment]{SurfaceProperty:LocalEnvironment}} object.
-    \item Imported: Pre-calculated sunlit fractions are input through a \textbf{\hyperref[schedulefileshading]{Schedule:File:Shading}} object.
+    \item Scheduled: Pre-calculated sunlit fractions are input through a schedule in the \textbf{SurfaceProperty:LocalEnvironment} object.
+    \item Imported: Pre-calculated sunlit fractions are input through a \textbf{Schedule:File:Shading} object.
 \end{enumerate}
 
 \subsection{Polygon Clipping}

doc/engineering-reference/src/daylighting-and-window-calculations/time-step-daylighting-calculation.tex

@@ -196,23 +196,23 @@ \subsection{Interior Illuminance}\label{interior-illuminance}
 The total illuminance at a reference point from all of the exterior windows in a zone is
 
 \begin{equation}
-  {I_{tot}}({i_L}) = \sum\limits_{\scriptstyle{\rm{windows}}\atop\scriptstyle{\rm{in~zone}}} {{I_{win}}({i_s},{i_L})}
+  {I_{tot}}({i_L}) = \sum\limits_{\genfrac{}{}{0pt}{2}{\rm{windows}}{\rm{in~zone}}} {{I_{win}}({i_s},{i_L})}
 \end{equation}
 
 where i\(_{S}\) = 1 if the window is unshaded and \emph{i\(_{S}\)} = 2 if the window is shaded that time step. (Before the illuminance calculation is done the window shading control will have been simulated to determine whether or not the window is shaded.)
 
 Similarly, the total background luminance is calculated:
 
 \begin{equation}
-{B_{tot}}({i_L}) = \sum\limits_{\scriptstyle{\rm{windows}}\atop\scriptstyle{\rm{in~zone}}} {{B_{win}}({i_s},{i_L})}
+  {B_{tot}}({i_L}) = \sum\limits_{\genfrac{}{}{0pt}{2}{\rm{windows}}{\rm{in~zone}}} {{B_{win}}({i_s},{i_L})}
 \end{equation}
 
 \subsection{Glare Index}\label{glare-index-000}
 
 The net glare index at each reference point is calculated as:
 
 \begin{equation}
-{G_I}({i_L}) = 10{\log_{10}}\sum\limits_{\scriptstyle{\rm{windows}}\atop\scriptstyle{\rm{in zone}}} {\frac{{{S_{win}}{{({i_L},{i_S})}^{1.6}}\Omega {{({i_L})}^{0.8}}}}{{B({i_L}) + 0.07\omega {{({i_L})}^{0.5}}{S_{win}}({i_L},{i_S})}}}
+  {G_I}({i_L}) = 10{\log_{10}}\sum\limits_{\genfrac{}{}{0pt}{2}{\rm{windows}}{\rm{in~zone}}} {\frac{{{S_{win}}{{({i_L},{i_S})}^{1.6}}\Omega {{({i_L})}^{0.8}}}}{{B({i_L}) + 0.07\omega {{({i_L})}^{0.5}}{S_{win}}({i_L},{i_S})}}}
 \end{equation}
 
 where

doc/engineering-reference/src/demand-limiting.tex

@@ -19,7 +19,7 @@ \chapter{Demand Limiting}\label{demand-limiting}
 
 The demand limiting controls implemented in EnergyPlus are intended to allow some of the more common demand limiting strategies.~ The DemandManagerAssignmentList object is a high level control that makes demand limiting decisions based on a list of possible demand limiting strategies.~ Each demand limiting strategy is described in a separate DemandManager object.~ Each DemandManager object controls a group of similar load objects of the same type, such as DemandManager:Lights, DemandManager:ElectricEquipment, DemandManager:Thermostats, or DemandManager:Ventilation objects.
 
-\subsection{Algorithm}\label{algorithm}
+\section{Algorithm}\label{algorithm}
 
 In EnergyPlus the DemandManagerAssignmentList and DemandManager objects are simulated by the Demand Manager module.~ The Demand Manager is built into the overall solution method for the program.~ For each zone time step, the program executes three major segments of code:
 
@@ -60,7 +60,7 @@ \subsection{Algorithm}\label{algorithm}
 
 All demand limiting controls are disabled during warmup days and sizing runs.
 
-\subsubsection{Sequential Priority}\label{sequential-priority}
+\subsection{Sequential Priority}\label{sequential-priority}
 
 If the \emph{Demand Manager Priority} field of the DemandManagerAssignmentList object is set to SEQUENTIAL, each DemandManager in the list is activated in sequence from first to last until demand is reduced below the limit or until all managers are activated.~ A DemandManager is skipped if it cannot reduce the demand.~ Possible reasons that a manager cannot reduce demand include:
 
@@ -77,6 +77,6 @@ \subsubsection{Sequential Priority}\label{sequential-priority}
 
 The implication of sequential priority is that a DemandManagerAssignmentList with many DemandManagers may make many passes through the Demand Manager before all demand limiting decisions are finalized.~ Each pass requires an additional resimulation of the current time step.~ In some cases this could significantly slow down the overall simulation runtime.~ The use of the \emph{Minimum Limit Duration} field can help to ensure that not every DemandManager is being activated at every time step.
 
-\subsubsection{All Priority}\label{all-priority}
+\subsection{All Priority}\label{all-priority}
 
 If the \emph{Demand Manager Priority} field of the DemandManagerAssignmentList object is set to ALL, all DemandManagers in the list are activated simultaneously to achieve the maximum demand reduction.~ This priority option requires only one final resimulation after all DemandManagers are activated.

doc/engineering-reference/src/simulation-models-encyclopedic-reference-001/coils.tex

@@ -1611,38 +1611,38 @@ \subsubsection{Special Calculations for Coil:Cooling:DX:TwoStageWithHumidityCont
 
 1. No latent control
 
-   Perform normal operation with SHR_{Normal}
+   Perform normal operation with SHR\(_{Normal}\)
 
 2. Latent control
 
-a.  If CoilSHR >= SHR_{Normal}
+a.  If CoilSHR >= SHR\(_{Normal}\)
 
    Perform normal operation to meet sensible load, adjusted by PLR for a single capacity equipmentl
 
 	SenLoad = SenOut * PLR
 
-b.  Else if (SHR_{Normal} > CoilSHR And CoilSHR >= SHR_{Sub})
+b.  Else if SHR\(_{Normal}\) > CoilSHR And CoilSHR >= SHR\(_{Sub}\)
 
    Perform combination between normal and subcooling operation
 
-	CoilSHR = SHR_{Sub} * r_{Sub} + SHR_{Normal} * (1 - r_{Sub})
+  CoilSHR = SHR\(_{Sub}\) * r\(_{Sub}\) + SHR\(_{Normal}\) * (1 - r\(_{Sub})\)
 
-	SenLoad = [SenOut_{Sub} * r_{Sub} + SenOut_{Normal} * (1 - r_{Sub})] * PLR
+  SenLoad = [SenOut\(_{Sub}\) * r\(_{Sub}\) + SenOut\(_{Normal}\) * (1 - r\(_{Sub}\))] * PLR
 
-c.  Else if (SHR_{Sub} > CoilSHR And CoilSHR >= SHR_{Reheat})
+c.  Else if SHR\(_{Sub}\) > CoilSHR And CoilSHR >= SHR\(_{Reheat}\)
 
    Perform combination between normal and reheat operation
 
-	CoilSHR = SHR_{Reheat} * r_{Reheat} + SHR_{Normal} * (1 - r_{Sub})
+  CoilSHR = SHR\(_{Reheat}\) * r\(_{Reheat}\) + SHR\(_{Normal}\) * (1 - r\(_{Sub}\))
 
-	SenLoad = [SenOut_{Sub} * r_{Sub} + SenOut_{Normal} * (1 - r_{Sub})] * PLR
+  SenLoad = [SenOut\(_{Sub}\) * r\(_{Sub}\) + SenOut\(_{Normal}\) * (1 - r\(_{Sub}\))] * PLR
 
 
 Else
 
     Performreheatg operation
 
-    SenLoad = SenOut_{Reheat} * PLR
+    SenLoad = SenOut\(_{Reheat}\) * PLR
 
 End If
 
@@ -5190,7 +5190,7 @@ \subsubsection{Model Description}\label{model-description-7}
 The temperature of the water leaving the desuperheater is then calculated as
 
 \begin{equation}
-{T_{water,outlet}} = {T_{water,inlet}} + \frac{{{Q_{coil}}}}{{{{\dot m}_{water}}\cdot {C_{p,water}}}} ~for~ {\dot m_{water}} \textgreater{} 0
+{T_{water,outlet}} = {T_{water,inlet}} + \frac{{{Q_{coil}}}}{{{{\dot m}_{water}}\cdot {C_{p,water}}}} ~for~ {\dot m_{water}} > 0
 \end{equation}
 
 \begin{equation}

doc/engineering-reference/src/simulation-models-encyclopedic-reference-002/heat-exchangers.tex

@@ -1224,7 +1224,7 @@ \subsubsection{Model Simplifications for Computational Efficiency}\label{model-s
 
 \begin{figure}[htbp]
 \centering
-\includegraphics{media/image8001.png}
+\includegraphics[width=0.5\textwidth]{media/image8001.png}
 \caption{Schematic of first and second improvements to the algorithm for computational efficiency \protect \label{fig:slinky-first-and-second-improvements}}
 \end{figure}
 

doc/engineering-reference/src/simulation-models-encyclopedic-reference-004/refrigeration-equipment.tex

@@ -1965,7 +1965,7 @@ \subsubsection{Secondary Loop Pumping Power and Secondary Loop Load}\label{secon
 
 The needed flow rate is used to determine the number of pumps required and the total pumping power, which produces a new estimate for the total load. A few iterations converge upon the final secondary loop load for each time step.~ The total load on the heat exchanger is therefore the sum of the refrigeration loads, any pipe heat gains, and the portion of the pump power that is absorbed by the circulating fluid.
 
-\subsection{Transcritical CO\(_{2}\) Refrigeration System}\label{transcritical-co2-refrigeration-system}
+\subsection{Transcritical CO\texorpdfstring{\(_{2}\)}{2} Refrigeration System}\label{transcritical-co2-refrigeration-system}
 
 The Refrigeration:TranscriticalSystem object allows users to model detailed transcritical carbon dioxide (CO\(_{2}\)) booster refrigeration systems used in supermarkets.~ The object allows for modeling either a single stage system with medium-temperature loads or a two stage system with both medium- and low-temperature loads.
 

doc/engineering-reference/src/simulation-models-encyclopedic-reference-005/water-systems.tex

@@ -493,7 +493,7 @@ \subsubsection{Calculate Connections Heat Recovery}\label{calculate-connections-
 \end{equation}
 
 \begin{equation}
-\varepsilon = \frac{{1 - EXP\left( { - NTU\left( {1 - {R_c}} \right)} \right)}}{{1 - {R_c}EXP\left( { - NTU\left( {1 - {R_c}} \right)} \right)}},~if~{R_c}~\textless{}~1
+\varepsilon = \frac{{1 - EXP\left( { - NTU\left( {1 - {R_c}} \right)} \right)}}{{1 - {R_c}EXP\left( { - NTU\left( {1 - {R_c}} \right)} \right)}},~if~{R_c}~<~1
 \end{equation}
 
 For the ``crossflow'' heat exchanger:

doc/engineering-reference/src/special-modules-reporting/heat-emissions.tex

@@ -86,6 +86,11 @@ \subsection{Heat Rejection from HVAC System Equipment}\label{emission-from-HVAC-
 \toprule 
 Object Group & Component & Calculation Methods \tabularnewline
 \midrule
+\endfirsthead
+\caption{Heat Rejection Calculation for Different HVAC Component Types} \tabularnewline
+\toprule 
+Object Group & Component & Calculation Methods \tabularnewline
+\midrule
 \endhead
 Coils      & Chilled water cooling coil   & Emit heat in condensing unit defined in Condenser Equipment \tabularnewline
            & Heating coil (fuel heated)   & Fuel Consumed + Heating Coil Defrost Electric Consumption + Heating Coil Crankcase Heater Electric Consumption – Heating Coil Total Heating Energy \tabularnewline