l3build (3aug18)

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

1 files changed, 73 insertions, 28 deletions

diff --git a/Master/texmf-dist/source/latex/l3build/l3build.dtx b/Master/texmf-dist/source/latex/l3build/l3build.dtx
index fd2e652347b..f15e1b970a9 100644
--- a/Master/texmf-dist/source/latex/l3build/l3build.dtx
+++ b/Master/texmf-dist/source/latex/l3build/l3build.dtx
@@ -102,13 +102,18 @@
 \luavarseparator
 \luavarset{bakext}{".bak"}{Extension of backup files}
 \luavarset{dviext}{".dvi"}{Extension of DVI files}
-\luavarset{lvtext}{".lvt"}{Extension of test files}
+\luavarset{lvtext}{".lvt"}{Extension of log-based test files}
 \luavarset{tlgext}{".tlg"}{Extension of test file output}
+\luavarset{tpfext}{".tpf"}{Extension of PDF-based test 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{pvtext}{".pvt"}{Extension of PDF-based test files}
 \luavarset{pdfext}{".pdf"}{Extension of PDF file for checking and saving}
 \luavarset{psext} {".ps"} {Extension of PostScript files}
 \luavarseparator
+\luavarset{includetests}{\{"*"\}}{Test names to include when checking}
+\luavarset{excludetests}{\{\}}   {Test names to exclude when checking}
+\luavarseparator
 \luavarset{checkdeps}  {\{\}}{List of dependencies for running checks}
 \luavarset{typesetdeps}{\{\}}{List of dependencies for typesetting docs}
 \luavarset{unpackdeps} {\{\}}{List of dependencies for unpacking}
@@ -135,7 +140,6 @@
 \luavarset{glossarystyle}{"gglo.ist"}{MakeIndex style file for glossary/changes creation}
 \luavarset{indexstyle}   {"gind.ist"}{MakeIndex style for index creation}
 \luavarseparator
-\luavarseparator
 \luavarset{biberexe}     {"biber"}    {Biber executable}
 \luavarset{biberopts}    {""}         {Biber options}
 \luavarset{bibtexexe}    {"bibtex8"}  {\BibTeX{} executable}
@@ -217,7 +221,7 @@
 %    }^^A
 % }
 %
-% \date{Released 2018-05-10}
+% \date{Released 2018-08-02}
 %
 % \maketitle
 % \tableofcontents
@@ -315,6 +319,7 @@
 %   \item |--config| (|-c|) Configuration(s) to use for testing
 % \item |--date| Date to use when tagging
 %   data
+% \item |--dirty| Skip cleaning up of the test area
 % \item |--dry-run| Runs the \texttt{install} target but does not copy
 %   any files: simply lists those that would be installed
 % \item |--engine| (|-e|) Sets the engine to use for
@@ -328,11 +333,9 @@
 %   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 |--last| Name of the last test to run
-% \item |--pdf| (|-p|) Test PDF file against a reference
-%   version rather than using a log comparison
 % \item |--quiet| (|-q|) Suppresses output from unpacking
 % \item |--rerun| Run tests without unpacking/set up
-% \item |--shuffle| Shuffle the order in whichs tests run
+% \item |--shuffle| Shuffle the order in which tests run
 % \item |--texmfhome| Sets the location of the user tree for installing
 % \end{itemize}
 %
@@ -382,16 +385,6 @@
 % test directory: this may be skipped using the |-s| option.
 % \end{buildcmd}
 %
-% \begin{buildcmd}{check -p}
-% Rather than the log-based checking carried out by the standard
-% |check| target, running with the |-p| option carries out a binary
-% comparison of the PDF files produced by typesetting against those
-% saved in \var{testfiledir}.
-%
-% This functionality requires \TeX{} Live 2016 or later as it needs support
-% from the engines not available in earlier releases.
-% \end{buildcmd}
-%
 % \begin{buildcmd}{clean}
 % This command removes all temporary files used for package bundling and regression testing.
 % In the standard layout, these are all files within the directories defined by \var{localdir}, \var{testdir}, \var{typesetdir} and \var{unpackdir}, as well as all files defined in the \var{cleanfiles} variable in the same directory as the script.
@@ -496,15 +489,6 @@
 % the \enquote{exit status} is zero, else non-zero.
 % \end{buildcmd}
 %
