l3build (13sep17)

git-svn-id: svn://tug.org/texlive/trunk@45283 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 31 insertions, 4 deletions

diff --git a/Master/texmf-dist/source/latex/l3build/l3build.dtx b/Master/texmf-dist/source/latex/l3build/l3build.dtx
index a6e5471899e..5a7e4a6e735 100644
--- a/Master/texmf-dist/source/latex/l3build/l3build.dtx
+++ b/Master/texmf-dist/source/latex/l3build/l3build.dtx
@@ -88,6 +88,7 @@
 \luavarset{textfiles}         {\{"*.md", "*.txt"\}}{Plain text files to send to CTAN as-is.}
 \luavarset{typesetdemofiles}  {\{~\}}       {Files to typeset before the documentation (as demos), but where the PDF results are not included in the release.}
 \luavarset{typesetfiles}      {\{"*.dtx"\}} {Files to typeset for documentation.}
+\luavarset{docfiledir}        {maindir}{Where to look for the |typesetfiles| and |typesetsourcefiles|.}
 \luavarset{typesetsuppfiles}  {\{~\}}       {Files needed to support typesetting when \enquote{sandboxed}.}
 \luavarset{typesetsourcefiles}{\{~\}}       {Files to copy to unpacking when typesetting.}
 \luavarset{unpackfiles}       {\{"*.ins"\}} {Files to run to perform unpacking.}
@@ -136,6 +137,9 @@
 \luavarset{makeindexexe} {"makeindex"}{MakeIndex executable}
 \luavarset{makeindexopts}{""}         {MakeIndex options}
 \luavarseparator
+\luavarset{forcecheckepoch}{"true"}    {Force epoch when running tests}
+\luavarset{forcedocepoch}  {"false"}   {Force epoch when typesetting}
+\luavarseparator
 \luavarset{asciiengines}{\{"pdftex"\}}{Engines which should log as sure ASCII}
 \luavarset{checkruns}   {1}           {How many times to run a check file before comparing the log.}
 \luavarset{epoch}       {1463734800}  {Epoch (Unix date) to set for test runs.}
@@ -144,6 +148,7 @@
 \luavarset{scriptname}  {"build.lua"} {Name of script used in dependencies.}
 \luavarset{typesetcmds} {""}          {Instructions to be passed to \TeX{} when doing typesetting.}
 \luavarset{versionform} {""}          {Nature of version strings for auto-replacement.}
+\luavarset{recordstatus} {false}      {Include error level(s) from test run(s) in TLG files?}
 }
 \allluavars
 \newcommand\luavartypeset{%
@@ -203,7 +208,7 @@
 %    }^^A
 % }
 %
-% \date{Released 2017/07/01}
+% \date{Released 2017/09/12}
 %
 % \maketitle
 % \tableofcontents
@@ -471,6 +476,12 @@
 %
 % If the \texttt{--engine} (or \texttt{-e}) is specified (one of |pdftex|, |xetex|, or |luatex|), the saved output is stored in \texttt{\meta{name}.\meta{engine}.tlg}. This is necessary if running the test through a different engine produces a different output.
 % A normalisation process is performed when checking to avoid common differences such as register allocation; full details are listed in section~\ref{sec:norm}.
+%
+% If the \var{recordstatus} variable is set \var{true}, additional information
+% will be added to the \texttt{.tlg} to record the \enquote{exit status} of the
+% typesetting compilation of the \texttt{.lvt} file. If the typesetting compilation
+% completed without throwing an error (due to \TeX\ programming errors, for example),
+% the \enquote{exit status} is zero, else non-zero.
 % \end{buildcmd}
 %
 % \begin{buildcmd}{save -p \meta{name(s)}}
@@ -966,6 +977,18 @@
 %   \label{fig:test-tasks}
 % \end{figure}
 %
+% \subsection{Epoch setting}
+%
+% To produce predictable output when suing dates, the test system offers the
+% ability to set the epoch to a known value. The \luavar{epoch} variable may
+% be given as a raw value (a simple integer) or as a date in ISO format.
+% The two flags \luavar{forcecheckepoch} and \luavar{forcedocepoch} then
+% determine whether this is applied in testing and typesetting, respectively.
+%
+% The epoch may also be given as a command line option, |-E|, which again
+% takes either a date or raw epoch. When given, this will automatically
+% activate forcing of the epoch in both testing and typesetting.
+%
 % \section{Alternative test formats}
 %
 % \subsection{Generating test files with \pkg{DocStrip}}
@@ -1163,7 +1186,7 @@
 %       \var{pdf}         & Boolean \\
 %       \var{quiet}       & Boolean \\
 %       \var{rerun}       & Boolean \\
-%       \var{testfiledir} & String  \\
+%       \var{testfiledir} & Table   \\
 %       \var{version}     & String  \\
 %     \bottomrule
 %     \end{tabular}
@@ -1347,11 +1370,14 @@
 %
 % \begin{function}{call()}
 %   \begin{syntax}
-%     |call(|\meta{dirs}, \meta{target}|)|
+%     |call(|\meta{dirs}, \meta{target}, \oarg{options}|)|
 %   \end{syntax}
 %   Runs the \texttt{l3build} \meta{target} (a string) for each directory in the
 %   \meta{dirs} (a table). This will pass command line options for the parent
-%   script to the child processes.
+%   script to the child processes. The \meta{options} table should take the
+%   same form as the global \meta{options}, described above. If it is
+%   absent then the global list is used. Note that any entry for the
+%   |target| in this table is ignored.
 % \end{function}
 %
 % \end{documentation}
@@ -1444,6 +1470,7 @@
 }
 \let\TYPE\LONGTYPEOUT
 %    \end{macrocode}
+% \end{macro}
 %
 % \begin{macro}{\STARTMESSAGE, \START}
 %   Start the test, after the optional |\documentclass|