summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3build/l3build.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/l3build/l3build.dtx')
-rw-r--r--macros/latex/contrib/l3build/l3build.dtx79
1 files changed, 53 insertions, 26 deletions
diff --git a/macros/latex/contrib/l3build/l3build.dtx b/macros/latex/contrib/l3build/l3build.dtx
index b2a981434f..f00774cada 100644
--- a/macros/latex/contrib/l3build/l3build.dtx
+++ b/macros/latex/contrib/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()}