summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3build
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2019-06-18 22:29:20 +0000
committerKarl Berry <karl@freefriends.org>2019-06-18 22:29:20 +0000
commit691106177d00ff3ef1e88a1bbe1a914140c86d85 (patch)
tree9393df2ca80c1a7787aa790d52b42b2009946504 /Master/texmf-dist/source/latex/l3build
parentbf2e8a6ab79c4f7fd2eed164783c60f1575f84e4 (diff)
l3build (18jun19)
git-svn-id: svn://tug.org/texlive/trunk@51397 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3build')
-rw-r--r--Master/texmf-dist/source/latex/l3build/l3build.dtx70
1 files changed, 63 insertions, 7 deletions
diff --git a/Master/texmf-dist/source/latex/l3build/l3build.dtx b/Master/texmf-dist/source/latex/l3build/l3build.dtx
index 7a662751323..4a5dc0f51cf 100644
--- a/Master/texmf-dist/source/latex/l3build/l3build.dtx
+++ b/Master/texmf-dist/source/latex/l3build/l3build.dtx
@@ -1,6 +1,6 @@
% \iffalse
%
-% File l3build.dtx (C) Copyright 2014-2018 The LaTeX3 Project
+% File l3build.dtx (C) Copyright 2014-2019 The LaTeX3 Project
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
@@ -227,7 +227,7 @@
% }^^A
% }
%
-% \date{Released 2019-02-10}
+% \date{Released 2019-06-18}
%
% \maketitle
% \tableofcontents
@@ -352,10 +352,12 @@
% \item |--halt-on-error| (|-H|) Specifies that checks
% 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 |--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 |--show-log-on-error| To be used in addition to \texttt{--halt-on-error} and results
+% in the full \texttt{.log} file of a failed test to be shown on the console
% \item |--shuffle| Shuffle the order in which tests run
% \item |--texmfhome| Sets the location of the user tree for installing
% \end{itemize}
@@ -1331,15 +1333,37 @@
% 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.
+% Note that the \texttt{upload} target will \emph{not} execute the
+% \texttt{ctan} target first.
+%
+% This upload facility assumes availablity of |curl| on your
+% system. In the case of Windows, the system curl will not be
+% available if you are using a 32 bit \TeX\ implementation. Curl
+% executables are available for a variety of operating systems from
+% \url{https://curl.haxx.se/download.html}.
%
% \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'
+% from a specified file. The \texttt{build.lua} file may also specify that this text is to
+% be taken from the file specified by
+% |uploadconfig.announcement_file|, this allows the release-specific announcement to be
+% specified outside the main |build.lua| file. If
+% |uploadconfig.announcement_file| is |nil| or specifies a file that
+% can not be read, and no announcement is provided by the
+% |announcement| field or commandline arguments, |l3build| will
+% interactively prompt for text (which may be empty).
+%
+% Note that if the announcement text is empty a `silent update'
% is performed; this should usually be performed for minor bug or documentation fixes only.
%
+% \paragraph{Note text}
+% This optional field is for passing notes to the CTAN maintainers. As
+% for announcements, the text may be set in |uploadconfig.note| or
+% perhaps more usefully, if |uploadconfig.note_file| is the filename of a
+% readable file the file text is used as the note.
+%
% \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
@@ -1356,13 +1380,41 @@
% non-existing package or if you attempt to upload a new package with the same name as a
% pre-existing one.
%
+% \paragraph{The \texttt{curl} options file}
+%
+% The \pkg{l3build} upload options are passed to |curl| by writing the
+% fields to a text file with a default name being
+% \meta{package}|-ctan.curlopt|. This is then passed to curl using its
+% |--config| commandline option. (Using an intermediate file helps
+% keep \pkg{l3build} portable between systems using different
+% commandline quoting conventions.)
+%
+% By default the file is written into the current directory alongside
+% the zip file to be uploaded. You may wish to specify that this file
+% is ignored by any version control in that directory (using
+% |.gitignore| or similar). Or alternatively you can use the
+% |uploadconfig.curl_file| field in the |build.lua| file to specify an
+% alternative name or location for this file.
+%
+% \paragraph{Debugging}
% 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.
+% the request from CTAN to a service that redirects the input back
+% again so it can be examined.
+% It can also be useful to check the contents of the |curlopts| file which has a
+% record of the options passed to curl.
%
% \begin{table}[p]
% \def\YES{\textbullet}
-% \caption{Fields used in the \texttt{uploadconfig} setup table. The first section of fields are \emph{required} and if they are omitted the user will be interactively prompted for further input. Most commands take string input, but those that are indicated with `Multi' accept more than one entry using an array of strings.}
+% \caption{Fields used in the \texttt{uploadconfig} setup table. The
+% first section of fields are \emph{required} and if they are
+% omitted the user will be interactively prompted for further
+% input. Most commands take string input, but those that are
+% indicated with `Multi' accept more than one entry using an array
+% of strings. Most of the fields correspond directly to the fields
+% in the CTAN upload API, the last group relate to file use by
+% \pkg{l3build}.}
% \label{tab:upload-setup}
+% \medskip
% \begin{minipage}{\linewidth}
% \begin{tabular}{@{}lccp{8cm}@{}}
% \toprule
@@ -1387,6 +1439,10 @@
% \texttt{support } & & \YES & URL(s) of support channels \\
% \texttt{topic } & & \YES & Topic(s)\footnote{See \url{https://ctan.org/topics/highscore}} \\
% \texttt{update } & & & Boolean \texttt{true} for an update, \texttt{false} for a new package \\
+% \midrule
+% \texttt{announcement\_file} & & & Announcement text file \\
+% \texttt{note\_file} & & & Note text file \\
+% \texttt{curlopt\_file} & & & The filename containing the options passed to curl \\
% \bottomrule
% \end{tabular}
% \end{minipage}