l3build (7feb19)

git-svn-id: svn://tug.org/texlive/trunk@49981 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 82 insertions, 20 deletions

diff --git a/Master/texmf-dist/source/latex/l3build/l3build.dtx b/Master/texmf-dist/source/latex/l3build/l3build.dtx
index b62f2e42ece..d0bd63173a6 100644
--- a/Master/texmf-dist/source/latex/l3build/l3build.dtx
+++ b/Master/texmf-dist/source/latex/l3build/l3build.dtx
@@ -86,7 +86,7 @@
 \luavarset{docfiles}          {\{\}}{Files which are part of the documentation but should not be typeset}
 \luavarset{dynamicfiles}      {\{ \}}{Secondary files to cleared before each test is run}
 \luavarset{excludefiles}      {\{"*\string~"\}}{Files to ignore entirely (default for Emacs backup files)}
-\luavarset{installfiles}      {\{"*.sty","*.cls"\}}{Files to install to the \texttt{text} area of the \texttt{texmf} tree}
+\luavarset{installfiles}      {\{"*.sty","*.cls"\}}{Files to install to the \texttt{tex} area of the \texttt{texmf} tree}
 \luavarset{makeindexfiles}    {\{"*.ist"\}}{MakeIndex files to be included in a TDS-style zip}
 \luavarset{scriptfiles}       {\{ \}}{Files to install to the \texttt{scripts} area of the \texttt{texmf} tree}
 \luavarset{scriptmanfiles}    {\{ \}}{Files to install to the \texttt{doc/man} area of the \texttt{texmf} tree}
@@ -110,6 +110,7 @@
 \luavarset{checkengines}{\{"pdftex", "xetex", "luatex"\}}{Engines to check with \texttt{check} by default}
 \luavarset{stdengine}    {"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}
 \luavarseparator
 \luavarset{checkconfigs}{\{\}}{Configurations to use for tests}
 \luavarseparator
@@ -226,7 +227,7 @@
 %    }^^A
 % }
 %
-% \date{Released 2018-12-18}
+% \date{Released 2019-02-06}
 %
 % \maketitle
 % \tableofcontents
@@ -317,14 +318,16 @@
 % \item check \meta{name(s)}
 % \item clean
 % \item ctan
+% \item doc
 % \item doc \meta{name(s)}
 % \item install
 % \item manifest
 % \item save \meta{name(s)}
-% \item tag
+% \item tag \meta{tag}
 % \item uninstall
 % \item unpack
 % \item upload
+% \item upload \meta{tag}
 % \end{itemize}
 % These commands are described below.
 %
@@ -332,11 +335,14 @@
 % \begin{itemize}
 % \item |--config| (|-c|) Configuration(s) to use for testing
 % \item |--date| Date to use when tagging data
+% \item |--debug| Runs the target in debug mode (not supported by all targets)
 % \item |--dirty| Skip cleaning up of the test area
 % \item |--dry-run| Runs the \texttt{install} target but does not copy
 %   any files: simply lists those that would be installed
+% \item |--email| Sets the email address for CTAN upload
 % \item |--engine| (|-e|) Sets the engine to use for testing
 % \item |--epoch| Sets the epoch for typesetting and testing
+% \item |--file| (|-F|) Take the upload announcement from the given file
 % \item |--first| Name of the first test to run
 % \item |--force| (|-f|) Force checks to run even if sanity
 %   checks fail, \emph{e.g.}~when |--engine| is not given in
@@ -347,6 +353,7 @@
 %   should stop as soon as possible, rather than running all requested
 %   tests; the difference file is printed in the terminal directly in the case of failure
 %  \item |--last| Name of the last test to run
+% \item |--message| (|-m|) Text for upload announcement
 % \item |--quiet| (|-q|) Suppresses output from unpacking
 % \item |--rerun| Run tests without unpacking/set up
 % \item |--shuffle| Shuffle the order in which tests run
@@ -531,14 +538,15 @@
 %
 % \begin{buildcmd}{tag}
 % Modifies the contents of files specified by |tagfiles| using a search pattern
-% to automatically update the `release tag' (or package version) and date. The tag is given as a
-% command line option, whilst the optional date should be passed using
-% |--date| (|-d|); if not given, the date will default to the current date in
-% ISO format (YYYY-MM-DD). The standard set up has no search
-% pattern defined for this target and so no action will be taken \emph{unless}
-% tag substitution is set up.
-%
-% See Section~\ref{sec:tagging} for full details on this feature.
+% to automatically update the `release tag' (or package version) and date.
+% The tag is given as the command line option and the date using
+% |--date| (|-d|). If not given, the date will default to the current date in
+% ISO format (YYYY-MM-DD). If no option is given (i.e., no tag specified) the tag
+% is passed through as |nil| to allow setting the tag programmatically.
+%
+% The standard setup has no search pattern defined for this target and so no action
+% will be taken \emph{unless} tag substitution is set up by defining the Lua function
+% |update_tag()|. See Section~\ref{sec:tagging} for full details on this feature.
 % \end{buildcmd}
 %
 % \begin{buildcmd}{unpack}
