[latex3-commits] [git/LaTeX3-latex3-l3build] master: general doc tweaks (037c1d1)

[Will Robertson]

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

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

commit 037c1d147d4d2e832a769e73ddb1c0f7ca6d5046
Author: Will Robertson <wspr81 at gmail.com>
Date:   Tue Dec 11 22:37:28 2018 +1030

    general doc tweaks


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

037c1d147d4d2e832a769e73ddb1c0f7ca6d5046
 l3build-help.lua    |    2 +-
 l3build-stdmain.lua |   10 +++++-----
 l3build.dtx         |   34 +++++++++++++++++++++-------------
 3 files changed, 27 insertions(+), 19 deletions(-)

diff --git a/l3build-help.lua b/l3build-help.lua
index 18caf87..8c38775 100644
--- a/l3build-help.lua
+++ b/l3build-help.lua
@@ -58,7 +58,7 @@ function help()
   end
   print("usage: " .. scriptname .. " <command> [<options>] [<names>]")
   print("")
-  print("The most commonly used l3build commands are:")
+  print("Valid commands are:")
   local longest,t = setup_list(target_list)
   for _,k in ipairs(t) do
     local target = target_list[k]
diff --git a/l3build-stdmain.lua b/l3build-stdmain.lua
index 3ff01ac..23f82b0 100644
--- a/l3build-stdmain.lua
+++ b/l3build-stdmain.lua
@@ -86,11 +86,6 @@ target_list =
         desc = "Create CTAN-ready archive",
         func = ctan
       },
-    upload =
-      {
-        desc = "Send archive to CTAN for public release",
-        func = upload
-      },
     doc =
       {
         desc = "Typesets all documentation files",
@@ -144,6 +139,11 @@ target_list =
         desc = "Unpacks the source files into the build tree",
         func = unpack
       }
+    upload =
+      {
+        desc = "Send archive to CTAN for public release",
+        func = upload
+      },
   }
 
 --
diff --git a/l3build.dtx b/l3build.dtx
index ff3ebf7..142949b 100644
--- a/l3build.dtx
+++ b/l3build.dtx
@@ -40,7 +40,7 @@
 \makeatother
 \newenvironment{buildcmd}[1]{%
   \bigskip\par\noindent\hspace{-\parindent}%
-  \fbox{\ttfamily \textcolor[gray]{0.5}{\$} texlua build.lua #1}%
+  \fbox{\ttfamily \textcolor[gray]{0.5}{\$} l3build #1}%
   \nopagebreak\smallskip\nopagebreak\par\nopagebreak\noindent\ignorespaces
  }
  {}
@@ -236,7 +236,10 @@
 %
 % The \pkg{l3build} system is a Lua script for building \TeX{} packages, with particular emphasis on regression testing.
 % It is written in cross-platform Lua code, so can be used by any modern \TeX{} distribution with the |texlua| interpreter.
-% A package for building with \pkg{l3build} can be written in any \TeX\ dialect; its defaults are set up for \LaTeX\ packages written in the DocStrip style. (Caveat: minimal testing has yet been performed for non-\LaTeX{} packages.)
+% Wrapper functions/binaries are distributed in the standard \TeX{} distributions so that the script can be called using
+% \texttt{l3build} on the command line; run without arguments it prints a brief synopsis of its usage.
+%
+% The \pkg{l3build} system is designed for packages written in any \TeX\ dialect; its defaults are set up for \LaTeX\ packages written in the DocStrip style. (Caveat: minimal testing has yet been performed for non-\LaTeX{} packages.)
 %
 % Test files are written as standalone \TeX{} documents using the |regression-test.tex| setup file; documentation on writing these tests is discussed in Section~\ref{sec:writing-tests}.
 %
@@ -301,31 +304,35 @@
 %
 % \subsection{Main build commands}
 %
-% In the working directory of a bundle or module, the following commands can be executed:
+% In the working directory of a bundle or module, \pkg{l3build} is run by executing
+% \begin{center}
+% \texttt{l3build \meta{command} [\meta{option(s)}]}
+% \end{center}
+% where \texttt{\meta{command}} can be one of the following:
 % \begin{itemize}[noitemsep]\ttfamily
 % \item check
 % \item check \meta{name(s)}
-% \item cmdcheck
 % \item clean
 % \item ctan
 % \item doc \meta{name(s)}
 % \item install
+% \item manifest
 % \item save \meta{name(s)}
 % \item tag
+% \item uninstall
 % \item unpack
+% \item upload
 % \end{itemize}
 % These commands are described below.
 %
 % As well as these commands, the system recognises the options
 % \begin{itemize}
-%   \item |--config| (|-c|) Configuration(s) to use for testing
-% \item |--date| Date to use when tagging
-%   data
+% \item |--config| (|-c|) Configuration(s) to use for testing
+% \item |--date| Date to use when tagging data
 % \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 |--engine| (|-e|) Sets the engine to use for
-%   testing
+% \item |--engine| (|-e|) Sets the engine to use for testing
 % \item |--epoch| Sets the epoch for typesetting and testing
 % \item |--first| Name of the first test to run
 % \item |--force| (|-f|) Force checks to run even if sanity
@@ -397,7 +404,7 @@
 %
 %
 % \begin{buildcmd}{ctan}
-% Creates an archive of the package and its documentation, suitable for uploading to CTAN
+% Creates an archive of the package and its documentation, suitable for uploading to CTAN.
 % The archive is compiled in \var{distribdir}, and if the results are successful the resultant |.zip| file is moved into the same directory as the build script.
 % If \var{packtdszip} is set true then  the building process includes a |.tds.zip| file containing the `\TeX\ Directory Structure' layout of the package or bundle.
 % The archive therefore may contain two `views' of the package:
@@ -520,11 +527,11 @@
 % \end{buildcmd}
 %
 % \begin{buildcmd}{tag}
-% Modifies the content of files specified by |tagfiles| to allow
-% automatic updating of the release tag and date. The tag is given as a
+% 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). As detailed below, the standard set up has no search
+% ISO format (YYYY-MM-DD). As detailed in Section~\ref{sec:tagging}, 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.
 % \end{buildcmd}
@@ -1158,6 +1165,7 @@
 % \section{Release-focussed features}
 %
 % \subsection{Automatic tagging}
+% \label{sec:tagging}
 %
 % As detailed above, the |tag| target will automatically edit
 % source files to modify date and release tag. As standard, no automatic