diff options
Diffstat (limited to 'Master/texmf-dist/source')
| -rw-r--r-- | Master/texmf-dist/source/latex/l3build/l3build.dtx | 106 |
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 |