[latex3-commits] [latex3/l3build] main: Documentation improved (b5e5c5f)
github at latex-project.org
github at latex-project.org
Sun Jul 16 20:22:53 CEST 2023
Repository : https://github.com/latex3/l3build
On branch : main
Link : https://github.com/latex3/l3build/commit/b5e5c5f43497b925d33a5bbbc35b67079bcdf140
>---------------------------------------------------------------
commit b5e5c5f43497b925d33a5bbbc35b67079bcdf140
Author: Denis Bitouzé <dbitouze at wanadoo.fr>
Date: Tue Mar 7 19:11:44 2023 +0100
Documentation improved
>---------------------------------------------------------------
b5e5c5f43497b925d33a5bbbc35b67079bcdf140
l3build.dtx | 133 ++++++++++++++++++++++--------------------------------------
1 file changed, 49 insertions(+), 84 deletions(-)
diff --git a/l3build.dtx b/l3build.dtx
index 1741124..53b7eca 100644
--- a/l3build.dtx
+++ b/l3build.dtx
@@ -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 \vref{tab:upload-setup})}
\luavarset{uploadconfig.pkg}{ctanpkg}{Name of the CTAN package}
\luavarseparator
\luavarset{bakext}{".bak"}{Extension of backup files}
@@ -212,10 +212,15 @@
basicstyle=\ttfamily\small,
numbers=left,
numberstyle={\tiny\color[gray]{0.4}},
+ captionpos=b,
+ abovecaptionskip=\bigskipamount,
+ floatplacement=htb,
}
\usepackage{shortvrb}
\usepackage{enumitem}
+\usepackage[nospace]{varioref}
\usepackage{longtable}
+\usepackage[noabbrev]{cleveref}
\MakeShortVerb\|
\begin{document}
\DocInput{\jobname.dtx}
@@ -254,7 +259,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 \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 +329,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 \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}
@@ -538,7 +543,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 \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 +560,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 \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 +580,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 \vref{sec:tagging} for full details on this feature.
% \end{buildcmd}
%
% \begin{buildcmd}{unpack}
@@ -593,21 +598,20 @@
% \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 \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 \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 \vref{fig: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]
+% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6,float,label=fig:breqn,caption=The build configuration for the \pkg{breqn} package.]
% -- Build configuration for breqn
%
% module = "breqn"
@@ -617,16 +621,12 @@
% "*/eqbreaks.pdf"}
% unpackopts = "-interaction=batchmode"
% \end{lstlisting}
-% \caption{The build configuration for the \pkg{breqn} package.}
-% \label{fig:breqn}
-% \end{figure}
%
-% 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 \vref{fig: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 \vref{fig:module}.
%
-% \begin{figure}[p]
-% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6]
+% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6,float,caption={The build script for the \pkg{l3packages} bundle.},label={fig:bundle}]
% -- Build script for LaTeX "l3packages" files
%
% -- Identify the bundle: there is no module as this is the "driver"
@@ -635,12 +635,8 @@
% -- 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}
%
-% \begin{figure}[p]
-% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6]
+% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6,float,caption={The build script for the \pkg{xparse} module.},label={fig:module}]
% -- Build script for LaTeX "xparse" files
%
% -- Identify the bundle and module:
@@ -651,9 +647,6 @@
% -- Should match that defined by the bundle.
% maindir = "../.."
% \end{lstlisting}
-% \caption{The build script for the \pkg{xparse} module.}
-% \label{fig:module}
-% \end{figure}
%
% A collection of full examples (source files in various layouts) are available
% at \url{https://github.com/latex3/l3build/tree/master/examples}.
@@ -696,22 +689,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 \vref{fig: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]
+% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6,float,caption={Example of using additional (or overriding) settings for configuring tests in a different subdirectory.},label={fig:configs}]
% -- 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}
%
% To allow selection of one or more configurations, and to allow saving of
% |.tlg| files in non-standard configurations, the |--config| (|-c|) option may
@@ -1012,7 +1001,7 @@
% \showbox0
% \END
% \end{Verbatim}
-% This produces the output shown in Figure~\ref{fig:box-log} (left side).
+% This produces the output shown in \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.
@@ -1028,7 +1017,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 \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.
@@ -1145,9 +1134,8 @@
% 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]
+% suitable for calling Biber is shown in \vref{fig:test-tasks}.
+% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6,float,caption={Example \texttt{runtest_tasks} function.},label={fig:test-tasks}]
% function runtest_tasks(name,run)
% if run == 1 then
% return "biber " .. name
@@ -1156,9 +1144,6 @@
% end
% end
% \end{lstlisting}
-% \caption{Example \texttt{runtest_tasks} function.}
-% \label{fig:test-tasks}
-% \end{figure}
%
% \subsection{Instructions for rebuilding test output}
%
@@ -1235,12 +1220,11 @@
% 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. \Vref{fig:expect-dtx} exemplary tests
+% \TeX{}s counters. \Vref{fig:expect-ins} shows the relevant part of an
% \texttt{.ins} file to generate it.
%
-% \begin{figure}
-% \begin{lstlisting}[frame=single,language={TeX},gobble = 6]
+% \begin{lstlisting}[frame=single,language={TeX},gobble = 6,float,caption={Test and expectation can be specified side-by-side in a single \texttt{.dtx} file.},label={fig:expect-dtx}]
% \input regression-test.tex\relax
% \START
% \TEST{counter-math}{
@@ -1257,20 +1241,11 @@
% }
% \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{figure}
-% \begin{lstlisting}[frame=single,language={TeX},gobble = 6]
+% \begin{lstlisting}[frame=single,language={TeX},gobble = 6,float,caption={Test and expectation are generated from a \texttt{.dtx} file of the same name.},label={fig:expect-ins}]
% \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}
%
% \subsection{PDF-based tests}
%
@@ -1355,9 +1330,8 @@
% 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]
+% tree, one might use the set up shown in \vref{fig:tds}.
+% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6,float,caption={Example \texttt{tdslocations} table.},label={fig:tds}]
% tdslocations =
% {
% "tex/generic/mypkg/*.generic.tex" ,
@@ -1365,9 +1339,6 @@
% "tex/latex/mypkg/*.latex.tex"
% }
% \end{lstlisting}
-% \caption{Example \texttt{tdslocations} table.}
-% \label{fig:tds}
-% \end{figure}
%
% The table is read in order, and thus specific file names should come before
% potential wild-card matches.
@@ -1388,10 +1359,9 @@
% 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 \vref{fig:update-tag}.
%
-% \begin{figure}
-% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6]
+% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6,float,caption={Example \texttt{update_tag} function.},label={fig:update-tag}]
% -- Detail how to set the version automatically
% function update_tag(file,content,tagname,tagdate)
% if string.match(file, "%.dtx$") then
@@ -1410,9 +1380,6 @@
% return content
% end
% \end{lstlisting}
-% \caption{Example \texttt{update_tag} function.}
-% \label{fig:update-tag}
-% \end{figure}
%
% 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
@@ -1441,7 +1408,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, \vref{fig: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).
%
@@ -1453,8 +1420,7 @@
% 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]
+% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6,float,caption={A customised PDF creation script.},label={fig:PDF}]
% #!/usr/bin/env texlua
%
% -- Build script with custom PDF route
@@ -1477,9 +1443,6 @@
% return errorlevel
% end
% \end{lstlisting}
-% \caption{A customised PDF creation script.}
-% \label{fig:PDF}
-% \end{figure}
%
% \subsection{Pre-typesetting hook}
%
@@ -1511,9 +1474,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 \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 \vref{fig:uploadconfig}.
%
% Note that the \texttt{upload} target will \emph{not} execute the
% \texttt{ctan} target first.
@@ -1636,8 +1599,7 @@
% \end{table}
%
%
-% \begin{figure}[p]
-% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6]
+% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6,float,caption={Example of \texttt{uploadconfig} from the \pkg{vertbars} package.},label={fig:uploadconfig}]
% uploadconfig = {
% pkg = "vertbars",
% version = "v1.0c",
@@ -1649,9 +1611,6 @@
% update = true,
% }
% \end{lstlisting}
-% \caption{Example of \texttt{uploadconfig} from the \pkg{vertbars} package.}
-% \label{fig:uploadconfig}
-% \end{figure}
%
% \section{Lua interfaces}
%
@@ -1994,13 +1953,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 (\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 (\vref{sec:manifest-sorting}),
+% the inclusion of one-line descriptions for each file (\vref{sec:manifest-desc}),
+% and the details of the formatting of each entry (\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,
@@ -2043,7 +2002,7 @@
%
% 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 \vref{tab:manifest-setup,tab:manifest-subheadings}
% See the complete setup code in |l3build-manifest-setup.lua| for examples of these in use.
%
% \begin{table}
@@ -2616,3 +2575,9 @@
% \end{implementation}
%
% \PrintIndex
+
+% \endinput
+% Local Variables:
+% mode: doctex
+% TeX-master: t
+% End:
More information about the latex3-commits
mailing list.