l3build (18feb20)

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

1 files changed, 53 insertions, 26 deletions

diff --git a/Master/texmf-dist/source/latex/l3build/l3build.dtx b/Master/texmf-dist/source/latex/l3build/l3build.dtx
index b2a981434fd..f00774cada1 100644
--- a/Master/texmf-dist/source/latex/l3build/l3build.dtx
+++ b/Master/texmf-dist/source/latex/l3build/l3build.dtx
@@ -64,6 +64,7 @@
 \luavarset{testfiledir}{"./testfiles"}  {Directory containing test files}
 \luavarset{testsuppdir}{testfiledir .. "/support"}{Directory containing test-specific support files}
 \luavarset{texmfdir}{maindir .. "/texmf"}{Directory containing support files in tree form}
+\luavarset{textfiledir}{"."}                 {Directory containing plain text files}
 \luavarseparator
 \luavarset{builddir}  {maindir .. "/build"}   {Directory for building and testing}
 \luavarset{distribdir}{builddir .. "/distrib"}{Directory for generating distribution structure}
@@ -137,6 +138,7 @@
 \luavarseparator
 \luavarset{glossarystyle}{"gglo.ist"}{MakeIndex style file for glossary/changes creation}
 \luavarset{indexstyle}   {"gind.ist"}{MakeIndex style for index creation}
+\luavarset{specialtypesetting}{\meta{table}} {Non-standard typesetting combinations}
 \luavarseparator
 \luavarset{forcecheckepoch}{"true"}    {Force epoch when running tests}
 \luavarset{forcedocepoch}  {"false"}   {Force epoch when typesetting}
@@ -231,7 +233,7 @@
 %    }^^A
 % }
 %
-% \date{Released 2020-02-03}
+% \date{Released 2020-02-17}
 %
 % \maketitle
 % \tableofcontents
@@ -310,13 +312,22 @@
 % For a module, this build folder can be in the main directory of the package itself, but for a bundle it should be common for the bundle itself and for all modules within that bundle.
 % A |build/| folder can be safety deleted; all material within is re-generated for each command of the \pkg{l3build} system.
 %
-% \subsection{Main build commands}
+% \subsection{The \texttt{build.lua} file}
+%
+% The \texttt{build.lua} file used to control \pkg{l3build} is a simple Lua file
+% which is read during execution. In the current release of \pkg{l3build},
+% \texttt{build.lua} is read automatically and can access all of the global
+% functions provided by the script. Thus it may contain a simple list of
+% variable settings \emph{or} additionally custom code to change the build
+% process. A number of example scripts are given in Section~\ref{sec:examples}.
+%
+% \subsection{Main build targets}
 %
 % In the working directory of a bundle or module, \pkg{l3build} is run by executing
 % \begin{center}
-% \texttt{l3build \meta{command} [\meta{option(s)}]}
+% \texttt{l3build \meta{targets} [\meta{option(s)}]}
 % \end{center}
-% where \texttt{\meta{command}} can be one of the following:
+% where \texttt{\meta{targets}} can be one of the following:
 % \begin{itemize}[noitemsep]\ttfamily
 % \item check
 % \item check \meta{name(s)}
@@ -333,9 +344,9 @@
 % \item upload
 % \item upload \meta{tag}
 % \end{itemize}
-% These commands are described below.
+% These targets are described below.
 %
-% As well as these commands, the system recognises the options
+% As well as these targets, the system recognises the options
 % \begin{itemize}
 % \item |--config| (|-c|) Configuration(s) to use for testing
 % \item |--date| Date to use when tagging data
@@ -510,7 +521,7 @@
 %
 % \begin{buildcmd}{install}
 % Copies all package files (defined by \var{installfiles}) into the user's home \texttt{texmf} tree in the form of the \TeX\ Directory Structure.
-% The location of the user tree can be adjusted using the |--texmfhome| swtich:
+% The location of the user tree can be adjusted using the |--texmfhome| switch:
 % the standard setting is the location set as |TEXMFHOME|.
 % \end{buildcmd}
 %
@@ -584,15 +595,6 @@
 % See Section~\ref{sec:upload} for full details on this feature.
 % \end{buildcmd}
 %
-% \subsection{The \texttt{build.lua} file}
-%
-% The \texttt{build.lua} file used to control \pkg{l3build} is a simple Lua file
-% which is read during execution. In the current release of \pkg{l3build},
-% \texttt{build.lua} is read automatically and can access all of the global
-% functions provided by the script. Thus it may contain a simple list of
-% variable settings \emph{or} additionally custom code to change the build
-% process. A number of example scripts are given in Section~\ref{sec:examples}.
-%
 % \subsection{Example build scripts}
 % \label{sec:examples}
 %
@@ -649,10 +651,13 @@
 % \label{fig:module}
 % \end{figure}
 %
