summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3build
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2017-07-02 21:13:29 +0000
committerKarl Berry <karl@freefriends.org>2017-07-02 21:13:29 +0000
commitefc6324a9b0ff04182c5a6683d271c43f33b28d5 (patch)
treed3f302539e594922cdff2cf47b0282212657728c /Master/texmf-dist/source/latex/l3build
parentd79b225e640990e67c41ed4a3631350e84d05a0e (diff)
l3build (2jul17)
git-svn-id: svn://tug.org/texlive/trunk@44741 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3build')
-rw-r--r--Master/texmf-dist/source/latex/l3build/l3build.dtx103
1 files changed, 75 insertions, 28 deletions
diff --git a/Master/texmf-dist/source/latex/l3build/l3build.dtx b/Master/texmf-dist/source/latex/l3build/l3build.dtx
index ee9665618c1..a6e5471899e 100644
--- a/Master/texmf-dist/source/latex/l3build/l3build.dtx
+++ b/Master/texmf-dist/source/latex/l3build/l3build.dtx
@@ -16,7 +16,7 @@
%
% The development version of the bundle can be found at
%
-% https://github.com/latex3/latex3
+% https://github.com/latex3/l3build
%
% for those people who are interested.
%
@@ -98,7 +98,7 @@
\luavarset{dviext} {".dvi"} {Extension of DVI files.}
\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{lveext} {".lve"} {Extension of auto-generating test file output.}
\luavarset{logext} {".log"} {Extension of checking output, before processing it into a \texttt{.tlg}.}
\luavarset{pdfext} {".pdf"} {Extension of PDF file for checking and saving.}
\luavarset{psext} {".ps"} {Extension of PostScript files.}
@@ -108,7 +108,7 @@
\luavarset{unpackdeps} {\{~\}} {\dots for unpacking.}
\luavarseparator
\luavarset{checkengines}{\{"pdftex", "xetex", "luatex"\}} {Engines to check with \texttt{check} by default.}
-\luavarset{stdengine} {"pdtex"} {Engine to generate \texttt{.tlg} file from.}
+\luavarset{stdengine} {"pdftex"} {Engine to generate \texttt{.tlg} file from.}
\luavarset{checkformat} {"latex"} {Format to use for tests.}
\luavarseparator
\luavarset{typesetexe} {"pdflatex"} {Executable for compiling \texttt{doc(s)}.}
@@ -203,7 +203,7 @@
% }^^A
% }
%
-% \date{Released 2017/06/25}
+% \date{Released 2017/07/01}
%
% \maketitle
% \tableofcontents
@@ -300,15 +300,18 @@
% data
% \item \texttt{--engine} (\texttt{-e}) Sets the engine to use for
% testing
+% \item \texttt{--force} (\texttt{-f}) Force checks to run even if sanity
+% checks fail, \emph{e.g.}~when \texttt{--engine} is not given in
+% \luavar{checkengines}
% \item \texttt{--halt-on-error} (\texttt{-H}) Specifies that checks
% should stop as soon as possible, rather than running all requested
% tests; the difference file is printed in the terminal directly in the case of failure
% \item \texttt{--pdf} (\texttt{-p}) Test PDF file against a reference
% version rather than using a log comparison
% \item \texttt{--quiet} (\texttt{-q}) Suppresses output from unpacking
-% \item \texttt{--release} (\texttt{-r}) Release string to use when setting
-% version data
% \item \texttt{--textfiledir} (\texttt{-t}) Select a specific set of tests
+% \item \texttt{--version} (\texttt{-v}) Version string to use when setting
+% version data
% \end{itemize}
%
% \begin{buildcmd}{check}
@@ -352,7 +355,9 @@
% 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.
+% testing to a single engine. Normally testing is preceded by unpacking
+% source files and copying the result plus any additional support to the
+% test directory: this may be skipped using the \texttt{-s} option.
% \end{buildcmd}
%
% \begin{buildcmd}{check -p}
@@ -443,7 +448,7 @@
%
% Source files specified in \var{sourcefiles} and \var{typesetsourcefiles}
% are unpacked before the typesetting takes place. (In most cases
-% \var{typesetsourcefiles} will be mepty, but may be used where there are
+% \var{typesetsourcefiles} will be empty, but may be used where there are
% files to unpack \emph{only} for typesetting.)
%
% If \var{typesetsearch} is \code{true} (default), standard \texttt{texmf} search trees are used in the typesetting compilation. If set to false, \emph{all} necessary files for compilation must be included in the |build/local| sandbox.
@@ -480,7 +485,7 @@
% \begin{buildcmd}{setversion}
% Modifies the content of files specified by |versionfiles| to allow
% automatic updating of the file date and version. The latter are
-% specified using the |-d| and |-r| command line options and if not
+% specified using the |-d| and |-v| command line options and if not
% given will default to the current date in ISO format (YYYY-MM-DD) and |-1|,
% respectively. As detailed below, the standard set up has no search pattern
% defined for this target and so no action will be taken \emph{unless}
@@ -776,6 +781,9 @@
% \cs{TESTEXP} surrounds its contents with \cs{TYPE} and formatting to match \cs{TEST}; this can be used as a shorthand to test expandable commands.
% \item
% TODO: would a \cs{TESTFEXP} command (based on \cs{romannumeral} expansion) be useful as well?
+% \item
+% \cs{BEGINTEST}\marg{title} \dots \cs{ENDTEST} is an environment form of
+% \cs{TEST}, allowing verbatim material, \emph{etc.} to appear.
% \end{itemize}
% An example of some of these commands is shown following.
% \begin{Verbatim}
@@ -917,6 +925,22 @@
% \label{fig:box-log}
% \end{figure}
%
+% \subsection{Testing entire pages}
+%
+% There may be occasions where creating entire test pages is necessary
+% to observe the test output required. That is best achieved by applying
+% \cs{showoutput} and forcing a complete page to be produced, for example
+% \begin{Verbatim}[frame=single,fontsize=\small]
+% \input{regression-test.tex}
+% \documentclass{article}
+% \usepackage{expl3}
+% \START
+% \showoutput
+% % Test content here
+% \vfil\break
+% \END
+% \end{Verbatim}
+%
% \subsection{Additional test tasks}
%
% A standard test will run the file \texttt{\meta{name}.lvt} using one
@@ -1034,7 +1058,7 @@
% a suitable function might read as shown in Figure~\ref{fig:update-line}.
% \begin{figure}
% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6]
-% function setversion_update_line(line, date, release)
+% function setversion_update_line(line, date, version)
% -- No real regex so do it one type at a time
% for _,i in pairs({"Class", "File", "Package"}) do
% if string.match(
@@ -1044,7 +1068,7 @@
% line = string.gsub(line, "%[%d%d%d%d/%d%d/%d%d", "["
% .. string.gsub(date, "%-", "/")
% line = string.gsub(
-% line, "(%[%d%d%d%d/%d%d/%d%d) [^ ]*", "%1 " .. release
+% line, "(%[%d%d%d%d/%d%d/%d%d) [^ ]*", "%1 " .. version
% )
% break
% end
@@ -1133,12 +1157,14 @@
% \var{date} & String \\
% \var{engine} & Table \\
% \var{files} & Table \\
+% \var{force} & Boolean \\
% \var{halt} & Boolean \\
% \var{help} & Boolean \\
% \var{pdf} & Boolean \\
% \var{quiet} & Boolean \\
-% \var{release} & String \\
+% \var{rerun} & Boolean \\
% \var{testfiledir} & String \\
+% \var{version} & String \\
% \bottomrule
% \end{tabular}
% \end{center}
@@ -1256,7 +1282,7 @@
% error level.
% \end{function}
%
-% \begin{function}{spltpath()}
+% \begin{function}{splitpath()}
% \begin{syntax}
% |splitpath(|\meta{file}|)|
% \end{syntax}
@@ -1290,7 +1316,7 @@
%
% \begin{variable}{os_null}
% The location to redirect commands which should produce no output
-% at the terminal: almost always used preded by |>|, \emph{e.g.}
+% at the terminal: almost always used preceded by |>|, \emph{e.g.}
% \begin{verbatim}
% os.execute("tex " .. file .. " > " .. os_null)
% \end{verbatim}
@@ -1317,6 +1343,17 @@
% used inside |os.execute| (it does not terminate).
% \end{variable}
%
+% \subsection{Components of \texttt{l3build}}
+%
+% \begin{function}{call()}
+% \begin{syntax}
+% |call(|\meta{dirs}, \meta{target}|)|
+% \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.
+% \end{function}
+%
% \end{documentation}
%
% \begin{implementation}
@@ -1492,7 +1529,18 @@
% \end{macro}
%
% \begin{macro}
-% {\SEPARATOR, \TEST, \TESTEXP, \TRUE, \FALSE, \YES, \NO, \NEWLINE}
+% {
+% \SEPARATOR,
+% \BEGINTEST,
+% \ENDTEST,
+% \TEST,
+% \TESTEXP,
+% \TRUE,
+% \FALSE,
+% \YES,
+% \NO,
+% \NEWLINE
+% }
% We are not starved for space in the log file output, so let's make it as
% verbose as is useful when reading the |.diff|'s.
% \begin{macrocode}
@@ -1501,30 +1549,29 @@
============================================================%
}%
}
-\long\def\TEST#1#2{%
+\protected\long\def\BEGINTEST#1{%
\global\advance\gTESTint by 1 %
\SEPARATOR
\LONGTYPEOUT{TEST \the\gTESTint: \detokenize{#1}}%
\SEPARATOR
\begingroup
\let\TYPE\LONGTYPEOUT
- #2%
+
+}
+\protected\long\def\ENDTEST{%
\endgroup
\SEPARATOR
\LONGTYPEOUT{}%
}
+\long\def\TEST#1#2{%
+ \BEGINTEST{#1}%
+ #2%
+ \ENDTEST
+}
\long\def\TESTEXP#1#2{%
- \global\advance\gTESTint by 1 %
- \SEPARATOR
- \LONGTYPEOUT{%
- TEST \the\gTESTint: \detokenize{#1}}%
- \SEPARATOR
- \begingroup
- \long\def\TYPE##1{##1}%
- \LONGTYPEOUT{#2}%
- \endgroup
- \SEPARATOR
- \LONGTYPEOUT{}%
+ \BEGINTEST{#1}%
+ \LONGTYPEOUT{#2}%
+ \ENDTEST
}
\def \TRUE {\TYPE{TRUE}}
\def \FALSE {\TYPE{FALSE}}