summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3build/l3build.dtx
diff options
context:
space:
mode:
authorNorbert Preining <preining@logic.at>2016-06-17 15:17:17 +0000
committerNorbert Preining <preining@logic.at>2016-06-17 15:17:17 +0000
commitcc9c5c66b9e6ae378ed92da735b5dd16bd94f0d5 (patch)
treebcbadeace80dabfa7116db9a37a03438fa31c33d /Master/texmf-dist/source/latex/l3build/l3build.dtx
parentb77a348b68095e25ff53806034cd68543066a39d (diff)
l3build (17Jun)
git-svn-id: svn://tug.org/texlive/trunk@41469 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3build/l3build.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3build/l3build.dtx115
1 files changed, 102 insertions, 13 deletions
diff --git a/Master/texmf-dist/source/latex/l3build/l3build.dtx b/Master/texmf-dist/source/latex/l3build/l3build.dtx
index 91847d2db7e..97fe4972e8d 100644
--- a/Master/texmf-dist/source/latex/l3build/l3build.dtx
+++ b/Master/texmf-dist/source/latex/l3build/l3build.dtx
@@ -39,12 +39,11 @@
\RequirePackage{expl3}
\def\ExplFileName{l3build}
\def\ExplFileDescription{L3 Regression test suite}
-\def\ExplFileDate{2016/03/26}
-\def\ExplFileVersion{6466}
+\def\ExplFileDate{2016/06/14}
+\def\ExplFileVersion{6608}
\documentclass[full]{l3doc}
\renewcommand\partname{Part}
\usepackage{multicol,needspace}
-
\makeatletter
\addtolength\columnsep{1em}
\renewcommand\columnseprule{0.4pt}
@@ -58,7 +57,6 @@
\@nobreakfalse
\end{multicols}}
\makeatother
-
\newenvironment{buildcmd}[1]{%
\bigskip\par\noindent\hspace{-\parindent}%
\fbox{\ttfamily \textcolor[gray]{0.5}{\$} texlua build.lua #1}%
@@ -114,10 +112,13 @@
\luavarset{versionfiles} {\{"*.dtx"\}} {Files for automatic version editing.}
\luavarseparator
\luavarset{bakext} {".bak"} {Extension of backup files.}
+\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{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.}
\luavarseparator
\luavarset{checkdeps} {\{~\}} {List of build unpack dependencies for checking.}
\luavarset{typesetdeps} {\{~\}} {\dots for typesetting docs.}
@@ -154,6 +155,7 @@
\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.}
\luavarset{maxprintline}{79} {Length of line to use in log files.}
\luavarset{packtdszip} {false} {Build a TDS-style zip file for CTAN?}
\luavarset{scriptname} {"build.lua"} {Name of script used in dependencies.}
@@ -187,17 +189,14 @@
\end{longtable}
\endgroup
}
-
\newcommand\code{\texttt}
\newcommand\var{\texttt}
-
\usepackage[procnames]{listings}
\lstset{
basicstyle=\ttfamily\small,
numbers=left,
numberstyle={\tiny\color[gray]{0.4}},
}
-
\usepackage{shortvrb}
\usepackage{enumitem}
\usepackage{longtable}
@@ -310,17 +309,24 @@
% \item doc
% \item install
% \item save \meta{name(s)}
+% \item setversion
% \end{itemize}
% These commands are described below.
%
% As well as these commands, the system recognises the options
% \begin{itemize}
+% \item \texttt{--date} (\texttt{-d}) Date to use when setting version
+% data
% \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
+% \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{--version} (\texttt{-v}) Version string to use when setting
+% version data
% \end{itemize}
%
% \begin{buildcmd}{check}
@@ -367,6 +373,16 @@
% testing to a single engine.
% \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}{cmdcheck}
% For \cls{l3doc}-based sources, allows checking that the commands defined in the code part (by \var{cmdchkfiles}) are documented in the description part.
% This is performed by passing the |check| option to the \cls{l3doc} class, typesetting the file(s) to check with engine \var{stdengine} with options \var{cmdchkopts}, and checking the resultant |.cmds| file(s).
@@ -461,6 +477,15 @@
% 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}
%
+% \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}{setversion}
% Modifies the content of files specified by |versionfiles| to allow
% automatic updating of the file date and version. The latter are
@@ -875,6 +900,31 @@
% \label{fig:box-log}
% \end{figure}
%
+% \subsection{Additional test tasks}
+%
+% A standard test will run the file \texttt{\meta{name}.lvt} using one
+% or more engines, but will not carry out any additional processing. For
+% some tests, for example bibliography generation, it may be desirable to
+% call one or more tools in addition to the engine. This can be arranged
+% by defining |runtest_tasks|, a function taking one argument, the name
+% of the current test (this is equivalent to \TeX{}'s \cs{jobname},
+% \emph{i.e.}~it lacks an extension). The function |runtest_tasks|
+% is is into a call to the system to run the engine. As such, it
+% should take return a string with the appropriate command(s)
+% and option(s). If more than one task is required, these should be separated
+% by use of |os_concat|, a string variable defined by \pkg{l3build} as the
+% correct concatenation marker for the system. An example of |runtest_tasks|
+% suitable for calling Biber is shown in Listing~\ref{fig:test-tasks}.
+% \begin{figure}
+% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6]
+% function runtest_tasks(name)
+% return "biber " .. name
+% end
+% \end{lstlisting}
+% \caption{Example \texttt{runtest_tasks} function.}
+% \label{fig:test-tasks}
+% \end{figure}
+%
% \section{Alternative test formats}
%
% \subsection{Generating test files with \pkg{DocStrip}}
@@ -956,7 +1006,7 @@
% \item |ExplFileName| --- Searches for lines using |\def\ExplFileName|,
% |\def\ExplFileDate|, \dots, formulation.
% \end{itemize}
-%
+%
% For more complex cases, the programmer may directly define the
% Lua function |setversion_update_line()|, which takes as arguments the line of the
% source, the supplied date and the supplied version. It should return a
@@ -1091,7 +1141,6 @@
\def\loggingoutput{\tracingoutput1
\showboxbreadth\maxdimen\showboxdepth\maxdimen}
% \end{macrocode}
-
%
% Set the newline character: \LaTeXe{} does this but plain-based formats
% do not.
@@ -1323,14 +1372,56 @@
\SEPARATOR
\LONGTYPEOUT{}%
}
-
\def \TRUE {\TYPE{TRUE}}
\def \FALSE {\TYPE{FALSE}}
\def \YES {\TYPE{YES}}
\def \NO {\TYPE{NO}}
-
\def \NEWLINE {\TYPE{^^J}}
% \end{macrocode}
+%
+% \subsection{Suppressing variable data in output}
+%
+% To make any PDF file produced comparable we need to suppress various
+% pieces of data. This works in concert with setting the epoch from the
+% environment side (as not all output can be controlled here). We are
+% somewhat stuck if \texttt{dvips} is being used so just hope for the best!
+% There is a limit to what can be done with the underlying PDF structure so
+% there is no point entirely suppressing \texttt{Producer}: simply avoid
+% any version numbers.
+% \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
+ \pdfinfo{/Producer (\ifx\directlua\@undefined pdf\else Lua\fi TeX)}
+ \ifx\pdfinfoomitdate\@undefined\else
+ \pdfinfoomitdate = 1 %
+ \pdfsuppressptexinfo = 1 %
+ \pdftrailerid{}
+ \fi
+ \else
+ \pdfextension info{/Producer (LuaTeX)}
+ \pdfvariable suppressoptionalinfo \numexpr
+ 0
+ + 1 % PTEX.Fullbanner
+ + 32 % CreationDate
+ + 64 % ModDate
+ \relax
+ \fi
+\else
+ \special{%
+ pdf: docinfo
+ <<
+ /Creator (TeX)
+ /CreationDate ()
+ /ModDate ()
+ /Producer (\ifx\XeTeXversion\@undefined\else x\fi dvipdfmx)
+ >>
+ }
+\fi
+% \end{macrocode}
+%
% Finish up.
% \begin{macrocode}
\reset@catcodes
@@ -1361,5 +1452,3 @@
% \end{implementation}
%
% \PrintIndex
-
-