summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3build
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2018-01-10 21:47:40 +0000
committerKarl Berry <karl@freefriends.org>2018-01-10 21:47:40 +0000
commitee9860b8c1122fcf2d566d52c867c223f948977c (patch)
treee590c73331e380cab46df5786f8f2b2b29c96421 /Master/texmf-dist/source/latex/l3build
parentb64554e78a768a6aff700f2960cf6a344c55347a (diff)
l3build (10jan18)
git-svn-id: svn://tug.org/texlive/trunk@46283 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3build')
-rw-r--r--Master/texmf-dist/source/latex/l3build/build.lua42
-rw-r--r--Master/texmf-dist/source/latex/l3build/l3build.dtx217
-rw-r--r--Master/texmf-dist/source/latex/l3build/plain.lua2
3 files changed, 249 insertions, 12 deletions
diff --git a/Master/texmf-dist/source/latex/l3build/build.lua b/Master/texmf-dist/source/latex/l3build/build.lua
new file mode 100644
index 00000000000..08653cb0261
--- /dev/null
+++ b/Master/texmf-dist/source/latex/l3build/build.lua
@@ -0,0 +1,42 @@
+#!/usr/bin/env texlua
+
+-- Build script for LaTeX3 "l3build" files
+
+-- Identify the bundle and module
+module = "l3build"
+bundle = ""
+
+-- Non-standard settings
+checkconfigs = {"build", "plain"}
+checkdeps = { }
+checkengines = {"pdftex", "xetex", "luatex", "ptex", "uptex"}
+cleanfiles = {"*.pdf", "*.tex", "*.zip"}
+installfiles = {"l3build*.lua", "regression-test.tex"}
+packtdszip = true
+sourcefiles = {"*.dtx", "*.lua", "*.ins"}
+typesetcmds = "\\AtBeginDocument{\\DisableImplementation}"
+unpackdeps = { }
+versionfiles = {"*.dtx", "*.md", "*.lua"}
+
+-- Detail how to set the version automatically
+function setversion_update_line(line, date, version)
+ local date = string.gsub(date, "%-", "/")
+ -- .dtx file
+ if string.match(line, "^%% \\date{Released %d%d%d%d/%d%d/%d%d}$") then
+ line = string.gsub(line, "%d%d%d%d/%d%d/%d%d", date)
+ end
+ -- Markdown files
+ if string.match(
+ line, "^Release %d%d%d%d/%d%d/%d%d$"
+ ) then
+ line = "Release " .. date
+ end
+ -- l3build.lua
+ if string.match(line, "^release_date = \"%d%d%d%d/%d%d/%d%d\"$") then
+ line = "release_date = \"" .. date .. "\""
+ end
+ return line
+end
+
+-- Load l3build itself: truly self-contained so no kpsewhich() here
+dofile("./l3build.lua")
diff --git a/Master/texmf-dist/source/latex/l3build/l3build.dtx b/Master/texmf-dist/source/latex/l3build/l3build.dtx
index 2c674d4d521..b022225a56b 100644
--- a/Master/texmf-dist/source/latex/l3build/l3build.dtx
+++ b/Master/texmf-dist/source/latex/l3build/l3build.dtx
@@ -75,12 +75,12 @@
\luavarset{tdsdir} {distribdir .. "/tds"} {Directory for organised files into TDS structure}
\luavarset{tdsroot}{"latex"}{Root directory of the TDS structure for the bundle/module to be installed into}
\luavarseparator
+\luavarset{auxfiles} {\{"*.aux", "*.lof", "*.lot", "*.toc"\}}{Secondary files to be saved as part of running tests}
\luavarset{bibfiles} {\{"*.bib"\}}{\BibTeX{} database files}
\luavarset{binaryfiles} {\{"*.pdf", "*.zip"\}}{Files to be added in binary mode to zip files}
\luavarset{bstfiles} {\{"*.bst"\}}{\BibTeX{} style files}
\luavarset{checkfiles} {\{~\}}{Extra files unpacked purely for tests}
\luavarset{checksuppfiles} { }{Files needed for performing regression tests}
-\luavarset{cmdchkfiles} {\{\}}{Files need to perform command checking (\cls{l3doc}-based documentation only)}
\luavarset{cleanfiles} {\{"*.log", "*.pdf", "*.zip"\}}{Files to delete when cleaning}
\luavarset{demofiles} {\{\}}{Files which show how to use a module}
\luavarset{docfiles} {\{\}}{Files which are part of the documentation but should not be typeset}
@@ -122,7 +122,6 @@
\luavarset{zipexe} {"zip"} {Executable for creating archive with \texttt{ctan}}
\luavarseparator
\luavarset{checkopts} {"-interaction=nonstopmode"}{Options based to engine when running checks.}
-\luavarset{cmdchkopts} {"-interaction=batchmode"} {Options based to engine when running command checks.}
\luavarset{typesetopts}{"-interaction=nonstopmode"}{Options based to engine when typesetting.}
\luavarset{unpackopts} {""} {Options based to engine when unpacking.}
\luavarset{zipopts} {"-v -r -X"} {Options based to zip program.}
@@ -155,8 +154,11 @@
\luavarset{typsetcycles}{3} {Number of cycles of typesetting to carry out.}
\luavarset{versionform} {""} {Nature of version strings for auto-replacement.}
\luavarset{recordstatus}{false} {Switch to include error level from test runs in \texttt{.tlg} files}
+\luavarset{manifestfile} {"MANIFEST.md"} {Filename to use for the manifest file.}
}
\allluavars
+
+
\newcommand\luavartypeset{%
\begingroup
\frenchspacing
@@ -214,7 +216,7 @@
% }^^A
% }
%
-% \date{Released 2017/12/12}
+% \date{Released 2018/01/10}
%
% \maketitle
% \tableofcontents
@@ -310,10 +312,13 @@
% As well as these commands, the system recognises the options
% \begin{itemize}
% \item \texttt{--config} (\texttt{-c}) Configuration(s) to use for testing
-% \item \texttt{--date} (\texttt{-d}) Date to use when setting version
+% \item \texttt{--date} Date to use when setting version
% data
+% \item \texttt{--dry-run} Runs the \texttt{install} target but does not copy
+% any files: simply lists those that would be installed
% \item \texttt{--engine} (\texttt{-e}) Sets the engine to use for
% testing
+% \item \texttt{--epoch} Sets the epoch for typesetting and testing
% \item \texttt{--force} (\texttt{-f}) Force checks to run even if sanity
% checks fail, \emph{e.g.}~when \texttt{--engine} is not given in
% \luavar{checkengines}
@@ -323,7 +328,9 @@
% \item \texttt{--pdf} (\texttt{-p}) Test PDF file against a reference
% version rather than using a log comparison
% \item \texttt{--quiet} (\texttt{-q}) Suppresses output from unpacking
-% \item \texttt{--textfiledir} (\texttt{-t}) Select a specific set of tests
+% \item \texttt{--rerun} Run tests without unpacking/set up
+% \item \texttt{--shuffle} Shuffle the order in whichs tests run
+% \item \texttt{--texmfhome} Sets the location of the user tree for installing
% \item \texttt{--version} (\texttt{-v}) Version string to use when setting
% version data
% \end{itemize}
@@ -384,13 +391,6 @@
% from the engines not available in earlier releases.
% \end{buildcmd}
%
-% \begin{buildcmd}{cmdcheck}
-% For \cls{l3doc}-based sources, allows checking that the commands defined in the code part (by \var{cmdchkfiles}) are documented in the description part.
-% This is performed by passing the |check| option to the \cls{l3doc} class, typesetting the file(s) to check with engine \var{stdengine} with options \var{cmdchkopts}, and checking the resultant |.cmds| file(s).
-% Dependencies are specified also with \var{checkdeps}.
-% \end{buildcmd}
-%
-%
% \begin{buildcmd}{clean}
% This command removes all temporary files used for package bundling and regression testing.
% In the standard layout, these are all files within the directories defined by \var{localdir}, \var{testdir}, \var{typesetdir} and \var{unpackdir}, as well as all files defined in the \var{cleanfiles} variable in the same directory as the script.
@@ -476,6 +476,8 @@
%
% \begin{buildcmd}{install}
% Copies all package files (defined by \var{installfiles}) into the user's home \texttt{texmf} tree in the form of the \TeX\ Directory Structure.
+% The location of the user tree can be adjusted using the |--texmfhome| swtich:
+% the standard setting is the location set as |TEXMFHOME|.
% \end{buildcmd}
%
% \begin{buildcmd}{save \meta{name(s)}}
@@ -502,6 +504,27 @@
% from the engines not available in earlier releases.
% \end{buildcmd}
%
+% \begin{buildcmd}{manifest}
+% Generates a `manifest' file which lists the files of the package as known to \pkg{l3build}.
+% The filename of this file (by default \luavar{manifestfile}) can be set with the variable \var{manifestfile}.
+%
+% The intended purpose of this manifest file is to include it within a package as metadata.
+% 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}.
+%
+% 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}
+% is run after also running \texttt{ctan} it will include the files included
+% in the CTAN and TDS directories as well.
+%
+% Presently, this means that if you wish to include an up-to-date manifest file
+% as part of a \texttt{ctan} release, you must run
+% \texttt{ctan} / \texttt{manifest} / \texttt{ctan}.
+% Improvements to this process are planned for the future.
+% \end{buildcmd}
+%
% \begin{buildcmd}{setversion}
% Modifies the content of files specified by |versionfiles| to allow
% automatic updating of the file date and version. The latter are
@@ -1203,6 +1226,7 @@
% \label{fig:PDF}
% \end{figure}
%
+%
% \section{Lua interfaces}
%
% Whilst for the majority of users the simple variable-based control methods
@@ -1424,6 +1448,175 @@
% |target| in this table is ignored.
% \end{function}
%
+% \subsection{Customising the manifest file}
+% \label{sec:manifest}
+%
+% The default setup for the manifest file creating with the \texttt{manifest}
+% 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 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}).
+%
+% 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,
+% and load it within your |build.lua| using |dofile()|.
+%
+%
+% \subsubsection{Custom manifest groups}
+% \label{sec:manifest-groups}
+%
+% The setup code for defining each group of files within the manifest looks something like
+% the following:
+% \begin{verbatim}
+% manifest_setup = function()
+% local groups = {
+% {
+% subheading = "Repository files",
+% description = [[
+% Files located in the package development repository.
+% ]],
+% },
+% {
+% name = "Source files",
+% description = [[
+% These are source files generating the package files.
+% ]],
+% files = {sourcefiles},
+% },
+% {
+% name = "Typeset documentation source files",
+% description = [[
+% These files are typeset using LaTeX to produce the PDF documentation for the package.
+% ]],
+% files = {typesetfiles,typesetsourcefiles,typesetdemofiles},
+% },
+% ...
+% }
+% return groups
+% end
+% \end{verbatim}
+%
+% 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}
+% See the complete setup code in |l3build-manifest-setup.lua| for examples of these in use.
+%
+% \begin{table}
+% \caption{Table entries used in the manifest setup table for a group.}
+% \label{tab:manifest-setup}
+% \centering
+% \begin{tabular}{lp{8cm}}
+% \toprule
+% Entry & Description \\
+% \midrule
+% \var{name} & The heading of the group \\
+% \var{description} & The description printed below the heading \\
+% \var{files} & Files to include in this group \\
+% \var{exclude} & Files to exclude (default |{excludefiles}|) \\
+% \var{dir} & The directory to search (default |maindir|) \\
+% \var{rename} & An array with a |gsub| redefinition for the filename \\
+% \var{skipfiledescription} & Whether to extract file descriptions from these files (default |false|) \\
+% \bottomrule
+% \end{tabular}
+% \end{table}
+%
+% \begin{table}
+% \caption{Table entries used in the manifest setup table for a subheading.}
+% \label{tab:manifest-subheadings}
+% \centering
+% \begin{tabular}{lp{8cm}}
+% \toprule
+% Entry & Description \\
+% \midrule
+% \var{subheading} & The subheading \\
+% \var{description} & The description printed below the subheading \\
+% \bottomrule
+% \end{tabular}
+% \end{table}
+%
+%
+% \subsubsection{Sorting within each manifest group}
+% \label{sec:manifest-sorting}
+%
+% Within a single group in the manifest listing, files can be matched against multiple variables.
+% For example, for |sourcefiles={*.dtx,*.ins}| the following (unsorted) file listing might result:
+% \begin{itemize}
+% \item foo.dtx
+% \item bar.dtx
+% \item foo.ins
+% \item bar.ins
+% \end{itemize}
+% This listing can be sorted using two separate functions by the default manifest code.
+% The first, default, is to sort alphabetically within a single variable match.
+% This keeps all files of a single extension contiguous in the listing.
+% To edit how this sort is performed, redefine the |manifest_sort_within_match| function.
+%
+% The second approach to sorting is to apply a sorting function to the entire set of matched files.
+% (This happens \emph{after} any sorting is applied for each match.)
+% By default this is a no-op but can be edited by redefining the |manifest_sort_within_group|
+% function. For example:
+% \begin{verbatim}
+% manifest_sort_within_group = function(files)
+% local f = files
+% table.sort(f)
+% return f
+% end
+% \end{verbatim}
+% This will produce an alphabetical listing of files:
+% \begin{itemize}
+% \item bar.dtx
+% \item bar.ins
+% \item foo.dtx
+% \item foo.ins
+% \end{itemize}
+%
+%
+% \subsubsection{File descriptions}
+% \label{sec:manifest-desc}
+%
+% By default the manifest contains lists of files, and with a small addition these
+% lists can be augmented with a one-line summary of each file.
+% If the Lua function |manifest_extract_filedesc| is defined, it will be used to search
+% the contents of each file to extract a description for that file.
+% For example, perhaps you are using multiple |.dtx| files for a project and the argument
+% to the first |\section| in each can be used as a file description:
+% \begin{verbatim}
+% manifest_extract_filedesc = function(filehandle,filename)
+%
+% local all_file = filehandle:read("*all")
+% local matchstr = "\\section{(.-)}"
+%
+% filedesc = string.match(all_file,matchstr)
+%
+% return filedesc
+% end
+% \end{verbatim}
+% (Note the |matchstr| above is only an example and doesn't handle nested braces.)
+%
+%
+% \subsubsection{Custom formatting}
+% \label{sec:manifest-formatting}
+%
+% After the manifest code has built a complete listing of files to print, a series of
+% file writing operations are performed which create the manifest file.
+% The following functions can be re-defined to change the formatting of the manifest file:
+% \begin{itemize}
+% \item |manifest_write_opening|: Write the heading of the manifest file and its opening paragraph.
+% \item |manifest_write_subheading|: Write a subheading and description
+% \item |manifest_write_group_heading|: Write the section heading of the manifest group and the group description
+% \item |manifest_write_group_file|: Write the filename (when not writing file descriptions)
+% \item |manifest_write_group_file_descr|: Write the filename and the file description
+% \end{itemize}
+% Full descriptions of their usage and arguments can be found within the |l3build-manifest-setup.lua|
+% code itself.
+%
+%
% \end{documentation}
%
% \begin{implementation}
diff --git a/Master/texmf-dist/source/latex/l3build/plain.lua b/Master/texmf-dist/source/latex/l3build/plain.lua
new file mode 100644
index 00000000000..b59b2c110ce
--- /dev/null
+++ b/Master/texmf-dist/source/latex/l3build/plain.lua
@@ -0,0 +1,2 @@
+checkformat = "tex"
+testfiledir = "testfiles-plain" \ No newline at end of file