[latex3-commits] [latex3/l3build] main: Auto-generate man file (cecb626)

[github at latex-project.org]

Repository : https://github.com/latex3/l3build
On branch  : main
Link       : https://github.com/latex3/l3build/commit/cecb6263b734eaf98f8bd5ae4636d3d30371d368

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

commit cecb6263b734eaf98f8bd5ae4636d3d30371d368
Author: Joseph Wright <joseph at texdev.net>
Date:   Tue Mar 5 13:32:18 2024 +0000

    Auto-generate man file


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

cecb6263b734eaf98f8bd5ae4636d3d30371d368
 build.lua | 41 ++++++++++++++++++++++++++++
 l3build.1 | 91 ---------------------------------------------------------------
 2 files changed, 41 insertions(+), 91 deletions(-)

diff --git a/build.lua b/build.lua
index f8f34c6..d91d136 100644
--- a/build.lua
+++ b/build.lua
@@ -97,6 +97,47 @@ function tag_hook(tagname)
   os.execute('git commit -a -m "Step release tag"')
 end
 
+-- Auto-generate a .1 file from the help
+function  docinit_hook()
+  local find = string.find
+  local insert = table.insert
+  local open = io.open
+
+  local f = open("README.md","rb")
+  local readme = f:read("*all")
+  local date_start,date_end = find(readme,"%d%d%d%d%p%d%d%p%d%d")
+
+  local man_t = {}
+  insert(man_t,'.TH ' .. string.upper(module) .. ' 1 "'
+    .. readme:sub(date_start,date_end) .. '" "LaTeX"\n')
+  insert(man_t,(".SH NAME\n" .. module .. "\n"))
+  insert(man_t,(".SH SYNOPSIS\n Usage " .. module .. " <cmd> [<options>] [<names>]\n"))
+  insert(man_t,".SH DESCRIPTION")
+
+  local _,desc_start = find(readme,"Overview\n--------")
+  local desc_end,_ = find(readme,"Issues")
+
+  local overview = readme:sub(desc_start + 2,desc_end - 2):gsub("[`_]","")
+  insert(man_t,overview)
+
+  local cmd = "texlua ./" .. module .. ".lua --help"
+  local f = assert(io.popen(cmd,"r"))
+  local help_text = assert(f:read("*a"))
+  f:close()
+
+  insert(man_t,(help_text:gsub("\nUsage.*spec>]\n\n","")
+  :gsub("Valid commands",".SH COMMANDS\nValid commands")
+  :gsub("Valid options",".SH OPTIONS\nValid options")
+  :gsub("Full manual",'.SH "SEE ALSO"\nFull manual')
+  :gsub("Bug tracker","\nBug tracker")
+  :gsub("Copyright",".SH AUTHORS\nCopyright")))
+
+  f = assert(open(module .. ".1","wb"))
+  f:write((table.concat(man_t,"\n"):gsub("\n$","")))
+  f:close()
+  return 0
+end
+
 if not release_date then
   dofile("./l3build.lua")
 end
diff --git a/l3build.1 b/l3build.1
deleted file mode 100644
index b983494..0000000
--- a/l3build.1
+++ /dev/null
@@ -1,91 +0,0 @@
-.TH l3build 1 "2024-02-08"
-.SH NAME
-l3build \- Checking and building packages
-.SH SYNOPSIS
-l3build <target> [<options>] [<names>]
-.SH DESCRIPTION
-The 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 l3build can be written in any TeX dialect; its
-defaults are set up for LaTeX packages written in the DocStrip style.
-.PP
-The standard l3build targets are:
-.IP check
-Runs all automated tests
-.IP clean
-Cleans out directory tree
-.IP ctan
-Creates CTAN-ready archive
-.IP doc
-Typesets all documentation files
-.IP install
-Installs files into the local texmf tree
-.IP manifest
-Creates a manifest file
-.IP save
-Saves test validation log
-.IP tag
-Updates release tags in files
-.IP uninstall
-Uninstalls files from the local texmf tree
-.IP unpack
-Unpacks the source files into the build tree
-.IP upload
-Sends archive to CTAN for public release
-.SH OPTIONS
-Various options apply
-.IP --config|-c
-Sets the config(s) used for running tests
-.IP --date
-Sets the date to insert into sources
-.IP --debug
-Runs target in debug mode
-.IP --dirty
-Skips cleaning up the test area
-.IP --dry-run
-Dry run for install or upload
-.IP --email
-Email address of CTAN uploader
-.IP --engine|-e
-Sets the engine(s) to use for running test
-.IP --epoch
-Sets the epoch for tests and typesetting
-.IP --file|-F
-Takes the upload announcement from the given file
-.IP --first
-Name of first test to run
-.IP --full
-Installs all files
-.IP --halt-on-error|-H
-Stops running tests after the first failure
-.IP --help|-h
-Prints help message and exits
-.IP --last
-Name of last test to run
-.IP --message|-m
-Text for upload announcement message
-.IP --quiet|-q
-Suppresses TeX output when unpacking
-.IP --rerun
-Skips setup: simply reruns tests
-.IP --show-log-on-error
-Shows the full log of the failure with 'halt-on-error'
-.IP --show-saves|-S
-Shows the invocation to update failing .tlg files
-.IP --shuffle
-Shuffles order of tests
-.IP --stdengine|-s
-Run tests with the std engine (config dependent)
-.IP --texmfhome
-Location of user texmf tree
-.IP --version
-Prints version information and exits
-.SH BUGS
-.SH AUTHOR
-The LaTeX Project (latex-team at latex-project.org)
-.PP
-Please log issues on the GitHub homepage:
-https://github.com/latex3/l3build/issues.
-.SH SEE ALSO
-See l3build.pdf for more details.