[latex3-commits] [git/LaTeX3-latex3-l3build] master: assorted documentation tidyups (c82351d)

Will Robertson will at wspr.io
Tue Dec 18 13:45:20 CET 2018


Repository : https://github.com/latex3/l3build
On branch  : master
Link       : https://github.com/latex3/l3build/commit/c82351dbdd142e1ca267e420915a1cc9156d78f3

>---------------------------------------------------------------

commit c82351dbdd142e1ca267e420915a1cc9156d78f3
Author: Will Robertson <wspr81 at gmail.com>
Date:   Wed Dec 12 22:19:37 2018 +1030

    assorted documentation tidyups


>---------------------------------------------------------------

c82351dbdd142e1ca267e420915a1cc9156d78f3
 l3build-upload.lua    |   37 ++++++++++++-------------
 l3build-variables.lua |    2 +-
 l3build.dtx           |   72 ++++++++++++++++++++++++++-----------------------
 3 files changed, 56 insertions(+), 55 deletions(-)

diff --git a/l3build-upload.lua b/l3build-upload.lua
index 7f16ba4..c526998 100644
--- a/l3build-upload.lua
+++ b/l3build-upload.lua
@@ -50,11 +50,13 @@ for those people who are interested.
 
 
 local curl_debug = curl_debug or false -- to disable posting
+-- For now, this is undocumented.
 
 local ctanupload = ctanupload or "ask"
 -- if ctanupload is nil or false, only validation is attempted
 -- if ctanupload is true the ctan upload URL will be used after validation
 -- if upload is anything else, the user will be prompted whether to upload.
+-- For now, this is undocumented. I think I would prefer to keep it always set to ask for the time being.
 
 function upload()
 
@@ -63,35 +65,30 @@ function upload()
   if bundle == "" then
     bundle = nil
   end
-  uploaddata.pkg = uploaddata.pkg or bundle or module or nil
+  uploaddata.pkg = uploaddata.pkg or ctanpkg or nil
 
-  ctan_post = uploadexe .. " "
+  ctan_post = curlexe .. " "
 
   --         field                                   max  desc                               mandatory  multi
   --         -------------------------------------------------------------------------------------------------
-  ctan_field("pkg",          uploaddata.pkg,            32, "Package name",                        true,  false )
-  ctan_field("version",      uploaddata.version,        32, "Package version",                     true,  false )
+  ctan_field("announcement", uploaddata.announcement, 8192, "Announcement",                        false, false )
   ctan_field("author",       uploaddata.author,        128, "Author name",                         true,  false )
-  ctan_field("email",        uploaddata.email,         255, "Email of uploader",                   true,  false )
-  ctan_field("uploader",     uploaddata.uploader,      255, "Name of uploader",                    true,  false )
+  ctan_field("bugtracker",   uploaddata.bugtracker,    255, "URL of bug tracker",                  false, false )
   ctan_field("ctanPath",     uploaddata.ctanPath,      255, "CTAN path",                           false, false )
-  ctan_field("license",      uploaddata.license,      2048, "Package license(s)",                  true,  true )
+  ctan_field("description",  uploaddata.description,  4096, "Short description of package",        false, false )
+  ctan_field("development",  uploaddata.development,   255, "URL of development channels",         false, true  )
+  ctan_field("email",        uploaddata.email,         255, "Email of uploader",                   true,  false )
   ctan_field("home",         uploaddata.home,          255, "URL of home page",                    false, false )
-  ctan_field("bugtracker",   uploaddata.bugtracker,    255, "URL of bug tracker",                  false, false )
-  ctan_field("support",      uploaddata.support,       255, "URL of support channels",             false, true  )
+  ctan_field("license",      uploaddata.license,      2048, "Package license(s)",                  true,  true  )
+  ctan_field("note",         uploaddata.note,         4096, "Internal note to ctan",               false, false )
+  ctan_field("pkg",          uploaddata.pkg,            32, "Package name",                        true,  false )
   ctan_field("repository",   uploaddata.repository,    255, "URL of source repositories",          false, true  )
-  ctan_field("development",  uploaddata.development,   255, "URL of development channels",         false, true  )
-  ctan_field("update",       uploaddata.update,          8, "True for an update, false for a new package", false, false )
+  ctan_field("summary",      uploaddata.summary,       128, "One-line summary of package",         true,  false )
+  ctan_field("support",      uploaddata.support,       255, "URL of support channels",             false, true  )
   ctan_field("topic",        uploaddata.topic,        1024, "Topic(s); see https://ctan.org/topics/highscore", false, true  )
