summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3build
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2017-05-14 22:40:58 +0000
committerKarl Berry <karl@freefriends.org>2017-05-14 22:40:58 +0000
commite0c5d6d38a1f285f20a66692e46d2e607d6ff1dd (patch)
tree977232bc088d27b46d9a6330c8f4f47aa98dbb78 /Master/texmf-dist/source/latex/l3build
parent4407d96af752e6e79a48c25c5189bd1a63fbd125 (diff)
l3 (14may17)
git-svn-id: svn://tug.org/texlive/trunk@44351 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3build')
-rw-r--r--Master/texmf-dist/source/latex/l3build/l3build.dtx178
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}