texlive[67658] trunk: l3build (17jul23)
commits+karl at tug.org
commits+karl at tug.org
Mon Jul 17 22:40:12 CEST 2023
Revision: 67658
http://tug.org/svn/texlive?view=revision&revision=67658
Author: karl
Date: 2023-07-17 22:40:11 +0200 (Mon, 17 Jul 2023)
Log Message:
-----------
l3build (17jul23)
Modified Paths:
--------------
trunk/Build/source/texk/texlive/linked_scripts/l3build/l3build.lua
trunk/Master/texmf-dist/doc/latex/l3build/CHANGELOG.md
trunk/Master/texmf-dist/doc/latex/l3build/README.md
trunk/Master/texmf-dist/doc/latex/l3build/l3build.pdf
trunk/Master/texmf-dist/doc/man/man1/l3build.1
trunk/Master/texmf-dist/doc/man/man1/l3build.man1.pdf
trunk/Master/texmf-dist/scripts/l3build/l3build-arguments.lua
trunk/Master/texmf-dist/scripts/l3build/l3build-aux.lua
trunk/Master/texmf-dist/scripts/l3build/l3build-check.lua
trunk/Master/texmf-dist/scripts/l3build/l3build-file-functions.lua
trunk/Master/texmf-dist/scripts/l3build/l3build-typesetting.lua
trunk/Master/texmf-dist/scripts/l3build/l3build-variables.lua
trunk/Master/texmf-dist/scripts/l3build/l3build.lua
trunk/Master/texmf-dist/source/latex/l3build/l3build.dtx
Modified: trunk/Build/source/texk/texlive/linked_scripts/l3build/l3build.lua
===================================================================
--- trunk/Build/source/texk/texlive/linked_scripts/l3build/l3build.lua 2023-07-17 20:39:57 UTC (rev 67657)
+++ trunk/Build/source/texk/texlive/linked_scripts/l3build/l3build.lua 2023-07-17 20:40:11 UTC (rev 67658)
@@ -25,7 +25,7 @@
--]]
-- 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 @@
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 @@
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 @@
testsuppdir = testfiledir .. "/support"
end
else
- print("Error: Cannot find configuration " .. configname .. ".lua")
+ print("Error: Cannot find configuration \"" .. configname .. ".lua\"")
exit(1)
end
end
Modified: trunk/Master/texmf-dist/doc/latex/l3build/CHANGELOG.md
===================================================================
--- trunk/Master/texmf-dist/doc/latex/l3build/CHANGELOG.md 2023-07-17 20:39:57 UTC (rev 67657)
+++ trunk/Master/texmf-dist/doc/latex/l3build/CHANGELOG.md 2023-07-17 20:40:11 UTC (rev 67658)
@@ -7,6 +7,20 @@
## [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 @@
### Fixed
- Apply needed luatex-specific log normalization, even when `--rerun` is used
- (issue #291)
+ (issue \#291)
## [2023-03-08]
@@ -30,6 +44,9 @@
- 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 @@
### 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 @@
### 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 @@
### 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 @@
## [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 @@
### Fixed
- When `checkruns` > 1 and `recordstatus=true`, testing code would crash
- (issue #90)
+ (issue \#90)
## [2020-02-03]
@@ -286,7 +303,7 @@
### Added
-- New `\ASSERT` and `\ASSERTSTR` functions (issue #102)
+- New `\ASSERT` and `\ASSERTSTR` functions (issue \#102)
### Changed
@@ -663,7 +680,8 @@
- 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
Modified: trunk/Master/texmf-dist/doc/latex/l3build/README.md
===================================================================
--- trunk/Master/texmf-dist/doc/latex/l3build/README.md 2023-07-17 20:39:57 UTC (rev 67657)
+++ trunk/Master/texmf-dist/doc/latex/l3build/README.md 2023-07-17 20:40:11 UTC (rev 67658)
@@ -1,7 +1,7 @@
l3build: a testing and building system for LaTeX
=================================================
-Release 2023-03-27
+Release 2023-07-17
Overview
--------
Modified: trunk/Master/texmf-dist/doc/latex/l3build/l3build.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/man/man1/l3build.1
===================================================================
--- trunk/Master/texmf-dist/doc/man/man1/l3build.1 2023-07-17 20:39:57 UTC (rev 67657)
+++ trunk/Master/texmf-dist/doc/man/man1/l3build.1 2023-07-17 20:40:11 UTC (rev 67658)
@@ -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
Modified: trunk/Master/texmf-dist/doc/man/man1/l3build.man1.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/scripts/l3build/l3build-arguments.lua
===================================================================
--- trunk/Master/texmf-dist/scripts/l3build/l3build-arguments.lua 2023-07-17 20:39:57 UTC (rev 67657)
+++ trunk/Master/texmf-dist/scripts/l3build/l3build-arguments.lua 2023-07-17 20:40:11 UTC (rev 67658)
@@ -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 @@
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)
Modified: trunk/Master/texmf-dist/scripts/l3build/l3build-aux.lua
===================================================================
--- trunk/Master/texmf-dist/scripts/l3build/l3build-aux.lua 2023-07-17 20:39:57 UTC (rev 67657)
+++ trunk/Master/texmf-dist/scripts/l3build/l3build-aux.lua 2023-07-17 20:40:11 UTC (rev 67658)
@@ -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 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 @@
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 @@
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
Modified: trunk/Master/texmf-dist/scripts/l3build/l3build-check.lua
===================================================================
--- trunk/Master/texmf-dist/scripts/l3build/l3build-check.lua 2023-07-17 20:39:57 UTC (rev 67657)
+++ trunk/Master/texmf-dist/scripts/l3build/l3build-check.lua 2023-07-17 20:40:11 UTC (rev 67658)
@@ -152,6 +152,9 @@
-- 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")
Modified: trunk/Master/texmf-dist/scripts/l3build/l3build-file-functions.lua
===================================================================
--- trunk/Master/texmf-dist/scripts/l3build/l3build-file-functions.lua 2023-07-17 20:39:57 UTC (rev 67657)
+++ trunk/Master/texmf-dist/scripts/l3build/l3build-file-functions.lua 2023-07-17 20:40:11 UTC (rev 67658)
@@ -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_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 @@
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"
Modified: trunk/Master/texmf-dist/scripts/l3build/l3build-typesetting.lua
===================================================================
--- trunk/Master/texmf-dist/scripts/l3build/l3build-typesetting.lua 2023-07-17 20:39:57 UTC (rev 67657)
+++ trunk/Master/texmf-dist/scripts/l3build/l3build-typesetting.lua 2023-07-17 20:40:11 UTC (rev 67658)
@@ -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,30 +31,9 @@
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) ..
@@ -61,7 +40,7 @@
"dvips " .. name .. dviext
.. (hide and (" > " .. os_null) or "")
.. os_concat ..
- "ps2pdf " .. ps2pdfopts .. name .. psext
+ "ps2pdf " .. ps2pdfopts .. " " .. name .. psext
.. (hide and (" > " .. os_null) or ""),
dir
)
Modified: trunk/Master/texmf-dist/scripts/l3build/l3build-variables.lua
===================================================================
--- trunk/Master/texmf-dist/scripts/l3build/l3build-variables.lua 2023-07-17 20:39:57 UTC (rev 67657)
+++ trunk/Master/texmf-dist/scripts/l3build/l3build-variables.lua 2023-07-17 20:40:11 UTC (rev 67658)
@@ -117,15 +117,16 @@
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
Modified: trunk/Master/texmf-dist/scripts/l3build/l3build.lua
===================================================================
--- trunk/Master/texmf-dist/scripts/l3build/l3build.lua 2023-07-17 20:39:57 UTC (rev 67657)
+++ trunk/Master/texmf-dist/scripts/l3build/l3build.lua 2023-07-17 20:40:11 UTC (rev 67658)
@@ -25,7 +25,7 @@
--]]
-- 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 @@
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 @@
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 @@
testsuppdir = testfiledir .. "/support"
end
else
- print("Error: Cannot find configuration " .. configname .. ".lua")
+ print("Error: Cannot find configuration \"" .. configname .. ".lua\"")
exit(1)
end
end
Modified: trunk/Master/texmf-dist/source/latex/l3build/l3build.dtx
===================================================================
--- trunk/Master/texmf-dist/source/latex/l3build/l3build.dtx 2023-07-17 20:39:57 UTC (rev 67657)
+++ trunk/Master/texmf-dist/source/latex/l3build/l3build.dtx 2023-07-17 20:40:11 UTC (rev 67658)
@@ -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,7 +594,7 @@
% 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}
@@ -582,7 +601,7 @@
% 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}.
+% shown in Listing~\vref{lst: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
+% \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
+% \begin{floating-listing}[caption={A customised PDF creation script.},label={lst:PDF}]
+% #!/usr/bin/env texlua
%
-% -- Build script with custom PDF route
+% -- Build script with custom PDF route
%
-% module = "mymodule"
+% 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
+% 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}
More information about the tex-live-commits
mailing list.