diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3build/l3build.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3build/l3build.dtx | 217 |
1 files changed, 205 insertions, 12 deletions
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} |