+% A collection of full examples (source files in various layouts) are available
+% at \url{https://github.com/latex3/l3build/tree/master/examples}.
+%
 % \subsection{Backwards compatibility}
 %
 % Earlier releases of \pkg{l3build} required that the last line of
-% \texttt{build.lua} ran the main script, \emph{i.e.}~ that \texttt{build.lua}
+% \texttt{build.lua} ran the main script, \emph{i.e.}~that \texttt{build.lua}
 % was what the user called rather than \texttt{l3build.lua}. To allow scripts
 % to support both forms \emph{for the transition}, a simple test may be
 % included as showing in Figure~\ref{fig:build-compat}.
@@ -770,7 +775,8 @@
 % A variety of source layouts are supported. In general, a \enquote{flat}
 % layout with all source files \enquote{here} is most convenient. However,
 % \pkg{l3build} supports placement of both code and documentation source
-% files in other locations using the \var{sourcefiledir} and \var{docfiledir}
+% files in other locations using the \var{sourcefiledir}, \var{docfiledir}
+% and \var{textfiledir}
 % variables. For pre-built trees, the glob syntax \texttt{**/*.\meta{ext}} may
 % be useful in these cases: this enables recursive searching in the appropriate
 % tree locations. With the standard settings, this structure will be removed
@@ -778,6 +784,11 @@
 % used to control this behavior. The \var{flattentds} setting controls
 % the same concept for TDS creation.
 %
+% Notice that text files are treated separately from documentation files when
+% splitting trees: this is to allow for the common case where files such
+% as |README| and |LICENSE| are at the top level even when other documentation
+% files are in a sub-directory.
+%
 % A series of example layouts and matching |build.lua| files are available from
 % \url{https://github.com/latex3/l3build/tree/master/examples}.
 %
@@ -924,8 +935,6 @@
 % \item
 % \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.
 % \item
@@ -1263,7 +1272,7 @@
 % tree, one might use the set up shown in Figure~\ref{fig:tds}.
 % \begin{figure}
 %   \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6]
-%     tdslocations = 
+%     tdslocations =
 %       {
 %         "tex/generic/mypkg/*.generic.tex" ,
 %         "tex/plain/mypkg/*.plain.tex"    ,
@@ -1355,7 +1364,8 @@
 % copying files to the typesetting location but before the main typesetting
 % run. This may be used for example to script a very large number of
 % demonstrations using a single source (see the \pkg{beamer} package
-% for an example of this).
+% for an example of this). Note that this hook is intended for use files
+% \emph{not} listed in \var{typesetfiles} or \var{typesetdemofiles}.
 %
 % \begin{figure}[!b]
 %   \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6]
@@ -1391,6 +1401,22 @@
 % to be executed once all standard set up is complete but before any typesetting
 % is run.
 %
+% \subsection{Non-standard typesetting}
+%
+% To allow non-standard typesetting combinations, for example per-file
+% choice of engines, the table \var{specialtypesetting} may be used.
+% This is a table with one entry per file. Each entry is itself a table,
+% and these contain a list of engines and settings for |cmd| and |func|.
+% For example, to choose to use \LuaTeX{} for one file when \var{typesetexe}
+% is |pdftex|
+% \begin{verbatim}
+% specialtypesetting.foo = {cmd = "luatex -interaction=nonstopmode"}
+% \end{verbatim}
+% or to select an entirely different typesetting function
+% \begin{verbatim}
+% specialtypesetting.foo = {func = typeset_foo}
+% \end{verbatim}
+%
 % \subsection{Automated upload to CTAN}
 % \label{sec:upload}
 %
@@ -1790,7 +1816,7 @@
 %   \end{syntax}
 %   Runs Biber on the \meta{name} (\emph{i.e.}~a jobname lacking any
 %   extension) inside the \meta{dir}. If there is no |.bcf| file then
-%   no action is taken with a return value of $0$. 
+%   no action is taken with a return value of $0$.
 % \end{function}
 %
 % \begin{function}{bibtex()}
@@ -1799,7 +1825,7 @@
 %   \end{syntax}
 %   Runs Bib\TeX{} on the \meta{name} (\emph{i.e.}~a jobname lacking any
 %   extension) inside the \meta{dir}. If there are no |\citation| lines in
-%   the |.aux| file then no action is taken with a return value of $0$. 
+%   the |.aux| file then no action is taken with a return value of $0$.
 % \end{function}
 %
 % \begin{function}{makeindex()}
@@ -1813,9 +1839,10 @@
 %
 % \begin{function}{tex()}
 %   \begin{syntax}
-%     |tex(|\meta{file},\meta{dir}|)|
+%     |tex(|\meta{file},\meta{dir},\meta{cmd}|)|
 %   \end{syntax}
-%   Runs \luavar{typesetexe} on the \meta{name} inside the \meta{dir}.
+%   Runs \meta{cmd} (by default \luavar{typesetexe} \luavar{typesetopts}) on the
+%   \meta{name} inside the \meta{dir}.
 % \end{function}
 %
 % \begin{function}{runcmd()}