summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3build/l3build.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3build/l3build.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3build/l3build.dtx35
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|