@@ -758,6 +766,32 @@
 % A series of example layouts and matching |build.lua| files are available from
 % \url{https://github.com/latex3/l3build/tree/master/examples}.
 %
+% \subsection{Non-standard formats/binaries}
+%
+% The standard approach used by \pkg{l3build} is to use a combination
+% of \var{engine} and \var{checkformat} to generate the \emph{binary} and
+% \emph{format} combination used for tests. For example, when |pdftex| is
+% the \var{engine} and |latex| is the \var{checkformat}, the system call
+% used is
+% \begin{verbatim}
+%   pdftex --fmt=pdflatex
+% \end{verbatim}
+% \emph{i.e.}~the binary names is the same as the \var{engine}, and the format
+% is a simple substitution of the \var{checkformat} into \var{engine}, replacing
+% |tex|.
+%
+% For more complex set ups, \var{specialformats} should be used. This is a
+% table with one entry per \var{checkformat}. Each entry is itself a table,
+% and these contain a list of engines and settings for |binary|, |format|
+% and |options|. For example, for Con\TeX{}t and appropriate set up is
+% \begin{verbatim}
+% specialformats.context = {
+%   luatex = {binary = "context", format = ""},
+%   pdftex = {binary = "texexec", format = ""},
+%   xetex  = {binary = "texexec", format = "", options = "--xetex"}
+% }
+% \end{verbatim}
+%
 % \subsection{Output normalisation}
 % \label{sec:norm}
 %
@@ -1186,10 +1220,10 @@
 % replacement takes place, but setting up a |update_tag()| function
 % will allow this to happen. This function takes four input arguments:
 % \begin{enumerate}[nosep]
-%   \item The file name
-%   \item The full content of the file
-%   \item The tag name
-%   \item The tag date
+%   \item file name
+%   \item full content of the file
+%   \item tag name
+%   \item tag date
 % \end{enumerate}
 % The |update_tag()| function should return the (modified) contents
 % for writing to disk.
@@ -1222,8 +1256,9 @@
 %
 % 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
-% may be used to carry out arbitrary tasks during tagging (for example,
-% setting a version control tag for an entire repository).
+% may be used to carry out arbitrary tasks after the main tagging process.
+% For example, this can be used to set a version control tag for an entire repository.
+%
 %
 % \subsection{Typesetting documentation}
 %
@@ -1295,8 +1330,34 @@
 % A description of this metadata is outlined in Table~\ref{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}.
+%
 % Note that the \texttt{upload} target will \emph{not} execute the \texttt{ctan} target first.
 %
+% \paragraph{Announcement text}
+% It can be convenient not to include the announcement text within the |build.lua| file
+% directly. The command line argument |--message| (|-m|) allows the announcement to be
+% included as part of the |l3build| arguments, and |--file| (|-F|) reads the announcement
+% from a specified file. Note that if the announcement text is omitted a `silent update'
+% is performed; this should usually be performed for minor bug or documentation fixes only.
+%
+% \paragraph{Uploader details}
+% The CTAN team use the uploader email address as a form of low-security sanity
+% check that the upload is coming from a reputable source. Therefore, it is advisable not
+% to store this information within a public |build.lua| file. It can be set on the command
+% line with the |--email| option to \texttt{l3build}; alternatively, a private
+% configuration file could be used to add this information at upload time.
+%
+% \paragraph{The \texttt{update} field}
+% In most scenarios the |update| field does not need to be explicitly set. By default
+% \pkg{l3build} assumes that the package being uploaded already exists on CTAN
+% (|update=true|). If it does not, this is caught in the validation process before
+% uploading and automatically corrected. If you set |update| explicitly this will be passed
+% directly to CTAN in all circumstances, leading to errors if you attempt to update a
+% non-existing package or if you attempt to upload a new package with the same name as a
+% pre-existing one.
+%
+% If you have have difficulty with the upload process, add the option |--debug| to divert
+% the request from CTAN to a service that redirects the input back again so it can be examined.
 %
 % \begin{table}[p]
 %   \def\YES{\textbullet}
@@ -1307,6 +1368,7 @@
 %     \toprule
 %     Field & Req. & Multi & Description \\
 %     \midrule
+%  \texttt{announcement} & \YES &      & Announcement text                      \\
 %  \texttt{author      } & \YES &      & Author name (semicolon-separated for multiple) \\
 %  \texttt{ctanPath    } & \YES &      & CTAN path                              \\
 %  \texttt{email       } & \YES &      & Email address of uploader              \\
@@ -1316,7 +1378,6 @@
 %  \texttt{uploader    } & \YES &      & Name of uploader                       \\
 %  \texttt{version     } & \YES &      & Package version                        \\
 %  \midrule
-%  \texttt{announcement} &      &      & Announcement text                      \\
 %  \texttt{bugtracker  } &      & \YES & URL(s) of bug tracker                  \\
 %  \texttt{description } &      &      & Short description/abstract             \\
 %  \texttt{development } &      & \YES & URL(s) of development channels         \\
@@ -1342,8 +1403,6 @@
 %       summary     = "Mark vertical rules in margin of text",
 %       ctanPath    = "/macros/latex/contrib/vertbars",
 %       repository  = "https://github.com/wspr/herries-press/",
-%       uploader    = "Will Robertson",
-%       email       = [...],
 %       update      = true,
 %     }
 %   \end{lstlisting}
@@ -1373,13 +1432,16 @@
 %       \var{date}          & String  \\
 %       \var{dirty}         & Boolean \\
 %       \var{dry-run}       & Boolean \\
+%       \var{email}         & String  \\
 %       \var{engine}        & Table   \\
 %       \var{epoch}         & String  \\
+%       \var{file}          & string  \\
 %       \var{first}         & Boolean \\
 %       \var{force}         & Boolean \\
 %       \var{full}          & Boolean \\
 %       \var{halt-on-error} & Boolean \\
 %       \var{help}          & Boolean \\
+%       \var{message}       & string  \\
 %       \var{names}         & Table   \\
 %       \var{quiet}         & Boolean \\
 %       \var{rerun}         & Boolean \\