l3 (14may17)

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

1 files changed, 174 insertions, 4 deletions

diff --git a/Master/texmf-dist/source/latex/l3build/l3build.dtx b/Master/texmf-dist/source/latex/l3build/l3build.dtx
index 7287b1a9ac1..81665872e6f 100644
--- a/Master/texmf-dist/source/latex/l3build/l3build.dtx
+++ b/Master/texmf-dist/source/latex/l3build/l3build.dtx
@@ -201,7 +201,7 @@
 %    }^^A
 % }
 %
-% \date{Released 2017/04/01}
+% \date{Released 2017/05/13}
 %
 % \maketitle
 % \tableofcontents
@@ -1026,8 +1026,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, version)
-%       local i
+%     function setversion_update_line(line, date, release)
 %       -- No real regex so do it one type at a time
 %       for _,i in pairs({"Class", "File", "Package"}) do
 %         if string.match(
@@ -1037,7 +1036,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 " .. version
+%             line, "(%[%d%d%d%d/%d%d/%d%d) [^ ]*", "%1 " .. release
 %           )
 %           break
 %         end
@@ -1105,6 +1104,177 @@
 %   \label{fig:PDF}
 % \end{figure}
 %
+% \section{Lua interfaces}
+%
+% Whilst for the majority of users the simple variable-based control methods
+% outlined above will suffice, for more advanced applications there will be
+% a need to adjust behavior by using interfaces within the Lua code. This
+% section details the global variables and functions provided.
+%
+% \subsection{Global variables}
+%
+% \begin{variable}{options}
+%   The |options| table holds the values passed to \pkg{l3build} at the
+%   command line. The possible entries in the table are given in the table
+%   below.
+%   \begin{center}
+%   \begin{tabular}{ll}
+%     \toprule
+%     Entry & Type \\
+%     \midrule
+%       \var{date}        & String  \\
+%       \var{engine}      & Table   \\
+%       \var{files}       & Table   \\
+%       \var{halt}        & Boolean \\
+%       \var{help}        & Boolean \\
+%       \var{pdf}         & Boolean \\
+%       \var{quiet}       & Boolean \\
+%       \var{release}     & String  \\
+%       \var{testfiledir} & String  \\
+%     \bottomrule
+%     \end{tabular}
+%   \end{center}
+% \end{variable}
+%
+% \subsection{Utility functions}
+%
+% The utility functions are largely focussed on file operations, though a small
+% number of others are provided. File paths should be given in Unix style
+% (using |/| as a path separator). File operations take place relative to the
+% path from which \pkg{l3build} is called. File operation syntax is largely
+% modelled on Unix command line commands but reflect the need to work on
+% Windows in a flexible way.
+%
+% \begin{function}{abspath()}
+%   \begin{syntax}
+%     |abspath(|\meta{target}|)|
+%   \end{syntax}
+%   Returns a string which gives the absolute location of the
+%   \meta{target} directory.
+% \end{function}
+%
+% \begin{function}{cleandir()}
+%   \begin{syntax}
+%     |cleandir(|\meta{dir}|)|
+%   \end{syntax}
+%   Removes any content within the \meta{dir}; returns an error level.
+% \end{function}
+%
+% \begin{function}{cp()}
+%   \begin{syntax}
+%     |cp(|\meta{glob}, \meta{source}, \meta{destination}|)|
+%   \end{syntax}
+%   Copies files matching the \meta{glob} from the \meta{source} directory
+%   to the \meta{destination}; returns an error level.
+% \end{function}
+%
+% \begin{function}{direxists()}
+%   \begin{syntax}
+%     |direxists(|\meta{dir}|)|
+%   \end{syntax}
+%   Tests if the \meta{dir} exists; returns a boolean value.
+% \end{function}
+%
+% \begin{function}{fileexists()}
+%   \begin{syntax}
+%     |fileexists(|\meta{file}|)|
+%   \end{syntax}
+%   Tests if the \meta{file} exists; returns a boolean value.
+% \end{function}
+%
+% \begin{function}{filelist()}
+%   \begin{syntax}
+%     |filelist(|\meta{path}, \oarg{glob}|)|
+%   \end{syntax}
+%   Returns a table containing all of the files with the \meta{path}
+%   which match the \meta{glob}; if the latter is absent returns a list of
+%   all files in the \meta{path}.
+% \end{function}
+%
+% \begin{function}{mkidr()}
+%   \begin{syntax}
+%     |mkdir(|\meta{dir}|)|
+%   \end{syntax}
+%   Creates the \meta{dir}; returns an error level.
+% \end{function}
+%
+% \begin{function}{ren()}
+%   \begin{syntax}
+%     |ren(|\meta{dir}, \meta{source}, \meta{destination}|)|
+%   \end{syntax}
+%   Renames the \meta{source} file to the \meta{destination} name within
+%   the \meta{dir}; returns an error level.
+% \end{function}
+%
+% \begin{function}{rm()}
+%   \begin{syntax}
+%     |rm(|\meta{dir}, \meta{glob}|)|
+%   \end{syntax}
+%   Removes files in the \meta{dir} matching the \meta{glob}; returns an
+%   error level.
+% \end{function}
+%
+% \begin{function}{run()}
+%   \begin{syntax}
+%     |run(|\meta{dir}, \meta{cmd}|)|
+%   \end{syntax}
+%   Executes the \meta{cmd}, starting it in the \meta{dir}; returns an
+%   error level.
+% \end{function}
+%
+% \begin{function}{unix_to_win()}
+%   \begin{syntax}
+%     |unix_to_win(|\meta{path}|)|
+%   \end{syntax}
+%   Returns a string comprising the \meta{path} with |/| characters replaced
+%   by |\\|  and thus suitable for use with Windows-specific commands which
+%   require this form of path.
+% \end{function}
+%
+% \subsection{System-dependent strings}
+%
+% To support creation of additional functionality, the following low-level
+% strings are exposed by \pkg{l3build}: these all have system-dependent
+% definitions and avoid the need to test |os.type| during the construction
+% of system calls.
+%
+% \begin{variable}{os_concat}
+%   The concatenation operation for using multiple commands in one
+%   system call, \emph{e.g.}
+%   \begin{verbatim}
+%     os.execute("tex " .. file .. os_concat .. "tex " .. file)
+%   \end{verbatim}
+% \end{variable}
+%
+% \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.}
+%   \begin{verbatim}
+%     os.execute("tex " .. file .. " > " .. os_null)
+%   \end{verbatim}
+% \end{variable}
+%
+% \begin{variable}{os_pathsep}
+%   The separator used when setting an environment variable to multiple
+%   paths, \emph{e.g.}
+%   \begin{verbatim}
+%     os.execute(os_setenv .. " PATH=../a" .. os_pathsep .. "../b")
+%   \end{verbatim}
+% \end{variable}
+%
+% \begin{variable}{os_setenv}
+%   The command to set an environmental variable, \emph{e.g.}
+%   \begin{verbatim}
+%     os.execute(os_setenv .. " PATH=../a")
+%   \end{verbatim}
+% \end{variable}
+%
+% \begin{variable}{os_yes}
+%   A command to generate a series of $200$ lines each containing the
+%   character |y|: this is useful as the Unix |yes| command cannot be
+%   used inside |os.execute| (it does not terminate).
+% \end{variable}
+%
 % \end{documentation}
 %
 % \begin{implementation}