summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3build
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2019-02-08 23:00:59 +0000
committerKarl Berry <karl@freefriends.org>2019-02-08 23:00:59 +0000
commitab1456ac100fab623d9d9e62c3ba878930d944aa (patch)
treea235def7a689e9590f6d29f43274fdafe52ce434 /Master/texmf-dist/source/latex/l3build
parentf22da8de751b570b9a23401289409b32368e867e (diff)
l3build (7feb19)
git-svn-id: svn://tug.org/texlive/trunk@49981 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3build')
-rw-r--r--Master/texmf-dist/source/latex/l3build/l3build.dtx102
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 \\