diff options
author | Karl Berry <karl@freefriends.org> | 2023-07-17 20:40:11 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2023-07-17 20:40:11 +0000 |
commit | 5e0bfde5d4b60579c356de905cf8878932b091e1 (patch) | |
tree | 1085da69b148558837ae7b55e6ff8f849258a901 /Master | |
parent | ba614240cb4c3d2e4f92a9521440b0e856d235fb (diff) |
l3build (17jul23)
git-svn-id: svn://tug.org/texlive/trunk@67658 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master')
-rw-r--r-- | Master/texmf-dist/doc/latex/l3build/CHANGELOG.md | 36 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/l3build/README.md | 2 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/l3build/l3build.pdf | bin | 743472 -> 744466 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/man/man1/l3build.1 | 2 | ||||
-rw-r--r-- | Master/texmf-dist/doc/man/man1/l3build.man1.pdf | bin | 14866 -> 14866 bytes | |||
-rw-r--r-- | Master/texmf-dist/scripts/l3build/l3build-arguments.lua | 4 | ||||
-rw-r--r-- | Master/texmf-dist/scripts/l3build/l3build-aux.lua | 35 | ||||
-rw-r--r-- | Master/texmf-dist/scripts/l3build/l3build-check.lua | 3 | ||||
-rw-r--r-- | Master/texmf-dist/scripts/l3build/l3build-file-functions.lua | 6 | ||||
-rw-r--r-- | Master/texmf-dist/scripts/l3build/l3build-typesetting.lua | 25 | ||||
-rw-r--r-- | Master/texmf-dist/scripts/l3build/l3build-variables.lua | 9 | ||||
-rwxr-xr-x | Master/texmf-dist/scripts/l3build/l3build.lua | 10 | ||||
-rw-r--r-- | Master/texmf-dist/source/latex/l3build/l3build.dtx | 386 |
13 files changed, 265 insertions, 253 deletions
diff --git a/Master/texmf-dist/doc/latex/l3build/CHANGELOG.md b/Master/texmf-dist/doc/latex/l3build/CHANGELOG.md index bcfd68115d9..23bdc92d9b4 100644 --- a/Master/texmf-dist/doc/latex/l3build/CHANGELOG.md +++ b/Master/texmf-dist/doc/latex/l3build/CHANGELOG.md @@ -7,6 +7,20 @@ this project uses date-based 'snapshot' version identifiers. ## [Unreleased] +## [2023-07-17] + +### Changed +- Improve stdout "Running l3build with target ..." +- Quote configuration name used in stdout +- Update one leftover outdated doc for `unpackexe`: defaults to `pdftex` +- Building pLaTeX format now uses e-upTeX engine +- Normalize more `luaotfload` path data (see issue \#301) +- Update ConTeXt settings to allow for LuaTeX and LuaMetaTeX runs +- Improve doc for default `stdengine` + +### Fixed +- Avoid setting `TEMXFCNF` for ConTeXt (issue \#232) + ## [2023-03-27] ### Fixed @@ -21,7 +35,7 @@ this project uses date-based 'snapshot' version identifiers. ### Fixed - Apply needed luatex-specific log normalization, even when `--rerun` is used - (issue #291) + (issue \#291) ## [2023-03-08] @@ -30,6 +44,9 @@ this project uses date-based 'snapshot' version identifiers. - Include UNIX timestamps in generated ZIP files - Normalize pdfTeX `.enc` file loading +### Fixed +- Ensure when used, value of `ps2pdfopts` is surrounded by a space on both sides + ## [2023-02-26] ### Changed @@ -38,7 +55,7 @@ this project uses date-based 'snapshot' version identifiers. ### Fixed - Restore epoch settings for `dvitopdf()` - Use plural form of variable `ps2pdfopts` consistently in code and doc, and - retain compatibility with singular form `ps2pdfopt` (issue #275) + retain compatibility with singular form `ps2pdfopt` (issue \#275) - Remove the last trace of dropped variable `stdconfig` ## [2023-02-20] @@ -125,7 +142,7 @@ this project uses date-based 'snapshot' version identifiers. ### Changed - If multiple configurations are present, let `l3build clean` run - on all of them by default. (issue #214) + on all of them by default. (issue \#214) ## [2021-12-06] @@ -144,7 +161,7 @@ this project uses date-based 'snapshot' version identifiers. ### Fixed - Installation of files when using MiKTeX (see #125) - Incorrect line in `manifest` target (see #195) -- Placement of PDF files in subdirectory locations (issue #209) +- Placement of PDF files in subdirectory locations (issue \#209) - Detection of engine-specific tlg files for non-standard LuaTeX based engines (issues #214) ## [2021-11-24] @@ -186,12 +203,12 @@ this project uses date-based 'snapshot' version identifiers. ## [2021-05-05] ### Changed -- Normalise Lua function calls (issue #127) - may require `.tlg` update +- Normalise Lua function calls (issue \#127) - may require `.tlg` update - LuaTeX from TL'21 is no longer 'off by one' in log files - may require `.tlg` update ### Fixed -- Installation now supports deeper directory levels (issue #182) +- Installation now supports deeper directory levels (issue \#182) - The `texmfhome` directory is now created before use if required - Crash caused by yyyy-mm-dd epoch format @@ -255,7 +272,7 @@ this project uses date-based 'snapshot' version identifiers. ### Fixed - When `checkruns` > 1 and `recordstatus=true`, testing code would crash - (issue #90) + (issue \#90) ## [2020-02-03] @@ -286,7 +303,7 @@ this project uses date-based 'snapshot' version identifiers. ### Added -- New `\ASSERT` and `\ASSERTSTR` functions (issue #102) +- New `\ASSERT` and `\ASSERTSTR` functions (issue \#102) ### Changed @@ -663,7 +680,8 @@ this project uses date-based 'snapshot' version identifiers. - Rationalise short option names: removed `-d`, `-E`, `-r` - Target `cmdcheck`: specific to LaTeX kernel work -[Unreleased]: https://github.com/latex3/l3build/compare/2023-03-27...HEAD +[Unreleased]: https://github.com/latex3/l3build/compare/2023-07-17...HEAD +[2023-07-17]: https://github.com/latex3/l3build/compare/2023-03-27...2023-07-17 [2023-03-27]: https://github.com/latex3/l3build/compare/2023-03-22...2023-03-27 [2023-03-22]: https://github.com/latex3/l3build/compare/2023-03-08...2023-03-22 [2023-03-08]: https://github.com/latex3/l3build/compare/2023-02-26...2023-03-08 diff --git a/Master/texmf-dist/doc/latex/l3build/README.md b/Master/texmf-dist/doc/latex/l3build/README.md index 2c898324b4d..27b742e167a 100644 --- a/Master/texmf-dist/doc/latex/l3build/README.md +++ b/Master/texmf-dist/doc/latex/l3build/README.md @@ -1,7 +1,7 @@ l3build: a testing and building system for LaTeX ================================================= -Release 2023-03-27 +Release 2023-07-17 Overview -------- diff --git a/Master/texmf-dist/doc/latex/l3build/l3build.pdf b/Master/texmf-dist/doc/latex/l3build/l3build.pdf Binary files differindex aea61f7b01f..6199bfa99d0 100644 --- a/Master/texmf-dist/doc/latex/l3build/l3build.pdf +++ b/Master/texmf-dist/doc/latex/l3build/l3build.pdf diff --git a/Master/texmf-dist/doc/man/man1/l3build.1 b/Master/texmf-dist/doc/man/man1/l3build.1 index 086181ab9b0..a4398b434e8 100644 --- a/Master/texmf-dist/doc/man/man1/l3build.1 +++ b/Master/texmf-dist/doc/man/man1/l3build.1 @@ -1,4 +1,4 @@ -.TH l3build 1 "2023-03-27" +.TH l3build 1 "2023-07-17" .SH NAME l3build \- Checking and building packages .SH SYNOPSIS diff --git a/Master/texmf-dist/doc/man/man1/l3build.man1.pdf b/Master/texmf-dist/doc/man/man1/l3build.man1.pdf Binary files differindex a4af9e08eb3..420b5fda364 100644 --- a/Master/texmf-dist/doc/man/man1/l3build.man1.pdf +++ b/Master/texmf-dist/doc/man/man1/l3build.man1.pdf diff --git a/Master/texmf-dist/scripts/l3build/l3build-arguments.lua b/Master/texmf-dist/scripts/l3build/l3build-arguments.lua index 76b661e26c6..c2a9263b325 100644 --- a/Master/texmf-dist/scripts/l3build/l3build-arguments.lua +++ b/Master/texmf-dist/scripts/l3build/l3build-arguments.lua @@ -1,6 +1,6 @@ --[[ -File l3build-arguments.lua Copyright (C) 2018-2021 The LaTeX Project +File l3build-arguments.lua Copyright (C) 2018-2021,2023 The LaTeX Project It may be distributed and/or modified under the conditions of the LaTeX Project Public License (LPPL), either version 1.3c of this @@ -300,7 +300,7 @@ function check_engines(config) end for _, engine in pairs(options["engine"]) do if not t[engine] then - print("\n! Error: Engine \"" .. engine .. "\" not set up for testing with configuration " .. config .. "!") + print("\n! Error: Engine \"" .. engine .. "\" not set up for testing with configuration \"" .. config .. "\"!") print("\n Valid values are:") for _, engine in ipairs(checkengines) do print(" - " .. engine) diff --git a/Master/texmf-dist/scripts/l3build/l3build-aux.lua b/Master/texmf-dist/scripts/l3build/l3build-aux.lua index 2f6902a7b02..5511802c160 100644 --- a/Master/texmf-dist/scripts/l3build/l3build-aux.lua +++ b/Master/texmf-dist/scripts/l3build/l3build-aux.lua @@ -1,6 +1,6 @@ --[[ -File l3build-aux.lua Copyright (C) 2018-2021 The LaTeX Project +File l3build-aux.lua Copyright (C) 2018-2021,2023 The LaTeX Project It may be distributed and/or modified under the conditions of the LaTeX Project Public License (LPPL), either version 1.3c of this @@ -32,6 +32,8 @@ local print = print local lookup = kpse.lookup local os_time = os.time +local os_type = os.type + -- -- Auxiliary functions which are used by more than one main function -- @@ -133,9 +135,9 @@ function call(modules, target, opts) for _, module in ipairs(modules) do local text if module == "." and opts["config"] and #opts["config"]>0 then - text = " with configuration " .. opts["config"][1] + text = " and configuration \"" .. opts["config"][1] .. "\"" else - text = " for module " .. module + text = " for module \"" .. module .. "\"" end print("Running l3build with target \"" .. target .. "\"" .. text ) local error_level = run( @@ -179,3 +181,30 @@ function localtexmf() end return paths end + +-- Run a command after setting up the environmental variables +function runcmd(cmd,dir,vars) + dir = dir or "." + dir = abspath(dir) + vars = vars or {} + -- Allow for local texmf files + local env = "" + if not match(checkformat,"^context$") then + env = os_setenv .. " TEXMFCNF=." .. os_pathsep .. os_concat + end + local envpaths = "." .. localtexmf() .. os_pathsep + .. abspath(localdir) .. os_pathsep + .. dir .. (typesetsearch and os_pathsep or "") + -- Deal with spaces in paths + if os_type == "windows" and match(envpaths," ") then + envpaths = gsub(envpaths,'"','') + end + for _,var in pairs(vars) do + if env ~= "" then + env = env .. os_setenv .. " " .. var .. "=" .. envpaths .. os_concat + else + env = os_setenv .. " " .. var .. "=" .. envpaths + end + end + return run(dir,set_epoch_cmd(epoch, forcedocepoch) .. env .. cmd) +end
\ No newline at end of file diff --git a/Master/texmf-dist/scripts/l3build/l3build-check.lua b/Master/texmf-dist/scripts/l3build/l3build-check.lua index d7430b2f5d2..b1c33c6d56c 100644 --- a/Master/texmf-dist/scripts/l3build/l3build-check.lua +++ b/Master/texmf-dist/scripts/l3build/l3build-check.lua @@ -152,6 +152,9 @@ local function normalize_log(content,engine,errlevels) -- luaotfload files start with keywords line = gsub(line, "from " .. pattern .. "$", "from ../%1") line = gsub(line, ": " .. pattern .. "%)", ": ../%1)") + -- More luaotfload + line = gsub(line, "database loaded from " .. pattern .. "%)", + "database loaded from ../%1)") -- Deal with XeTeX specials if match(line, "^%.+\\XeTeX.?.?.?file") then line = gsub(line, pattern, "../%1") diff --git a/Master/texmf-dist/scripts/l3build/l3build-file-functions.lua b/Master/texmf-dist/scripts/l3build/l3build-file-functions.lua index 841c05571ae..d6ec0cd5139 100644 --- a/Master/texmf-dist/scripts/l3build/l3build-file-functions.lua +++ b/Master/texmf-dist/scripts/l3build/l3build-file-functions.lua @@ -1,6 +1,6 @@ --[[ -File l3build-file-functions.lua Copyright (C) 2018-2022 The LaTeX Project +File l3build-file-functions.lua Copyright (C) 2018-2023 The LaTeX Project It may be distributed and/or modified under the conditions of the LaTeX Project Public License (LPPL), either version 1.3c of this @@ -130,8 +130,6 @@ os_setenv = "export" os_yes = "printf 'y\\n%.0s' {1..300}" os_ascii = "echo \"\"" -os_cmpexe = getenv("cmpexe") or "cmp" -os_cmpext = getenv("cmpext") or ".cmp" os_diffext = getenv("diffext") or ".diff" os_diffexe = getenv("diffexe") or "diff -c --strip-trailing-cr" os_grepexe = "grep" @@ -139,8 +137,6 @@ os_newline = "\n" if os_type == "windows" then os_ascii = "@echo." - os_cmpexe = getenv("cmpexe") or "fc /b" - os_cmpext = getenv("cmpext") or ".cmp" os_concat = "&" os_diffext = getenv("diffext") or ".fc" os_diffexe = getenv("diffexe") or "fc /n" diff --git a/Master/texmf-dist/scripts/l3build/l3build-typesetting.lua b/Master/texmf-dist/scripts/l3build/l3build-typesetting.lua index 2a7dbad510f..d0e491d4c59 100644 --- a/Master/texmf-dist/scripts/l3build/l3build-typesetting.lua +++ b/Master/texmf-dist/scripts/l3build/l3build-typesetting.lua @@ -1,6 +1,6 @@ --[[ -File l3build-typesetting.lua Copyright (C) 2018-2021 The LaTeX Project +File l3build-typesetting.lua Copyright (C) 2018-2021,2023 The LaTeX Project It may be distributed and/or modified under the conditions of the LaTeX Project Public License (LPPL), either version 1.3c of this @@ -31,37 +31,16 @@ local pairs = pairs local print = print local gsub = string.gsub -local match = string.match local os_type = os.type --- An auxiliary used to set up the environmental variables -function runcmd(cmd,dir,vars) - dir = dir or "." - dir = abspath(dir) - vars = vars or {} - -- Allow for local texmf files - local env = os_setenv .. " TEXMFCNF=." .. os_pathsep - local envpaths = "." .. localtexmf() .. os_pathsep - .. abspath(localdir) .. os_pathsep - .. dir .. (typesetsearch and os_pathsep or "") - -- Deal with spaces in paths - if os_type == "windows" and match(envpaths," ") then - envpaths = gsub(envpaths,'"','') - end - for _,var in pairs(vars) do - env = env .. os_concat .. os_setenv .. " " .. var .. "=" .. envpaths - end - return run(dir,set_epoch_cmd(epoch, forcedocepoch) .. env .. os_concat .. cmd) -end - function dvitopdf(name, dir, engine, hide) runcmd( set_epoch_cmd(epoch, forcecheckepoch) .. "dvips " .. name .. dviext .. (hide and (" > " .. os_null) or "") .. os_concat .. - "ps2pdf " .. ps2pdfopts .. name .. psext + "ps2pdf " .. ps2pdfopts .. " " .. name .. psext .. (hide and (" > " .. os_null) or ""), dir ) diff --git a/Master/texmf-dist/scripts/l3build/l3build-variables.lua b/Master/texmf-dist/scripts/l3build/l3build-variables.lua index 576fb15e82d..5ee366c0582 100644 --- a/Master/texmf-dist/scripts/l3build/l3build-variables.lua +++ b/Master/texmf-dist/scripts/l3build/l3build-variables.lua @@ -117,15 +117,16 @@ checkengines = checkengines or {"pdftex", "xetex", "luatex"} checkformat = checkformat or "latex" specialformats = specialformats or { } specialformats.context = specialformats.context or { - luatex = {binary = "context", format = ""}, - pdftex = {binary = "texexec", format = ""}, - xetex = {binary = "texexec", format = "", options = "--xetex"} + luametatex = {binary = "context", format = ""}, + luatex = {binary = "context", format = "", options = "--luatex"}, + pdftex = {binary = "texexec", format = ""}, + xetex = {binary = "texexec", format = "", options = "--xetex"} } specialformats.latex = specialformats.latex or { } specialformats.latex.etex = specialformats.latex.etex or {format = "latex"} specialformats.latex.ptex = specialformats.latex.ptex or - {binary = "eptex"} + {binary = "euptex"} specialformats.latex.uptex = specialformats.latex.uptex or {binary = "euptex"} if not string.find(status.banner,"2019") then diff --git a/Master/texmf-dist/scripts/l3build/l3build.lua b/Master/texmf-dist/scripts/l3build/l3build.lua index cefc59b905a..1124b9611f1 100755 --- a/Master/texmf-dist/scripts/l3build/l3build.lua +++ b/Master/texmf-dist/scripts/l3build/l3build.lua @@ -25,7 +25,7 @@ for those people who are interested. --]] -- Version information -release_date = "2023-03-27" +release_date = "2023-07-17" -- File operations are aided by the LuaFileSystem module local lfs = require("lfs") @@ -147,7 +147,7 @@ if #checkconfigs > 1 then end if next(failed) then for _,config in ipairs(failed) do - print("Failed tests for configuration " .. config .. ":") + print("Failed tests for configuration \"" .. config .. "\":") print("\n Check failed with difference files") local testdir = testdir if config ~= "build" then @@ -167,8 +167,8 @@ if #checkconfigs > 1 then end local f = open(testdir .. "/.savecommands") if not f then - print("Error: Cannot find save commands for configuration " .. - config) + print("Error: Cannot find save commands for configuration \"" .. + config .. "\"") exit(2) end for line in f:lines() do @@ -221,7 +221,7 @@ if #checkconfigs == 1 and testsuppdir = testfiledir .. "/support" end else - print("Error: Cannot find configuration " .. configname .. ".lua") + print("Error: Cannot find configuration \"" .. configname .. ".lua\"") exit(1) end end diff --git a/Master/texmf-dist/source/latex/l3build/l3build.dtx b/Master/texmf-dist/source/latex/l3build/l3build.dtx index d4d0abaa5cf..ca32296032e 100644 --- a/Master/texmf-dist/source/latex/l3build/l3build.dtx +++ b/Master/texmf-dist/source/latex/l3build/l3build.dtx @@ -111,7 +111,7 @@ \luavarset{unpackdeps} {\{\}}{List of dependencies for unpacking} \luavarseparator \luavarset{checkengines}{\{"pdftex", "xetex", "luatex"\}}{Engines to check with \texttt{check} by default} -\luavarset{stdengine} {"pdftex"}{Engine to generate \texttt{.tlg} file from} +\luavarset{stdengine} {checkengines[1] or "pdftex"}{Engine to generate \texttt{.tlg} file from} \luavarset{checkformat} {"latex"} {Format to use for tests} \luavarset{specialformats}{\meta{table}} {Non-standard engine/format combinations} \luavarset{\detokenize{test_types}} {\meta{table}} {Custom test variants} @@ -163,7 +163,7 @@ \luavarset{tdslocations}{\{ \}}{Map for non-standard file installations} \luavarset{tdsdirs}{\{ \}}{List of ready-to-use source locations} \luavarseparator -\luavarset{uploadconfig} {\meta{table}} {Metadata to describe the package for CTAN (see Table~\ref{tab:upload-setup})} +\luavarset{uploadconfig} {\meta{table}} {Metadata to describe the package for CTAN (see Table~\vref{tab:upload-setup})} \luavarset{uploadconfig.pkg}{ctanpkg}{Name of the CTAN package} \luavarseparator \luavarset{bakext}{".bak"}{Extension of backup files} @@ -212,9 +212,24 @@ basicstyle=\ttfamily\small, numbers=left, numberstyle={\tiny\color[gray]{0.4}}, + language={[5.2]Lua}, + gobble=4, } +\lstnewenvironment{floating-listing}[1][] +{% + \lstset{ + frame=single, + float, + captionpos=b, + abovecaptionskip=\bigskipamount, + floatplacement=htb, + #1 + }% +} +{} \usepackage{shortvrb} \usepackage{enumitem} +\usepackage[nospace]{varioref} \usepackage{longtable} \MakeShortVerb\| \begin{document} @@ -236,7 +251,7 @@ % }^^A % } % -% \date{Released 2023-03-27} +% \date{Released 2023-07-17} % % \maketitle % \tableofcontents @@ -254,7 +269,7 @@ % % The \pkg{l3build} system is designed for packages written in any \TeX\ dialect; its defaults are set up for \LaTeX\ packages written in the DocStrip style. (Caveat: minimal testing has yet been performed for non-\LaTeX{} packages.) % -% Test files are written as standalone \TeX{} documents using the |regression-test.tex| setup file; documentation on writing these tests is discussed in Section~\ref{sec:writing-tests}. +% Test files are written as standalone \TeX{} documents using the |regression-test.tex| setup file; documentation on writing these tests is discussed in Section~\vref{sec:writing-tests}. % % Each package will define its own |build.lua| configuration file which both sets variables (such as the name of the package) and may also provide custom functions. % @@ -324,7 +339,7 @@ % variable settings \emph{or} additional code to customize the build % process. % -%The example scripts given in Section~\ref{sec:examples} largely cover the required knowledge in Lua programing. +%The example scripts given in Section~\vref{sec:examples} largely cover the required knowledge in Lua programing. % For a more advanced usage, one may consult general Lua documentations including \url{http://www.lua.org/manual/5.3/manual.html} and for the few |texlua| specific additions see section 4.2 of the \LuaTeX{} manual available locally with |texdoc luatex| command line or at \url{https://www.pragma-ade.com/general/manuals/luatex.pdf}. % % \subsection{Main build targets} @@ -412,7 +427,11 @@ % This range of possibilities allow sensible defaults but significant flexibility for defining your own test setups. % % Checking can be performed with any or all of the `engines' \texttt{pdftex}, \texttt{xetex}, and \texttt{luatex}. -% By default, each test is executed with all three, being compared against the \texttt{.tlg} file produced from the \var{pdftex} engine (these defaults are controlled by the |checkengines| and |stdengine| variable respectively). +% By default, each test is executed with all three, being compared against the \texttt{.tlg} file produced from the \var{pdftex} engine (these defaults are controlled by the |checkengines| and |stdengine| variable, respectively). +% The standard engine to use is typically chosen automatically as the first entry in +% \var{checkengines}, but may be set manually using \var{stdengine}. Where multiple +% 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} or \texttt{tex}.) % To perform the check, the engine typesets each test up to \var{checkruns} times. @@ -538,7 +557,7 @@ % This file is then used in all subsequent checks against the \texttt{\meta{name}.lvt} test. % % If the |--engine| (or |-e|) is specified (one of |pdftex|, |xetex|, or |luatex|), the saved output is stored in \texttt{\meta{name}.\meta{engine}.tlg}. This is necessary if running the test through a different engine produces a different output. -% A normalisation process is performed when checking to avoid common differences such as register allocation; full details are listed in section~\ref{sec:norm}. +% A normalisation process is performed when checking to avoid common differences such as register allocation; full details are listed in Section~\vref{sec:norm}. % % If the \var{recordstatus} variable is set \var{true}, additional information % will be added to the \texttt{.tlg} to record the \enquote{exit status} of the @@ -555,7 +574,7 @@ % This would allow, say, for the copyright statement for the package to refer to the % manifest file rather than requiring the author to manually keep a file list up-to-date % in multiple locations. The manifest file can be structured and documented with a degree -% of flexibility. Additional information is described in Section~\ref{sec:manifest}. +% of flexibility. Additional information is described in Section~\vref{sec:manifest}. % % In order for \texttt{manifest} to detect derived and typeset files, it should be run % \emph{after} running \texttt{unpack} and \texttt{doc}. If \texttt{manifest} @@ -575,14 +594,14 @@ % ISO format (YYYY-MM-DD). If no \meta{tag name} is given, the tag will default to |nil|. % Both are passed as arguments to the |update_tag()| function. % -% The standard setup does nothing unless tag update is set up by defining a custom |update_tag()| function. See Section~\ref{sec:tagging} for full details on this feature. +% The standard setup does nothing unless tag update is set up by defining a custom |update_tag()| function. See Section~\vref{sec:tagging} for full details on this feature. % \end{buildcmd} % % \begin{buildcmd}{unpack} % This is an internal target that is normally not needed on user level. % It unpacks all files into the directory defined by \var{unpackdir}. This occurs before other build commands such as |doc|, |check|, etc. % -% The unpacking process is performed by executing the \var{unpackexe} (default \texttt{tex}) with options \var{unpackopts} on all files defined by the \var{unpackfiles} variable; by default, all files that match \luavar{unpackfiles}. +% The unpacking process is performed by executing the \var{unpackexe} (default \texttt{pdftex}) with options \var{unpackopts} on all files defined by the \var{unpackfiles} variable; by default, all files that match \luavar{unpackfiles}. % % If additional support files are required for the unpacking process, these can be enumerated in the \var{unpacksuppfiles} variable. % Dependencies for unpacking are defined with \var{unpackdeps}. @@ -593,67 +612,55 @@ % \begin{buildcmd}{upload [\meta{version}]} % This target uses \texttt{curl} to upload the package zip file (created using \texttt{ctan}) to CTAN. % To control the metadata used to upload the package, the \texttt{uploadconfig} table should be populated with a number of fields. -% These are documented in Table~\ref{tab:upload-setup}. +% These are documented in Table~\vref{tab:upload-setup}. % Missing required fields will result in an interactive prompt for manual entry. When given, \meta{version} overrides \texttt{uploadconfig.version}. % -% See Section~\ref{sec:upload} for full details on this feature. +% See Section~\vref{sec:upload} for full details on this feature. % \end{buildcmd} % % \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}. +% An example of a standalone build script for a package that uses self-contained |.dtx| files is shown in Listing~\vref{lst: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. % -% \begin{figure}[!b] -% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6] -% -- Build configuration for breqn +% \begin{floating-listing}[caption=The build configuration for the \pkg{breqn} package.,label=lst:breqn] +% -- Build configuration for breqn % -% module = "breqn" +% module = "breqn" % -% unpackfiles = {"*.dtx"} -% excludefiles = {"*/breqn-abbr-test.pdf", -% "*/eqbreaks.pdf"} -% unpackopts = "-interaction=batchmode" -% \end{lstlisting} -% \caption{The build configuration for the \pkg{breqn} package.} -% \label{fig:breqn} -% \end{figure} +% unpackfiles = {"*.dtx"} +% excludefiles = {"*/breqn-abbr-test.pdf", +% "*/eqbreaks.pdf"} +% unpackopts = "-interaction=batchmode" +% \end{floating-listing} % -% An example of a bundle build script for \pkg{l3packages} is shown in Figure~\ref{fig:bundle}. +% An example of a bundle build script for \pkg{l3packages} is shown in Listing~\vref{lst:bundle}. % Note for \LaTeX{} we use a common file to set all build variables in one place, and the path to the |l3build.lua| script is hard-coded so we always use our own most recent version of the script. -% An example of an accompanying module build script is shown in Figure~\ref{fig:module}. +% An example of an accompanying module build script is shown in Listing~\vref{lst:module}. % -% \begin{figure}[p] -% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6] -% -- Build script for LaTeX "l3packages" files +% \begin{floating-listing}[caption={The build script for the \pkg{l3packages} bundle.},label={lst:bundle}] +% -- Build script for LaTeX "l3packages" files % -% -- Identify the bundle: there is no module as this is the "driver" -% bundle = "l3packages" +% -- Identify the bundle: there is no module as this is the "driver" +% bundle = "l3packages" % -% -- Location of main directory: use Unix-style path separators -% maindir = ".." -% \end{lstlisting} -% \caption{The build script for the \pkg{l3packages} bundle.} -% \label{fig:bundle} -% \end{figure} +% -- Location of main directory: use Unix-style path separators +% maindir = ".." +% \end{floating-listing} % -% \begin{figure}[p] -% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6] -% -- Build script for LaTeX "xparse" files +% \begin{floating-listing}[caption={The build script for the \pkg{xparse} module.},label={lst:module}] +% -- Build script for LaTeX "xparse" files % -% -- Identify the bundle and module: -% bundle = "l3packages" -% module = "xparse" +% -- Identify the bundle and module: +% bundle = "l3packages" +% module = "xparse" % -% -- Location of main directory: use Unix-style path separators -% -- Should match that defined by the bundle. -% maindir = "../.." -% \end{lstlisting} -% \caption{The build script for the \pkg{xparse} module.} -% \label{fig:module} -% \end{figure} +% -- Location of main directory: use Unix-style path separators +% -- Should match that defined by the bundle. +% maindir = "../.." +% \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}. @@ -673,6 +680,14 @@ % tests such that they do not use the same names for such files: this may lead % to variable outcomes depending on the order in which tests are run. % +% Where files need to be removed between different engine tests, they should +% be listed in |dynamicfiles|. If the files are generated in a directory +% structure, e.g.~by \pkg{minted}, then a recursive glob will be needed, +% for example +% \begin{Verbatim} +% dynamicfiles = {"_minted-*/**"} +% \end{Verbatim} +% % \subsection{Selective running of tests} % % The variables |includetests| and |excludetests| may be used to select which @@ -696,22 +711,18 @@ % For example, for the core \LaTeXe{} tests the main test files are contained % in a directory |testfiles|. To test font loading for \XeTeX{} and \LuaTeX{} % there are a second set of tests in |testfiles-TU| which use the short -% |build-TU.lua| file shown in Figure~\ref{fig:configs}. To run both sets of +% |build-TU.lua| file shown in Listing~\vref{lst:configs}. To run both sets of % tests, the main |build.lua| file contains the setting % |checkconfigs = {"build", "config-TU"}|. This will cause \pkg{l3build} to run % first using no additional settings (\emph{i.e.}~reading the normal % |build.lua| file alone), then running \emph{also} loading the settings from % |config-TU.lua|. -% \begin{figure} -% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6] -% -- Special config for these tests -% checksearch = true -% checkengines = {"xetex","luatex"} -% testfiledir = "testfiles-TU" -% \end{lstlisting} -% \caption{Example of using additional (or overriding) settings for configuring tests in a different subdirectory.} -% \label{fig:configs} -% \end{figure} +% \begin{floating-listing}[caption={Example of using additional (or overriding) settings for configuring tests in a different subdirectory.},label={lst:configs}] +% -- Special config for these tests +% checksearch = true +% checkengines = {"xetex","luatex"} +% testfiledir = "testfiles-TU" +% \end{floating-listing} % % To allow selection of one or more configurations, and to allow saving of % |.tlg| files in non-standard configurations, the |--config| (|-c|) option may @@ -908,7 +919,7 @@ % % \subsubsection{Release 2023-03-22} % -% This release changes the standard value of \var{maxprintline} for $79$ to +% This release changes the standard value of \var{maxprintline} from $79$ to % $9999$, to suppress line wrapping in the log. This makes normalisation of % for example file paths more reliable. To check that \texttt{.tlg} files % are correct, you can set \var{maxprintline} in your \texttt{build.lua} file @@ -951,9 +962,13 @@ % \item % \cs{ERROR} is \emph{not} defined but is commonly used to indicate a code path that should never be reached. % \item -% The \cs{TEST}\marg{title}\marg{contents} command surrounds its \meta{contents} with some \cs{SEPARATOR}s and a \meta{title}. +% The \cs{TEST}\marg{title}\marg{contents} command runs its \meta{contents} +% in a group and surrounds the generated log lines with some \cs{SEPARATOR}s +% and a \meta{title}. % \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. +% \cs{TESTEXP}\marg{title}\marg{contents} surrounds its \meta{contents} with +% \cs{TYPE} and formatting to match \cs{TEST}; this can be used as a shorthand +% to test expandable commands. % \item % \cs{BEGINTEST}\marg{title} \dots \cs{ENDTEST} is an environment form of % \cs{TEST}, allowing verbatim material, \emph{etc.} to appear. @@ -1008,7 +1023,7 @@ % \showbox0 % \END % \end{Verbatim} -% This produces the output shown in Figure~\ref{fig:box-log} (left side). +% This produces the output shown in Figure~\vref{fig:box-log} (left side). % It is clear that if the definitions used to typeset the material in the box changes, the log output will differ and the test will no longer pass. % % The equivalent test in \LaTeXe{} using \pkg{expl3} is similar. @@ -1024,7 +1039,7 @@ % \ExplSyntaxOff % \END % \end{Verbatim} -% The output from this test is shown in Figure~\ref{fig:box-log} (right side). +% The output from this test is shown in Figure~\vref{fig:box-log} (right side). % There is marginal difference (mostly related to font selection and different logging settings in \LaTeX) between the plain and \pkg{expl3} versions. % % When examples are not self-contained enough to be typeset into boxes, it is possible to ask \TeX{} to output the entire contents of a page. @@ -1141,20 +1156,16 @@ % If more than one task is required, these should be separated % by use of |os_concat|, a string variable defined by \pkg{l3build} as the % correct concatenation marker for the system. An example of |runtest_tasks| -% suitable for calling Biber is shown in Listing~\ref{fig:test-tasks}. -% \begin{figure} -% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6] -% function runtest_tasks(name,run) -% if run == 1 then -% return "biber " .. name -% else -% return "" -% end +% suitable for calling Biber is shown in Listing~\vref{lst:test-tasks}. +% \begin{floating-listing}[caption={Example \texttt{runtest_tasks} function.},label={lst:test-tasks}] +% function runtest_tasks(name,run) +% if run == 1 then +% return "biber " .. name +% else +% return "" % end -% \end{lstlisting} -% \caption{Example \texttt{runtest_tasks} function.} -% \label{fig:test-tasks} -% \end{figure} +% end +% \end{floating-listing} % % \subsection{Instructions for rebuilding test output} % @@ -1231,42 +1242,32 @@ % differ. % % Combining both features enables contrasting the test with its expected -% outcome in a compact format. Listing \ref{fig:expect-dtx} exemplary tests -% \TeX{}s counters. Listing \ref{fig:expect-ins} shows the relevant part of an +% outcome in a compact format. Listing~\vref{lst:expect-dtx} exemplary tests +% \TeX{}s counters. Listing~\vref{lst:expect-ins} shows the relevant part of an % \texttt{.ins} file to generate it. % -% \begin{figure} -% \begin{lstlisting}[frame=single,language={TeX},gobble = 6] -% \input regression-test.tex\relax -% \START -% \TEST{counter-math}{ -% %<*test> -% \OMIT -% \newcounter{numbers} -% \setcounter{numbers}{2} -% \addtocounter{numbers}{2} -% \stepcounter{numbers} -% \TIMO -% \typeout{\arabic{numbers}} -% %</test> -% %<expect> \typeout{5} -% } -% \END -% \end{lstlisting} -% \caption{Test and expectation can be specified side-by-side in a single -% \texttt{.dtx} file.} -% \label{fig:expect-dtx} -% \end{figure} +% \begin{floating-listing}[language={TeX},caption={Test and expectation can be specified side-by-side in a single \texttt{.dtx} file.},label={lst:expect-dtx}] +% \input regression-test.tex\relax +% \START +% \TEST{counter-math}{ +% %<*test> +% \OMIT +% \newcounter{numbers} +% \setcounter{numbers}{2} +% \addtocounter{numbers}{2} +% \stepcounter{numbers} +% \TIMO +% \typeout{\arabic{numbers}} +% %</test> +% %<expect> \typeout{5} +% } +% \END +% \end{floating-listing} % -%\begin{figure} -% \begin{lstlisting}[frame=single,language={TeX},gobble = 6] -% \generate{\file{\jobname.lvt}{\from{\jobname.dtx}{test}} -% \file{\jobname.lve}{\from{\jobname.dtx}{expect}}} -% \end{lstlisting} -% \caption{Test and expectation are generated from a \texttt{.dtx} file of -% the same name.} -% \label{fig:expect-ins} -% \end{figure} +% \begin{floating-listing}[language={TeX},caption={Test and expectation are generated from a \texttt{.dtx} file of the same name.},label={lst:expect-ins}] +% \generate{\file{\jobname.lvt}{\from{\jobname.dtx}{test}} +% \file{\jobname.lve}{\from{\jobname.dtx}{expect}}} +% \end{floating-listing} % % \subsection{PDF-based tests} % @@ -1351,19 +1352,15 @@ % TDS position of a file or files. Any files not specified in the table % will use the standard locations above. For example, to place some files % in the generic tree, some in the plain \TeX{} tree and some in the \LaTeX{} -% 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 = -% { -% "tex/generic/mypkg/*.generic.tex" , -% "tex/plain/mypkg/*.plain.tex" , -% "tex/latex/mypkg/*.latex.tex" -% } -% \end{lstlisting} -% \caption{Example \texttt{tdslocations} table.} -% \label{fig:tds} -% \end{figure} +% tree, one might use the set up shown in Listing~\vref{lst:tds}. +% \begin{floating-listing}[caption={Example \texttt{tdslocations} table.},label={lst:tds}] +% tdslocations = +% { +% "tex/generic/mypkg/*.generic.tex" , +% "tex/plain/mypkg/*.plain.tex" , +% "tex/latex/mypkg/*.latex.tex" +% } +% \end{floating-listing} % % The table is read in order, and thus specific file names should come before % potential wild-card matches. @@ -1384,31 +1381,27 @@ % The |update_tag()| function should return the (modified) contents % for writing to disk. % For example, the function used by |l3build| itself is -% shown in Figure~\ref{fig:update-tag}. -% -% \begin{figure} -% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6] -% -- Detail how to set the version automatically -% function update_tag(file,content,tagname,tagdate) -% if string.match(file, "%.dtx$") then -% return string.gsub(content, -% "\n%% \\date{Released %d%d%d%d/%d%d/%d%d}\n", -% "\n%% \\date{Released " .. tagname .. "}\n") -% elseif string.match(file, "%.md$") then -% return string.gsub(content, -% "\nRelease %d%d%d%d/%d%d/%d%d\n", -% "\nRelease " .. tagname .. "\n") -% elseif string.match(file, "%.lua$") then -% return string.gsub(content, -% '\nrelease_date = "%d%d%d%d/%d%d/%d%d"\n', -% '\nrelease_date = "' .. tagname .. '"\n') -% end -% return content +% shown in Listing~\vref{lst:update-tag}. +% +% \begin{floating-listing}[caption={Example \texttt{update_tag} function.},label={lst:update-tag}] +% -- Detail how to set the version automatically +% function update_tag(file,content,tagname,tagdate) +% if string.match(file, "%.dtx$") then +% return string.gsub(content, +% "\n%% \\date{Released %d%d%d%d/%d%d/%d%d}\n", +% "\n%% \\date{Released " .. tagname .. "}\n") +% elseif string.match(file, "%.md$") then +% return string.gsub(content, +% "\nRelease %d%d%d%d/%d%d/%d%d\n", +% "\nRelease " .. tagname .. "\n") +% elseif string.match(file, "%.lua$") then +% return string.gsub(content, +% '\nrelease_date = "%d%d%d%d/%d%d/%d%d"\n', +% '\nrelease_date = "' .. tagname .. '"\n') % end -% \end{lstlisting} -% \caption{Example \texttt{update_tag} function.} -% \label{fig:update-tag} -% \end{figure} +% return content +% end +% \end{floating-listing} % % To allow more complex tasks to take place, a hook |tag_hook()| is also % available. It will receive the tag name and date as arguments, and @@ -1437,7 +1430,7 @@ % any extension. The \texttt{tex} takes as an argument the full name % of the file. The most complex function \texttt{makeindex} requires the % name, input extension, output extension, log extension and style name. -% For example, Figure~\ref{fig:PDF} shows a simple script which might +% For example, Listing~\vref{lst:PDF} shows a simple script which might % apply to a case where multiple \BibTeX{} runs are needed (perhaps where % citations can appear within other references). % @@ -1449,33 +1442,29 @@ % 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] -% #!/usr/bin/env texlua -% -% -- Build script with custom PDF route -% -% module = "mymodule" -% -% function typeset(file) -% local name = jobname(file) -% local errorlevel = tex (file) -% if errorlevel == 0 then -% -- Return a non-zero errorlevel if anything goes wrong -% errorlevel =( -% bibtex(name) + -% tex(file) + -% bibtex(name) + -% tex(file) + -% tex(file) -% ) -% end -% return errorlevel +% \begin{floating-listing}[caption={A customised PDF creation script.},label={lst:PDF}] +% #!/usr/bin/env texlua +% +% -- Build script with custom PDF route +% +% module = "mymodule" +% +% function typeset(file) +% local name = jobname(file) +% local errorlevel = tex (file) +% if errorlevel == 0 then +% -- Return a non-zero errorlevel if anything goes wrong +% errorlevel =( +% bibtex(name) + +% tex(file) + +% bibtex(name) + +% tex(file) + +% tex(file) +% ) % end -% \end{lstlisting} -% \caption{A customised PDF creation script.} -% \label{fig:PDF} -% \end{figure} +% return errorlevel +% end +% \end{floating-listing} % % \subsection{Pre-typesetting hook} % @@ -1507,9 +1496,9 @@ % The CTAN upload process is backed by an API, which \pkg{l3build} can use % to send zip files for release. Along with the file, a variety of metadata % must be specified about the package, including the version, license, and so on, explained at \url{https://www.ctan.org/upload}. -% A description of this metadata is outlined in Table~\ref{tab:upload-setup}, +% A description of this metadata is outlined in Table~\vref{tab:upload-setup}, % and a simple example of an extract from a \texttt{build.lua} file using this is shown -% in Figure~\ref{fig:uploadconfig}. +% in Listing~\vref{lst:uploadconfig}. % % Note that the \texttt{upload} target will \emph{not} execute the % \texttt{ctan} target first. @@ -1632,22 +1621,18 @@ % \end{table} % % -% \begin{figure}[p] -% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6] -% uploadconfig = { -% pkg = "vertbars", -% version = "v1.0c", -% author = "Peter R Wilson; Will Robertson", -% license = "lppl1.3c", -% summary = "Mark vertical rules in margin of text", -% ctanPath = "/macros/latex/contrib/vertbars", -% repository = "https://github.com/wspr/herries-press/", -% update = true, -% } -% \end{lstlisting} -% \caption{Example of \texttt{uploadconfig} from the \pkg{vertbars} package.} -% \label{fig:uploadconfig} -% \end{figure} +% \begin{floating-listing}[caption={Example of \texttt{uploadconfig} from the \pkg{vertbars} package.},label={lst:uploadconfig}] +% uploadconfig = { +% pkg = "vertbars", +% version = "v1.0c", +% author = "Peter R Wilson; Will Robertson", +% license = "lppl1.3c", +% summary = "Mark vertical rules in margin of text", +% ctanPath = "/macros/latex/contrib/vertbars", +% repository = "https://github.com/wspr/herries-press/", +% update = true, +% } +% \end{floating-listing} % % \section{Lua interfaces} % @@ -1990,13 +1975,13 @@ % target attempt to reflect the defaults for \pkg{l3build} itself. % The groups (and hence the files) displayed can be completely % customised by defining a new setup function which creates a Lua table with -% the appropriate settings (\S\ref{sec:manifest-groups}). +% the appropriate settings (Section~\vref{sec:manifest-groups}). % % The formatting within the manifest file can be customised by redefining a number % of Lua functions. This includes -% how the files are sorted within each group (\S\ref{sec:manifest-sorting}), -% the inclusion of one-line descriptions for each file (\S\ref{sec:manifest-desc}), -% and the details of the formatting of each entry (\S\ref{sec:manifest-formatting}). +% how the files are sorted within each group (Section~\vref{sec:manifest-sorting}), +% the inclusion of one-line descriptions for each file (Section~\vref{sec:manifest-desc}), +% and the details of the formatting of each entry (Section~\vref{sec:manifest-formatting}). % % To perform such customisations, either include the re-definitions directly within your % package's |build.lua| file, or make a copy of |l3build-manifest-setup.lua|, rename it, @@ -2039,7 +2024,8 @@ % % The |groups| variable is an ordered array of tables which contain the metadata about each % `group' in the manifest listing. -% The keys supported in these tables are outlined in Table~\ref{tab:manifest-setup} and Table~\ref{tab:manifest-subheadings} +% The keys supported in these tables are outlined in +% Tables~\vref{tab:manifest-setup} and~\vref{tab:manifest-subheadings}. % See the complete setup code in |l3build-manifest-setup.lua| for examples of these in use. % % \begin{table} |