diff options
Diffstat (limited to 'Master/texmf-dist/source/latex')
| -rw-r--r-- | Master/texmf-dist/source/latex/l3build/l3build.dtx | 70 |
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} |