summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2015-08-19 22:22:20 +0000
committerKarl Berry <karl@freefriends.org>2015-08-19 22:22:20 +0000
commitee32a98c12dea0596ae127c9d655041e50b8599d (patch)
treeb60dfc3adc6b3bea0f64417eb20c19f852058f23 /Master/texmf-dist/source
parent662cbab0534a510978ea4b6497b06c94258f339e (diff)
l3build (19aug15)
git-svn-id: svn://tug.org/texlive/trunk@38163 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source')
-rw-r--r--Master/texmf-dist/source/latex/l3build/l3build.dtx106
1 files changed, 86 insertions, 20 deletions
diff --git a/Master/texmf-dist/source/latex/l3build/l3build.dtx b/Master/texmf-dist/source/latex/l3build/l3build.dtx
index 780134c0efb..e3f49bc1bbd 100644
--- a/Master/texmf-dist/source/latex/l3build/l3build.dtx
+++ b/Master/texmf-dist/source/latex/l3build/l3build.dtx
@@ -39,8 +39,8 @@
\RequirePackage{expl3}
\def\ExplFileName{l3build}
\def\ExplFileDescription{L3 Regression test suite}
-\def\ExplFileDate{2015/07/28}
-\def\ExplFileVersion{5704}
+\def\ExplFileDate{2015/08/18}
+\def\ExplFileVersion{5866}
\documentclass[full]{l3doc}
\renewcommand\partname{Part}
\usepackage{multicol,needspace}
@@ -114,6 +114,7 @@
\luavarseparator
\luavarset{lvtext} {".lvt"} {Extension of test files.}
\luavarset{tlgext} {".tlg"} {Extension of test file output.}
+\luavarset{lvtext} {".lve"} {Extension of auto-generating test file output.}
\luavarset{logext} {".log"} {Extension of checking output, before processing it into a \texttt{.tlg}.}
\luavarseparator
\luavarset{checkdeps} {\{~\}} {List of build unpack dependencies for checking.}
@@ -298,14 +299,23 @@
% In the working directory of a bundle or module, the following commands can be executed:
% \begin{itemize}[noitemsep]\ttfamily
% \item check
-% \item check \meta{name} [\meta{engine}]
+% \item check \meta{name(s)}
% \item cmdcheck
% \item clean
% \item doc
% \item install
-% \item save \meta{name} [\meta{engine}]
+% \item save \meta{name(s)}
% \end{itemize}
% These commands are described below.
+%
+% As well as these commands, the system recognises the options
+% \begin{itemize}
+% \item \texttt{--engine} (\texttt{-e}) Sets the engine to use for
+% testing
+% \item \texttt{--halt-on-error} (\texttt{-H}) Specifies that checks
+% should stop as soon as possible, rather than running all requested
+% tests
+% \end{itemize}
%
% \begin{buildcmd}{check}
% The |check| command runs the entire test suite.
@@ -335,9 +345,11 @@
% \end{buildcmd}
%
%
-% \begin{buildcmd}{check \meta{name} [\meta{engine}]}
-% Checks only the test \texttt{\meta{name}.lvt} with optionally specified \meta{engine} (one of |pdftex|, |xetex|, or |luatex|).
-% If an \meta{engine} is not specified, all three engines are checked (or those defined by the |checkengines| variable if changed from the default).
+% \begin{buildcmd}{check \meta{name(s)}}
+% Checks only the test \texttt{\meta{name(s)}.lvt}.
+% All engines specified by \var{checkengines} are tested unless the command
+% line option \texttt{--engine} (or \texttt{-e}) has been given to limit
+% testing to a single engine.
% \end{buildcmd}
%
% \begin{buildcmd}{cmdcheck}
@@ -405,7 +417,9 @@
%
%
% \begin{buildcmd}{doc}
-% Compiles all documentation files in the \var{typesetdir} directory.
+% Compiles documentation files in the \var{typesetdir} directory.
+% In the absence of one or more file names, all documentation is typeset;
+% a file list may be given at the command line for selective typesetting.
% If the compilation is successful the |.pdf| is moved back into the main directory.
%
% The documentation compilation is performed with the \var{typesetexe} binary (default \texttt{pdflatex}), with options \var{typesetopts}.
@@ -423,12 +437,12 @@
% \end{buildcmd}
%
%
-% \begin{buildcmd}{save \meta{name} [\meta{engine}]}
-% This command runs through the same execution as |check| for a specific test \texttt{\meta{name}.lvt} with optional \texttt{\meta{engine}}.
-% If no \meta{engine} is specific, this command saves the output of the test to a |.tlg| file.
+% \begin{buildcmd}{save \meta{name(s)}}
+% This command runs through the same execution as |check| for a specific test(s) \texttt{\meta{name(s)}.lvt}.
+% This command saves the output of the test to a |.tlg| file.
% This file is then used in all subsequent checks against the \texttt{\meta{name}.lvt} test.
%
-% If the \meta{engine} 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.
+% 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}.
% \end{buildcmd}
%
@@ -631,14 +645,6 @@
% \item Conversion of low chars ($1$ to $31$) to |^^| notation.
% \end{itemize}
%
-% \subsection{Generating test files with \pkg{DocStrip}}
-%
-% It is possible to pack tests inside source files. Tests generated during the
-% unpacking process will be available to the \texttt{check} and \texttt{save}
-% commands as if they were stored in the \texttt{testfiledir}. Any explicit
-% test files inside \texttt{testfiledir} take priority over generated ones
-% with the same names.
-%
% \section{Writing test files}
% \label{sec:writing-tests}
%
@@ -834,6 +840,66 @@
% \label{fig:box-log}
% \end{figure}
%
+% \section{Alternative test formats}
+%
+% \subsection{Generating test files with \pkg{DocStrip}}
+%
+% It is possible to pack tests inside source files. Tests generated during the
+% unpacking process will be available to the \texttt{check} and \texttt{save}
+% commands as if they were stored in the \texttt{testfiledir}. Any explicit
+% test files inside \texttt{testfiledir} take priority over generated ones
+% with the same names.
+%
+% \subsection{Specifying expectations}
+%
+% Regression tests check whether changes introduced in the code modify the test
+% output. Especially while developing a complex package there is not yet a
+% baseline to save a test goal with. It might then be easier to formulate the
+% expected effects and outputs of tests directly. To achieve this, you may
+% create an \texttt{.lve} instead of a \texttt{.tlg}
+% file.\footnote{Mnemonic: \texttt{lv\textbf{t}}: \textbf{t}est,
+% \texttt{lv\textbf{e}}: \textbf{e}xpectation} It is processed exactly like
+% the \texttt{.lvt} to generate the expected outcome. The test fails when both
+% differ.
+%
+% Combining both features enables contrasting the test with its expected
+% outcome in a compact format. Listing \ref{fig:expect-dtx} exemplary tests
+% \TeX{}s counters. Listing \ref{fig:expect-ins} shows the relevant part of an
+% \texttt{.ins} file to generate it.
+%
+% \begin{figure}
+% \begin{lstlisting}[frame=single,language={TeX},gobble = 6]
+% \input regression-test.tex\relax
+% \START
+% \TEST{counter-math}{
+% %<*test>
+% \OMIT
+% \newcounter{numbers}
+% \setcounter{numbers}{2}
+% \addtocounter{numbers}{2}
+% \stepcounter{numbers}
+% \TIMO
+% \typeout{\arabic{numbers}}
+% %</test>
+% %<expect> \typeout{5}
+% }
+% \END
+% \end{lstlisting}
+% \caption{Test and expectation can be specified side-by-side in a single
+% \texttt{.dtx} file.}
+% \label{fig:expect-dtx}
+% \end{figure}
+%
+%\begin{figure}
+% \begin{lstlisting}[frame=single,language={TeX},gobble = 6]
+% \generate{\file{\jobname.lvt}{\from{\jobname.dtx}{test}}
+% \file{\jobname.lve}{\from{\jobname.dtx}{expect}}}
+% \end{lstlisting}
+% \caption{Test and expectation are generated from a \texttt{.dtx} file of
+% the same name.}
+% \label{fig:expect-ins}
+% \end{figure}
+%
% \subsection{Typesetting documentation}
%
% As part of the overall build process, \pkg{l3build} will create PDF