-% \begin{buildcmd}{save -p \meta{name(s)}}
-% This version of |save| will store the PDF files produced from
-% \texttt{\meta{name(s)}.lvt} in addition to the |.tlg| file, and thus allows
-% binary comparison of the result of typesetting.
-%
-% This functionality requires \TeX{} Live 2016 or later as it needs support
-% from the engines not available in earlier releases.
-% \end{buildcmd}
-%
 % \begin{buildcmd}{manifest}
 % Generates a `manifest' file which lists the files of the package as known to \pkg{l3build}.
 % The filename of this file (by default \luavar{manifestfile}) can be set with the variable \var{manifestfile}.
@@ -650,6 +634,15 @@
 %
 % \luavartypeset
 %
+% \subsection{Selective running of tests}
+%
+% The variables |includetests| and |excludetests| may be used to select which
+% tests are run: these variables take test \emph{names} not full file names.
+% The list of tests in |excludetests| overrides any matches in |includetests|,
+% meaning that tests can be disabled selectively. It also makes it possible
+% to disable test on for example a platform basis: the Lua core variable
+% |os.type| may be used to set |excludetests| only on some systems.
+%
 % \subsection{Multiple sets of tests}
 %
 % In most cases, a single set of tests will be appropriate for the module, with
@@ -1116,6 +1109,24 @@
 %   \label{fig:expect-ins}
 % \end{figure}
 %
+% \subsection{PDF-based tests}
+%
+% In most cases, testing is best handled by using the text-based methods
+% outlined above. However, there are cases where the detail of output structure
+% is important. This can only be fully tested by comparing PDF structure.
+% To support this, \pkg{l3build} can be instructed to build and compare
+% PDF files by setting up tests in \texttt{.pvt} files. The following
+% normalization takes place:
+% \begin{itemize}
+%   \item Replacement of binary streams by the marker |[BINARY STREAM]|
+%   \item Removal of blank lines
+% \end{itemize}
+%
+% Testing on the result of typesetting \texttt{.pvt} files is carried out using
+% only the standard engine, as aspects of PDF files are not identical between
+% engines. To allow platform-independence, PDF-based tests must use only
+% Type1 or OpenType fonts: Type3 fonts are system-dependent.
+%
 % \section{Release-focussed features}
 %
 % \subsection{Automatic tagging}
@@ -1222,7 +1233,6 @@
 %   \label{fig:PDF}
 % \end{figure}
 %
-%
 % \section{Lua interfaces}
 %
 % Whilst for the majority of users the simple variable-based control methods
@@ -1247,7 +1257,6 @@
 %       \var{halt}        & Boolean \\
 %       \var{help}        & Boolean \\
 %       \var{names}       & Table   \\
-%       \var{pdf}         & Boolean \\
 %       \var{quiet}       & Boolean \\
 %       \var{rerun}       & Boolean \\
 %       \var{testfiledir} & Table   \\
@@ -1443,6 +1452,24 @@
 %   |target| in this table is ignored.
 % \end{function}
 %
+% \subsection{Customising the target list}
+%
+% The targets known to \pkg{l3build} are stored in the global table
+% |target_list|. Each entry should have at least a |func|, pointing to the
+% function used to implement the target. This function will receive the
+% list of names given at the command line as a table argument.
+% In most cases, targets will also have a |desc|, used to construct |help()|
+% automatically. In addition, the following may also be used:
+% \begin{itemize}
+%   \item |bundle_func| A variant of |func| used when at the top level of
+%     a bundle
+%   \item |bundle_target| A boolean to specify that when passing the target
+%     name in a bundle, it should have |bundle| prepended.
+%   \item |pre| A function executed before the main function, and receiving
+%     the |names| as an argument; this allows checking of the |name| data
+%     without impact on the main |func|.
+% \end{itemize}
+%
 % \subsection{Customising the manifest file}
 % \label{sec:manifest}
 %
@@ -1815,7 +1842,6 @@
   \SEPARATOR
   \begingroup
     \let\TYPE\LONGTYPEOUT
-
 }
 \protected\long\def\ENDTEST{%
   \endgroup
@@ -1899,6 +1925,25 @@
 \fi
 %    \end{macrocode}
 %
+% Disable compression in PDF output.
+%    \begin{macrocode}
+\ifnum 0%
+  \ifx\pdfoutput\@undefined\else\ifnum\pdfoutput>0 1\fi\fi
+  \ifx\outputmode\@undefined\else\ifnum\outputmode>0 1\fi\fi
+  >0 %
+  \ifx\pdfvariable\@undefined
+    \pdfcompresslevel=0 %
+    \pdfobjcompresslevel=0 %
+  \else
+    \pdfvariable compresslevel=0 %
+    \pdfvariable objcompresslevel=0 %
+  \fi
+\else
+  \special{dvipdfmx:config z 0}% Compress level
+  \special{dvipdfmx:config C 0x40}% Object compression
+\fi
+%    \end{macrocode}
+%
 % Finish up.
 %    \begin{macrocode}
 \reset@catcodes