l3build (10mar18)

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

1 files changed, 33 insertions, 15 deletions

diff --git a/Master/texmf-dist/source/latex/l3build/l3build.dtx b/Master/texmf-dist/source/latex/l3build/l3build.dtx
index 567dd1fce5d..a87e0724efc 100644
--- a/Master/texmf-dist/source/latex/l3build/l3build.dtx
+++ b/Master/texmf-dist/source/latex/l3build/l3build.dtx
@@ -216,7 +216,7 @@
 %    }^^A
 % }
 %
-% \date{Released 2018-03-09}
+% \date{Released 2018-03-10}
 %
 % \maketitle
 % \tableofcontents
@@ -547,12 +547,21 @@
 % By default this process allows files to be accessed in all standard |texmf| trees; this can be disabled by setting \var{unpacksearch} to |false|.
 % \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}
 %
 % An example of a standalone build script for a package that uses self-contained |.dtx| files is shown in Figure~\ref{fig:breqn}.
 % Here, the |module| only is defined, and since it doesn't use |.ins| files so the variable \var{unpackfiles} is redefined to run |tex| on the |.dtx| files instead to generate the necessary |.sty| files.
 % There are some PDFs in the repository that shouldn't be part of a CTAN submission, so they're explicitly excluded, and here unpacking is done `quietly' to minimise console output when building the package.
-% Finally, because this is a standalone package, we assume that \pkg{l3build} is installed in the main \TeX{} distribution and find the Lua script by searching for it.
 %
 % \begin{figure}[!b]
 %   \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6]
@@ -582,11 +591,6 @@
 %
 %     -- Location of main directory: use Unix-style path separators
 %     maindir = ".."
-%
-%     -- Load the common build code: this is the one place that a path
-%     -- needs to be hard-coded
-%     dofile(maindir .. "/l3build/l3build-config.lua")
-%     dofile(maindir .. "/l3build/l3build.lua")
 %   \end{lstlisting}
 % \caption{The build script for the \pkg{l3packages} bundle.}
 % \label{fig:bundle}
@@ -603,16 +607,33 @@
 %     -- Location of main directory: use Unix-style path separators
 %     -- Should match that defined by the bundle.
 %     maindir = "../.."
-%
-%     -- Load the common build code: this is the one place that a path
-%     -- needs to be hard-coded
-%     dofile(maindir .. "/l3build/l3build-config.lua")
-%     dofile(maindir .. "/l3build/l3build.lua")
 %   \end{lstlisting}
 % \caption{The build script for the \pkg{xparse} module.}
 % \label{fig:module}
 % \end{figure}
 %
+% \subsection{Backward compatibly}
+%
+% 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}
+% 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}.
+% \begin{figure}
+%   \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6]
+%     if not release_date then
+%       dofile(kpse.lookup("l3build.lua"))
+%     end
+%   \end{lstlisting}
+% \caption{Final lines for a \texttt{build.lua} script usable with both older
+%   and newer releases of \pkg{l3build}.}
+% \label{fig:build-compat}
+% \end{figure}
+%
+% Note that in time support for loading \pkg{l3build} by calling the
+% \texttt{build.lua} script \emph{may} be removed: the recommended approach for
+% new scripts is to run \pkg{l3build}.
+%
 % \subsection{Variables}
 %
 % This section lists all variables defined in the |l3build.lua| script that are available for customisation.
@@ -1195,9 +1216,6 @@
 %       end
 %       return errorlevel
 %     end
-%
-%     kpse.set_program_name("kpsewhich")
-%     dofile(kpse.lookup("l3build.lua"))
 %   \end{lstlisting}
 %   \caption{A customised PDF creation script.}
 %   \label{fig:PDF}