-  ctan_field("announcement", uploaddata.announcement, 8192, "Announcement",                        false, false )
-  ctan_field("summary",      uploaddata.summary,       128, "One-line summary of package",         true,  false ) -- ctan-o-mat doc says optional
-  ctan_field("description",  uploaddata.description,  4096, "Short description of package",        false, false )
-  ctan_field("note",         uploaddata.note,         4096, "Internal note to ctan",               false, false )
-
-  --[[
-       Q: What about an explicit copyright string? CTAN packages have them
-          listed. TODO: check these are all the fields.
-  --]]
+  ctan_field("update",       uploaddata.update,          8, "True for an update, false for a new package", false, false )
+  ctan_field("uploader",     uploaddata.uploader,      255, "Name of uploader",                    true,  false )
+  ctan_field("version",      uploaddata.version,        32, "Package version",                     true,  false )
 
   -- construct the curl command
   ctan_post = ctan_post .. " --form 'file=@" .. tostring(ctan_file) .. ";filename=" .. tostring(ctan_file) .. "'"
diff --git a/l3build-variables.lua b/l3build-variables.lua
index 9c8ad2b..1142c5f 100644
--- a/l3build-variables.lua
+++ b/l3build-variables.lua
@@ -187,6 +187,6 @@ tpfext = tpfext or ".tpf"
 manifestfile = manifestfile or "MANIFEST.md"
 
 -- Upload settings
-uploadexe  = uploadexe  or "curl"
+curlexe  = curlexe  or "curl"
 uploaddata = uploaddata or {}
 
diff --git a/l3build.dtx b/l3build.dtx
index cd98ccf..a6e6c9d 100644
--- a/l3build.dtx
+++ b/l3build.dtx
@@ -96,21 +96,10 @@
 \luavarset{typesetdemofiles}  {\{\}}{Files to typeset before the documentation for inclusion in main documentation files}
 \luavarset{typesetfiles}      {\{"*.dtx"\}}{Files to typeset for documentation}
 \luavarset{typesetsuppfiles}  {\{\}}{Files needed to support typesetting when \enquote{sandboxed}}
-\luavarset{typesetsourcefiles}{\{\}}{Files to copy to unpacking when typesetting.}
-\luavarset{unpackfiles}       {\{"*.ins"\}}{Files to run to perform unpacking.}
+\luavarset{typesetsourcefiles}{\{\}}{Files to copy to unpacking when typesetting}
+\luavarset{unpackfiles}       {\{"*.ins"\}}{Files to run to perform unpacking}
 \luavarset{unpacksuppfiles}   {\{\}}{Files needed to support unpacking when \enquote{sandboxed}}
 \luavarseparator
-\luavarset{bakext}{".bak"}{Extension of backup files}
-\luavarset{dviext}{".dvi"}{Extension of DVI files}
-\luavarset{lvtext}{".lvt"}{Extension of log-based test files}
-\luavarset{tlgext}{".tlg"}{Extension of test file output}
-\luavarset{tpfext}{".tpf"}{Extension of PDF-based test output}
-\luavarset{lveext}{".lve"}{Extension of auto-generating test file output}
-\luavarset{logext}{".log"}{Extension of checking output, before processing it into a \texttt{.tlg}}
-\luavarset{pvtext}{".pvt"}{Extension of PDF-based test files}
-\luavarset{pdfext}{".pdf"}{Extension of PDF file for checking and saving}
-\luavarset{psext} {".ps"} {Extension of PostScript files}
-\luavarseparator
 \luavarset{includetests}{\{"*"\}}{Test names to include when checking}
 \luavarset{excludetests}{\{\}}   {Test names to exclude when checking}
 \luavarseparator
@@ -127,11 +116,18 @@
 \luavarset{typesetexe}{"pdflatex"}{Executable for compiling \texttt{doc(s)}}
 \luavarset{unpackexe} {"tex"}     {Executable for running \texttt{unpack}}
 \luavarset{zipexe}    {"zip"}     {Executable for creating archive with \texttt{ctan}}
+\luavarset{biberexe}     {"biber"}    {Biber executable}
+\luavarset{bibtexexe}    {"bibtex8"}  {\BibTeX{} executable}
+\luavarset{makeindexexe} {"makeindex"}{MakeIndex executable}
+\luavarset{curlexe} {"curl"}{Curl executable}
 \luavarseparator
-\luavarset{checkopts}  {"-interaction=nonstopmode"}{Options based to engine when running 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.}
+\luavarset{checkopts}  {"-interaction=nonstopmode"}{Options based to engine when running 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}
+\luavarset{biberopts}    {""}         {Biber options}
+\luavarset{bibtexopts}   {"-W"}       {\BibTeX{} options}
+\luavarset{makeindexopts}{""}         {MakeIndex options}
 \luavarseparator
 \luavarset{checksearch}  {true}{Switch to search the system \texttt{texmf} for during checking}
 \luavarset{typesetsearch}{true}{Switch to search the system \texttt{texmf} for during typesetting}
@@ -140,17 +136,10 @@
 \luavarset{glossarystyle}{"gglo.ist"}{MakeIndex style file for glossary/changes creation}
 \luavarset{indexstyle}   {"gind.ist"}{MakeIndex style for index creation}
 \luavarseparator
