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.dtx94
1 files changed, 56 insertions, 38 deletions
diff --git a/macros/latex/contrib/l3build/l3build.dtx b/macros/latex/contrib/l3build/l3build.dtx
index 96c1f0ead8..16fc10055d 100644
--- a/macros/latex/contrib/l3build/l3build.dtx
+++ b/macros/latex/contrib/l3build/l3build.dtx
@@ -251,7 +251,7 @@
% }^^A
% }
%
-% \date{Released 2024-02-08}
+% \date{Released 2024-10-16}
%
% \maketitle
% \tableofcontents
@@ -369,8 +369,9 @@
% 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
+% \item |--date| (|-d|) Date to use when tagging data
% \item |--debug| Runs the target in debug mode (not supported by all targets)
+% \item |--dev| Runs \LaTeX{} checks using the development format
% \item |--dirty| Skips cleaning up of the test area
% \item |--dry-run| Runs the \texttt{install} target but does not copy
% any files: simply lists those that would be installed
@@ -388,7 +389,7 @@
% \item |--message| (|-m|) Text for upload announcement
% \item |--quiet| (|-q|) Suppresses output from unpacking
% \item |--rerun| Runs tests without unpacking/set up
-% \item |--show-log-on-error| To be used in addition to \texttt{--halt-on-error} and results
+% \item |--show-log-on-error| To be used in addition to |--halt-on-error| and results
% in the full \texttt{.log} file of a failed test to be shown on the console
% \item |--show-saves| (|-S|) When tests fail, prints the \texttt{l3build save} commands needed
% to regenerate the tests assuming that the failures were false negatives.
@@ -432,7 +433,7 @@
% configurations are used and need adjustment to the standard engine, this does
% need to be given explicitly using \var{stdengine}.
% The format used for tests can be altered by setting \var{checkformat}: the default setting \texttt{latex} means that tests are run using \emph{e.g.}~\texttt{pdflatex}, whereas setting to \texttt{tex} will run tests using \emph{e.g.}~\texttt{pdftex}.
-% (Currently, this should be one of \texttt{latex}, \texttt{tex}, or
+% (Currently, this should be one of \texttt{latex}, \texttt{latex-dev}, \texttt{tex}, or
% \texttt{context}.)
% To perform the check, the engine typesets each test up to \var{checkruns} times.
% More detail on this in the documentation on |save|.
@@ -460,9 +461,19 @@
% \end{buildcmd}
%
% \begin{buildcmd}{clean}
-% This command removes all temporary files used for package bundling and regression testing.
-% In the standard layout, these are all files within the directories defined by \var{localdir}, \var{testdir}, \var{typesetdir} and \var{unpackdir}, as well as all files defined in the \var{cleanfiles} variable in the same directory as the script.
-% The defaults are |.pdf| files from typesetting (|doc|) and |.zip| files from bundling (|ctan|).
+% This target is meant as preparation for other targets, for example |ctan|.
+% It removes the contents of \var{distribdir} and all temporary files used for package bundling and regression testing.
+% These are all files within the directories \var{unpackdir}, \var{testdir}, \var{typesetdir} and \var{localdir}.
+% In addition, all the files in \var{maindir} (the directory of |build.lua| in the standard layout),
+% \var{sourcefiledir} and \var{docfiledir} are removed when matched by \var{cleanfiles}
+% but not by \var{sourcefiles}.
+% In a standard way are removed |.log| and |.pdf| files from the |doc| target and
+% |.zip| files from the |ctan| target.
+%
+% When applied to a bundle, the |clean| target is first applied to each
+% embedded modules (listed in |modules|).
+% In addition, all the files in the directory of |build.lua| are removed
+% when matched by \var{cleanfiles}, while ignoring \var{sourcefiles}. Finally |ctandir| and |tdsdir| are removed.
% \end{buildcmd}
%
%
@@ -667,7 +678,7 @@
% \end{floating-listing}
%
% A collection of full examples (source files in various layouts) are available
-% at \url{https://github.com/latex3/l3build/tree/master/examples}.
+% at \url{https://github.com/latex3/l3build/tree/main/examples}.
%
% \subsection{Variables}
%
@@ -791,7 +802,7 @@
% 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}.
+% \url{https://github.com/latex3/l3build/tree/main/examples}.
%
% For more complex layouts in which sources are laid out in TDS format and
% should be used directly, the table \var{tdsdirs} is available. Each entry
@@ -1227,9 +1238,9 @@
% \subsection{Settings in \texttt{texmf.cnf}}
%
% To allow application of non-standard \TeX{} trees or similar non-standard
-% settings, \pkg{l3build} enables searching for a \texttt{texmf.cnf} file
-% by setting the envirnmental variable \texttt{TEXMFCNF}. This might
-% for example be used with a file containing
+% settings, \pkg{l3build} sets the environment variable \texttt{TEXMFCNF}
+% to allow reading of any \texttt{texmf.cnf} file present in the support folder.
+% This might for example be used with a file containing
% \begin{verbatim}
% TEXMFAUXTREES = ../../texmf,
% \end{verbatim}
@@ -1662,35 +1673,42 @@
%
% \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.
+% command line. Each possible \meta{entry} given below corresponds to
+% |--|\meta{entry} given at the command line, except the |target| entry
+% which is self explanatory and the |names| entry which corresponds to \meta{name(s)}
+% for |check|, |doc|, |save| and |tag| targets.
% \begin{center}
% \begin{tabular}{ll}
% \toprule
-% Entry & Type \\
+% Entry & Lua type \\
% \midrule
-% \var{config} & Table \\
-% \var{date} & String \\
-% \var{dirty} & Boolean \\
-% \var{dry-run} & Boolean \\
-% \var{email} & String \\
-% \var{engine} & Table \\
-% \var{epoch} & String \\
-% \var{file} & string \\
-% \var{first} & Boolean \\
-% \var{full} & Boolean \\
-% \var{halt-on-error} & Boolean \\
-% \var{help} & Boolean \\
-% \var{message} & string \\
-% \var{names} & Table \\
-% \var{quiet} & Boolean \\
-% \var{rerun} & Boolean \\
-% \var{shuffle} & Boolean \\
-% \var{stdengine} & Boolean \\
-% \var{texmfhome} & String \\
+% \var{config} & |table| \\
+% \var{date} & |string| \\
+% \var{dirty} & |boolean| \\
+% \var{dry-run} & |boolean| \\
+% \var{email} & |string| \\
+% \var{engine} & |table| \\
+% \var{epoch} & |string| \\
+% \var{file} & |string| \\
+% \var{first} & |boolean| \\
+% \var{full} & |boolean| \\
+% \var{halt-on-error} & |boolean| \\
+% \var{help} & |boolean| \\
+% \var{message} & |string| \\
+% \var{names} & |table| \\
+% \var{quiet} & |boolean| \\
+% \var{rerun} & |boolean| \\
+% \var{shuffle} & |boolean| \\
+% \var{stdengine} & |boolean| \\
+% \var{target} & |string| \\
+% \var{texmfhome} & |string| \\
% \bottomrule
% \end{tabular}
% \end{center}
+% The Lua tables mentionned here are in fact arrays of strings.
+% From the |build.lua| file, one can modify the string and boolean values,
+% add or remove entries in arrays. But it is not recommended to affect a
+% whole new Lua table to |options| nor to its array entries.
% \end{variable}
%
% \subsection{Utility functions}
@@ -1946,7 +1964,7 @@
% |tex(|\meta{file},\meta{dir},\meta{cmd}|)|
% \end{syntax}
% Runs \meta{cmd} (by default \luavar{typesetexe} \luavar{typesetopts}) on the
-% \meta{name} inside the \meta{dir}.
+% \meta{file} inside the \meta{dir}.
% \end{function}
%
% \begin{function}{runcmd()}
@@ -2127,7 +2145,7 @@
% \begin{verbatim}
% manifest_extract_filedesc = function(filehandle,filename)
%
-% local all_file = filehandle:read("*all")
+% local all_file = filehandle:read("a")
% local matchstr = "\\section{(.-)}"
%
% filedesc = string.match(all_file,matchstr)
@@ -2288,8 +2306,8 @@
\ifnum\currentgrouplevel>0 %
\LONGTYPEOUT{Bad grouping: \the\currentgrouplevel!}%
\fi
- \ifnum\currentiflevel>2 %
- \LONGTYPEOUT{Bad conditionals: \the\numexpr\currentiflevel-2!}%
+ \ifnum\currentiflevel>1 %
+ \LONGTYPEOUT{Bad conditionals: \the\numexpr\currentiflevel-1!}%
\fi
\LONGTYPEOUT{^^JEND-TEST-LOG^^J}%
\@@@end