-\luavarset{biberexe}     {"biber"}    {Biber executable}
-\luavarset{biberopts}    {""}         {Biber options}
-\luavarset{bibtexexe}    {"bibtex8"}  {\BibTeX{} executable}
-\luavarset{bibtexopts}   {"-W"}       {\BibTeX{} options}
-\luavarset{makeindexexe} {"makeindex"}{MakeIndex executable}
-\luavarset{makeindexopts}{""}         {MakeIndex options}
-\luavarseparator
 \luavarset{forcecheckepoch}{"true"}    {Force epoch when running tests}
 \luavarset{forcedocepoch}  {"false"}   {Force epoch when typesetting}
 \luavarseparator
-\luavarset{asciiengines}{\{"pdftex"\}}{Engines which should log as sure ASCII}
+\luavarset{asciiengines}{\{"pdftex"\}}{Engines which should log as pure ASCII}
 \luavarset{checkruns}   {1}           {Number of runs to complete for a test before comparing the log}
 \luavarset{ctanreadme}{"README.md"}   {Name of the file to send to CTAN as \texttt{README.\meta{ext}}}
 \luavarset{ctanzip}{ctanpkg ... "-ctan"}{Name of the zip file created for upload to CTAN}
@@ -158,10 +147,24 @@
 \luavarset{flatten}     {true}        {Switch to flatten any source structure when sending to CTAN}
 \luavarset{maxprintline}{79}          {Length of line to use in log files}
 \luavarset{packtdszip}  {false}       {Switch to build a TDS-style zip file for CTAN}
-\luavarset{typesetcmds} {""}          {Instructions to be passed to \TeX{} when doing typesetting.}
-\luavarset{typesetruns}{3}            {Number of cycles of typesetting to carry out.}
+\luavarset{typesetcmds} {""}          {Instructions to be passed to \TeX{} when doing typesetting}
+\luavarset{typesetruns}{3}            {Number of cycles of typesetting to carry out}
 \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.}
+\luavarset{manifestfile}        {"MANIFEST.md"} {Filename to use for the manifest file}
+\luavarseparator
+\luavarset{uploaddata}        {\meta{table}} {Metadata to describe the package for CTAN (see Table~\ref{tab:upload-setup})}
+\luavarset{uploaddata.pkg}{ctanpkg}{Name of the CTAN package}
+\luavarseparator
+\luavarset{bakext}{".bak"}{Extension of backup files}
+\luavarset{dviext}{".dvi"}{Extension of DVI files}
+\luavarset{lvtext}{".lvt"}{Extension of log-based test files}
+\luavarset{tlgext}{".tlg"}{Extension of test file output}
+\luavarset{tpfext}{".tpf"}{Extension of PDF-based test output}
+\luavarset{lveext}{".lve"}{Extension of auto-generating test file output}
+\luavarset{logext}{".log"}{Extension of checking output, before processing it into a \texttt{.tlg}}
+\luavarset{pvtext}{".pvt"}{Extension of PDF-based test files}
+\luavarset{pdfext}{".pdf"}{Extension of PDF file for checking and saving}
+\luavarset{psext} {".ps"} {Extension of PostScript files}
 }
 \allluavars
 
@@ -551,13 +554,14 @@
 % \begin{buildcmd}{upload}
 % This target uses \texttt{curl} to upload the package zip file (created using \texttt{ctan}) to CTAN.
 % To control the metadata used to upload the package, the \texttt{uploaddata} table should be populated with a number of fields.
+% These are documented in Table~\ref{tab:upload-setup}.
 % Missing required fields will result in an interactive prompt for manual entry.
 % \end{buildcmd}
 %
 % \begin{table}
 %   \def\YES{\textbullet}
-%   \caption{Fields used in the \texttt{uploaddata} setup table. Most commands require string input, but those that are indicated with `Multi' accept more than one entry using an array of strings.}
-%   \label{tab:manifest-setup}
+%   \caption{Fields used in the \texttt{uploaddata} 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.}
+%   \label{tab:upload-setup}
 %   \begin{minipage}{\linewidth}
 %   \centering
 %   \begin{tabular}{lccp{8cm}}
@@ -653,7 +657,7 @@
 % \label{fig:module}
 % \end{figure}
 %
-% \subsection{Backward compatibly}
+% \subsection{Backwards compatability}
 %
 % Earlier releases of \pkg{l3build} required that the last line of
 % \texttt{build.lua} ran the main script, \emph{i.e.}~ that \texttt{build.lua}
@@ -673,12 +677,14 @@
 %
 % Note that in time support for loading \pkg{l3build} by calling the
 % \texttt{build.lua} script \emph{may} be removed: the recommended approach for
-% new scripts is to run \pkg{l3build}.
+% new scripts is to run \texttt{l3build}.
 %
 % \subsection{Variables}
 %
 % This section lists all variables defined in the |l3build.lua| script that are available for customisation.
 %
+% \luavartypeset
+%
 % \subsection{Interaction between tests}
 %
 % Tests are run in a single directory, so whilst they are may be isolated from
@@ -688,8 +694,6 @@
 % tests such that they do not use the same names for such files: this may lead
 % to variable outcomes depending on the order in which tests are run.
 %
-% \luavartypeset
-%
 % \subsection{Selective running of tests}
 %
 % The variables |includetests| and |excludetests| may be used to select which





More information about the latex3-commits mailing list