texlive[49450] trunk: l3build (18dec18)
commits+karl at tug.org
commits+karl at tug.org
Wed Dec 19 00:33:00 CET 2018
Revision: 49450
http://tug.org/svn/texlive?view=revision&revision=49450
Author: karl
Date: 2018-12-19 00:33:00 +0100 (Wed, 19 Dec 2018)
Log Message:
-----------
l3build (18dec18)
Modified Paths:
--------------
trunk/Build/source/texk/texlive/linked_scripts/l3build/l3build.lua
trunk/Build/source/texk/texlive/linked_scripts/texlive/tlmgr.pl
trunk/Master/texmf-dist/doc/latex/l3build/CHANGELOG.md
trunk/Master/texmf-dist/doc/latex/l3build/README.md
trunk/Master/texmf-dist/doc/latex/l3build/l3build.pdf
trunk/Master/texmf-dist/doc/man/man1/l3build.1
trunk/Master/texmf-dist/doc/man/man1/l3build.man1.pdf
trunk/Master/texmf-dist/scripts/l3build/l3build-help.lua
trunk/Master/texmf-dist/scripts/l3build/l3build-stdmain.lua
trunk/Master/texmf-dist/scripts/l3build/l3build-variables.lua
trunk/Master/texmf-dist/scripts/l3build/l3build.lua
trunk/Master/texmf-dist/source/latex/l3build/l3build.dtx
Added Paths:
-----------
trunk/Master/texmf-dist/scripts/l3build/l3build-upload.lua
Modified: trunk/Build/source/texk/texlive/linked_scripts/l3build/l3build.lua
===================================================================
--- trunk/Build/source/texk/texlive/linked_scripts/l3build/l3build.lua 2018-12-18 23:32:36 UTC (rev 49449)
+++ trunk/Build/source/texk/texlive/linked_scripts/l3build/l3build.lua 2018-12-18 23:33:00 UTC (rev 49450)
@@ -1,4 +1,4 @@
-#!/usr/bin/env texlua
+#!/usr/bin/env texlua
--[[
@@ -65,6 +65,7 @@
build_require("manifest")
build_require("manifest-setup")
build_require("tagging")
+build_require("upload")
build_require("stdmain")
-- This has to come after stdmain(),
@@ -96,7 +97,7 @@
build_require("variables")
-- Ensure that directories are 'space safe'
-maindir = escapepath(maindir)
+maindir = escapepath(maindir)
docfiledir = escapepath(docfiledir)
sourcefiledir = escapepath(sourcefiledir)
supportdir = escapepath(supportdir)
@@ -125,12 +126,12 @@
--
-- Deal with multiple configs for tests
--
-
+
-- When we have specific files to deal with, only use explicit configs
-- (or just the std one)
if options["names"] then
checkconfigs = options["config"] or {stdconfig}
-else
+else
checkconfigs = options["config"] or checkconfigs
end
Modified: trunk/Build/source/texk/texlive/linked_scripts/texlive/tlmgr.pl
===================================================================
--- trunk/Build/source/texk/texlive/linked_scripts/texlive/tlmgr.pl 2018-12-18 23:32:36 UTC (rev 49449)
+++ trunk/Build/source/texk/texlive/linked_scripts/texlive/tlmgr.pl 2018-12-18 23:33:00 UTC (rev 49450)
@@ -1,12 +1,12 @@
#!/usr/bin/env perl
-# $Id: tlmgr.pl 49226 2018-11-22 23:37:16Z karl $
+# $Id: tlmgr.pl 49408 2018-12-13 23:12:47Z karl $
#
# Copyright 2008-2018 Norbert Preining
# This file is licensed under the GNU General Public License version 2
# or any later version.
-my $svnrev = '$Revision: 49226 $';
-my $datrev = '$Date: 2018-11-23 00:37:16 +0100 (Fri, 23 Nov 2018) $';
+my $svnrev = '$Revision: 49408 $';
+my $datrev = '$Date: 2018-12-14 00:12:47 +0100 (Fri, 14 Dec 2018) $';
my $tlmgrrevision;
my $tlmgrversion;
my $prg;
@@ -9761,7 +9761,7 @@
distribution (L<http://tug.org/texlive>) and both are licensed under the
GNU General Public License Version 2 or later.
-$Id: tlmgr.pl 49226 2018-11-22 23:37:16Z karl $
+$Id: tlmgr.pl 49408 2018-12-13 23:12:47Z karl $
=cut
# test HTML version: pod2html --cachedir=/tmp tlmgr.pl >/tmp/tlmgr.html
Modified: trunk/Master/texmf-dist/doc/latex/l3build/CHANGELOG.md
===================================================================
--- trunk/Master/texmf-dist/doc/latex/l3build/CHANGELOG.md 2018-12-18 23:32:36 UTC (rev 49449)
+++ trunk/Master/texmf-dist/doc/latex/l3build/CHANGELOG.md 2018-12-18 23:33:00 UTC (rev 49450)
@@ -7,6 +7,13 @@
## [Unreleased]
+## [2018-12-18]
+
+### Changed
+
+- Add new `upload` target which uses `curl` with the CTAN API to send a package
+ for release (see #1)
+
## [2018-11-08]
### Changed
@@ -199,7 +206,8 @@
- Rationalise short option names: removed `-d`, `-E`, `-r`
- Target `cmdcheck`: specific to LaTeX3 kernel work
-[Unreleased]: https://github.com/latex3/l3build/compare/2018-11-08...HEAD
+[Unreleased]: https://github.com/latex3/l3build/compare/2018-12-18...HEAD
+[2018-12-18]: https://github.com/latex3/l3build/compare/2018-11-08...2018-12-18
[2018-11-08]: https://github.com/latex3/l3build/compare/2018-10-30...2018-11-08
[2018-10-30]: https://github.com/latex3/l3build/compare/2018-10-25...2018-10-30
[2018-10-25]: https://github.com/latex3/l3build/compare/2018-09-26...2018-10-25
Modified: trunk/Master/texmf-dist/doc/latex/l3build/README.md
===================================================================
--- trunk/Master/texmf-dist/doc/latex/l3build/README.md 2018-12-18 23:32:36 UTC (rev 49449)
+++ trunk/Master/texmf-dist/doc/latex/l3build/README.md 2018-12-18 23:33:00 UTC (rev 49450)
@@ -1,7 +1,7 @@
l3build: a testing and building system for LaTeX3
=================================================
-Release 2018-11-08
+Release 2018-12-18
Overview
--------
Modified: trunk/Master/texmf-dist/doc/latex/l3build/l3build.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/man/man1/l3build.1
===================================================================
--- trunk/Master/texmf-dist/doc/man/man1/l3build.1 2018-12-18 23:32:36 UTC (rev 49449)
+++ trunk/Master/texmf-dist/doc/man/man1/l3build.1 2018-12-18 23:33:00 UTC (rev 49450)
@@ -1,4 +1,4 @@
-.TH l3build 1 "2018-11-08"
+.TH l3build 1 "2018-12-18"
.SH NAME
l3build \- Checking and building packages
.SH SYNOPSIS
Modified: trunk/Master/texmf-dist/doc/man/man1/l3build.man1.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/scripts/l3build/l3build-help.lua
===================================================================
--- trunk/Master/texmf-dist/scripts/l3build/l3build-help.lua 2018-12-18 23:32:36 UTC (rev 49449)
+++ trunk/Master/texmf-dist/scripts/l3build/l3build-help.lua 2018-12-18 23:33:00 UTC (rev 49450)
@@ -58,7 +58,7 @@
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]
Modified: trunk/Master/texmf-dist/scripts/l3build/l3build-stdmain.lua
===================================================================
--- trunk/Master/texmf-dist/scripts/l3build/l3build-stdmain.lua 2018-12-18 23:32:36 UTC (rev 49449)
+++ trunk/Master/texmf-dist/scripts/l3build/l3build-stdmain.lua 2018-12-18 23:33:00 UTC (rev 49450)
@@ -58,7 +58,7 @@
return 0
end
},
- bundlectan =
+ bundlectan =
{
func = bundlectan
},
@@ -138,7 +138,12 @@
bundle_target = true,
desc = "Unpacks the source files into the build tree",
func = unpack
- }
+ },
+ upload =
+ {
+ desc = "Send archive to CTAN for public release",
+ func = upload
+ },
}
--
Added: trunk/Master/texmf-dist/scripts/l3build/l3build-upload.lua
===================================================================
--- trunk/Master/texmf-dist/scripts/l3build/l3build-upload.lua (rev 0)
+++ trunk/Master/texmf-dist/scripts/l3build/l3build-upload.lua 2018-12-18 23:33:00 UTC (rev 49450)
@@ -0,0 +1,237 @@
+--[[
+
+File l3build-upload.lua Copyright (C) 2018 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
+license or (at your option) any later version. The latest version
+of this license is in the file
+
+ http://www.latex-project.org/lppl.txt
+
+This file is part of the "l3build bundle" (The Work in LPPL)
+and all files in that bundle must be distributed together.
+
+-----------------------------------------------------------------------
+
+The development version of the bundle can be found at
+
+ https://github.com/latex3/l3build
+
+for those people who are interested.
+
+--]]
+
+
+-- UPLOAD()
+--
+-- takes a package configuration table and an optional boolean
+--
+-- if the upload parameter is not supplied or is not true, only package validation
+-- is used, if upload is true then package upload will be attempted if validation
+-- succeeds.
+
+-- fields are given as a string, or optionally for fields allowing multiple
+-- values, as a table of strings.
+
+-- Mandatory fields are checked in Lua
+-- Maximum string lengths are checked.
+
+-- Currently string values are not checked, eg licence names, or URL syntax.
+
+-- The input form could be used to construct a post body but
+-- luasec is not included in texlua. Instead an external program is used to post.
+-- As Windows (since April 2018) includes curl now use curl.
+-- A version using ctan-o-mat is available in the ctan-post github repo.
+
+-- the main interface is
+-- upload()
+-- with a configuration table `uploadconfig`
+
+
+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()
+
+ local uploadfile = ctanzip..".zip"
+
+ -- try a sensible default for the package name:
+ uploadconfig.pkg = uploadconfig.pkg or ctanpkg or nil
+
+ -- start building the curl command:
+ ctan_post = curlexe .. " "
+
+ -- build up the curl command field-by-field:
+
+ -- field max desc mandatory multi
+ -- ----------------------------------------------------------------------------------------------------
+ ctan_field("announcement", uploadconfig.announcement, 8192, "Announcement", false, false )
+ ctan_field("author", uploadconfig.author, 128, "Author name", true, false )
+ ctan_field("bugtracker", uploadconfig.bugtracker, 255, "URL(s) of bug tracker", false, true )
+ ctan_field("ctanPath", uploadconfig.ctanPath, 255, "CTAN path", true, false )
+ ctan_field("description", uploadconfig.description, 4096, "Short description of package", false, false )
+ ctan_field("development", uploadconfig.development, 255, "URL(s) of development channels", false, true )
+ ctan_field("email", uploadconfig.email, 255, "Email of uploader", true, false )
+ ctan_field("home", uploadconfig.home, 255, "URL(s) of home page", false, true )
+ ctan_field("license", uploadconfig.license, 2048, "Package license(s)", true, true )
+ ctan_field("note", uploadconfig.note, 4096, "Internal note to ctan", false, false )
+ ctan_field("pkg", uploadconfig.pkg, 32, "Package name", true, false )
+ ctan_field("repository", uploadconfig.repository, 255, "URL(s) of source repositories", false, true )
+ ctan_field("summary", uploadconfig.summary, 128, "One-line summary of package", true, false )
+ ctan_field("support", uploadconfig.support, 255, "URL(s) of support channels", false, true )
+ ctan_field("topic", uploadconfig.topic, 1024, "Topic(s)", false, true )
+ ctan_field("update", uploadconfig.update, 8, "Boolean: true=update, false=new pkg", false, false )
+ ctan_field("uploader", uploadconfig.uploader, 255, "Name of uploader", true, false )
+ ctan_field("version", uploadconfig.version, 32, "Package version", true, false )
+
+ -- finish constructing the curl command:
+ ctan_post = ctan_post .. " --form 'file=@" .. tostring(uploadfile) .. ";filename=" .. tostring(uploadfile) .. "'"
+ ctan_post = ctan_post .. " https://ctan.org/submit/"
+
+ -- avoid lower level error from post command if zip file missing
+ local zip=io.open(trim_space(tostring(uploadfile)),"r")
+ if zip~=nil then
+ io.close(zip)
+ else
+ error("Missing zip file '" .. tostring(uploadfile) .. "'")
+ end
+
+ -- call post command to validate the upload at CTAN's validate URL
+ local exit_status=0
+ local fp_return=""
+
+ -- use popen not execute so get the return body local exit_status=os.execute(ctan_post .. "validate")
+ if (curl_debug==false) then
+ local fp = assert(io.popen(ctan_post .. "validate", 'r'))
+ fp_return = assert(fp:read('*a'))
+ fp:close()
+ else
+ fp_return="WARNING: curl_debug==true: posting disabled"
+ print(ctan_post)
+ end
+ if string.match(fp_return,"WARNING") or string.match(fp_return,"ERROR") then
+ exit_status=1
+ end
+
+ -- if upload requested and validation succeeded repost to the upload URL
+ if (exit_status==0 or exit_status==nil) then
+ if (ctanupload ~=nil and ctanupload ~=false and ctanupload ~= true) then
+ print("Validation successful, do you want to upload to CTAN? [y/n]" )
+ local answer=""
+ io.write("> ")
+ io.flush()
+ answer=io.read()
+ if(string.lower(answer,1,1)=="y") then
+ ctanupload=true
+ end
+ end
+ if (ctanupload==true) then
+ local fp = assert(io.popen(ctan_post .. "upload", 'r'))
+ fp_return = assert(fp:read('*a'))
+ fp:close()
+-- this is just html, could save to a file
+-- or echo a cleaned up version
+ print('Response from CTAN:')
+ print(fp_return)
+ if string.match(fp_return,"WARNING") or string.match(fp_return,"ERROR") then
+ exit_status=1
+ end
+ else
+ print("CTAN validation successful")
+ end
+ else
+ error("Warnings from CTAN package validation:\n" .. fp_return)
+ end
+ return exit_status
+end
+
+
+function trim_space(s)
+ return (s:gsub("^%s*(.-)%s*$", "%1"))
+end
+
+
+function ctan_field(fname,fvalue,max,desc,mandatory,multi)
+ if (type(fvalue)=="table" and multi==true) then
+ for i, v in pairs(fvalue) do
+ ctan_single_field(fname,v,max,desc,mandatory and i==1)
+ end
+ else
+ ctan_single_field(fname,fvalue,max,desc,mandatory)
+ end
+end
+
+
+function ctan_single_field(fname,fvalue,max,desc,mandatory)
+ print('ctan-post: ' .. fname .. ' ' ..tostring(fvalue or '??'))
+ if ((fvalue==nil and mandatory) or (fvalue == 'ask')) then
+ if (max < 256) then
+ fvalue=input_single_line_field(fname)
+ else
+ fvalue=input_multi_line_field(fname)
+ end
+ end
+ if (fvalue==nil or type(fvalue)~="table") then
+ local vs=trim_space(tostring(fvalue))
+ if (mandatory==true and (fvalue == nil or vs=="")) then
+ error("The field " .. fname .. " must contain " .. desc)
+ end
+ if (fvalue ~=nil and string.len(vs) > 0) then
+ if (max > 0 and string.len(vs) > max) then
+ error("The field " .. fname .. " is longer than " .. max)
+ end
+ vs = vs:gsub('"','\\"')
+ vs = vs:gsub('`','\\`')
+ ctan_post=ctan_post .." --form " .. fname .. '="' .. vs .. '"'
+ end
+ else
+ error("The value of the field '" .. fname .."' must be a scalar not a table")
+ end
+end
+
+
+-- function for interactive multiline fields
+function input_multi_line_field (name)
+ print("Enter " .. name .. " three <return> or ctrl-D to stop")
+
+ local field=""
+
+ local answer_line
+ local return_count=0
+ repeat
+ io.write("> ")
+ io.flush()
+ answer_line=io.read()
+ if answer_line=="" then
+ return_count=return_count+1
+ else
+ for i=1,return_count,1 do
+ field = field .. "\n"
+ end
+ return_count=0
+ if answer_line~=nil then
+ field = field .. "\n" .. answer_line
+ end
+ end
+ until (return_count==3 or answer_line==nil)
+ return field
+end
+
+function input_single_line_field(name)
+ print("Enter " .. name )
+
+ local field=""
+
+ io.write("> ")
+ io.flush()
+ field=io.read()
+ return field
+end
+
Property changes on: trunk/Master/texmf-dist/scripts/l3build/l3build-upload.lua
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Modified: trunk/Master/texmf-dist/scripts/l3build/l3build-variables.lua
===================================================================
--- trunk/Master/texmf-dist/scripts/l3build/l3build-variables.lua 2018-12-18 23:32:36 UTC (rev 49449)
+++ trunk/Master/texmf-dist/scripts/l3build/l3build-variables.lua 2018-12-18 23:33:00 UTC (rev 49450)
@@ -185,3 +185,7 @@
-- Manifest options
manifestfile = manifestfile or "MANIFEST.md"
+
+-- Upload settings
+curlexe = curlexe or "curl"
+uploadconfig = uploadconfig or {}
Modified: trunk/Master/texmf-dist/scripts/l3build/l3build.lua
===================================================================
--- trunk/Master/texmf-dist/scripts/l3build/l3build.lua 2018-12-18 23:32:36 UTC (rev 49449)
+++ trunk/Master/texmf-dist/scripts/l3build/l3build.lua 2018-12-18 23:33:00 UTC (rev 49450)
@@ -1,4 +1,4 @@
-#!/usr/bin/env texlua
+#!/usr/bin/env texlua
--[[
@@ -65,6 +65,7 @@
build_require("manifest")
build_require("manifest-setup")
build_require("tagging")
+build_require("upload")
build_require("stdmain")
-- This has to come after stdmain(),
@@ -96,7 +97,7 @@
build_require("variables")
-- Ensure that directories are 'space safe'
-maindir = escapepath(maindir)
+maindir = escapepath(maindir)
docfiledir = escapepath(docfiledir)
sourcefiledir = escapepath(sourcefiledir)
supportdir = escapepath(supportdir)
@@ -125,12 +126,12 @@
--
-- Deal with multiple configs for tests
--
-
+
-- When we have specific files to deal with, only use explicit configs
-- (or just the std one)
if options["names"] then
checkconfigs = options["config"] or {stdconfig}
-else
+else
checkconfigs = options["config"] or checkconfigs
end
Modified: trunk/Master/texmf-dist/source/latex/l3build/l3build.dtx
===================================================================
--- trunk/Master/texmf-dist/source/latex/l3build/l3build.dtx 2018-12-18 23:32:36 UTC (rev 49449)
+++ trunk/Master/texmf-dist/source/latex/l3build/l3build.dtx 2018-12-18 23:33:00 UTC (rev 49450)
@@ -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
}
{}
@@ -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
@@ -124,14 +113,21 @@
\luavarseparator
\luavarset{checkconfigs}{\{\}}{Configurations to use for tests}
\luavarseparator
-\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{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 for \texttt{upload}}
\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 passed to engine when running checks}
+\luavarset{typesetopts}{"-interaction=nonstopmode"}{Options passed to engine when typesetting}
+\luavarset{unpackopts} {""} {Options passed to engine when unpacking}
+\luavarset{zipopts} {"-v -r -X"} {Options passed 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,28 +136,35 @@
\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}
+\luavarset{ctanzip}{ctanpkg ... "-ctan"}{Name of the zip file (without extension) created for upload to CTAN}
\luavarset{epoch} {1463734800} {Epoch (Unix date) to set for test runs}
\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{uploadconfig} {\meta{table}} {Metadata to describe the package for CTAN (see Table~\ref{tab:upload-setup})}
+\luavarset{uploadconfig.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
@@ -223,7 +226,7 @@
% }^^A
% }
%
-% \date{Released 2018-11-08}
+% \date{Released 2018-12-18}
%
% \maketitle
% \tableofcontents
@@ -236,8 +239,11 @@
%
% 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}.
%
% Each package will define its own |build.lua| configuration file which both sets variables (such as the name of the package) and may also provide custom functions.
@@ -301,31 +307,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 +407,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,13 +530,15 @@
% \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). 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.
+%
+% See Section~\ref{sec:tagging} for full details on this feature.
% \end{buildcmd}
%
% \begin{buildcmd}{unpack}
@@ -541,6 +553,15 @@
% By default this process allows files to be accessed in all standard |texmf| trees; this can be disabled by setting \var{unpacksearch} to |false|.
% \end{buildcmd}
%
+% \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{uploadconfig} 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.
+%
+% See Section~\ref{sec:upload} for full details on this feature.
+% \end{buildcmd}
+%
% \subsection{The \texttt{build.lua} file}
%
% The \texttt{build.lua} file used to control \pkg{l3build} is a simple Lua file
@@ -606,7 +627,7 @@
% \label{fig:module}
% \end{figure}
%
-% \subsection{Backward compatibly}
+% \subsection{Backwards compatibility}
%
% 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}
@@ -626,12 +647,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
@@ -641,8 +664,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
@@ -1145,28 +1166,36 @@
% \item Removal of blank lines
% \end{itemize}
%
+% After this normalization takes place, the file can not usually be rendered
+% properly. To check if the build system has produced a correct PDF, the
+% pre-normalization PDF can be found in the \texttt{build} folder.
+%
% To allow platform-independence, PDF-based tests must use only Type~1 or
% OpenType fonts: Type3 fonts are system-dependent. PDF files are
% engine-specific, thus one |.tpf| file should be stored per engine to be
% tested.
%
+%
% \section{Release-focussed features}
%
% \subsection{Automatic tagging}
+% \label{sec:tagging}
%
-% As detailed above, the |tag| target will automatically edit
+% The |tag| target can automatically edit
% source files to modify date and release tag. As standard, no automatic
-% replacement takes place, but setting up a |updae_tag()| function
-% will allow this to happen. This takes four arguments:
-% \begin{itemize}
+% replacement takes place, but setting up a |update_tag()| function
+% will allow this to happen. This function takes four input arguments:
+% \begin{enumerate}[nosep]
% \item The file name
% \item The full content of the file
% \item The tag name
% \item The tag date
-% \end{itemize}
-% and should return the (modified) contents for writing to disk.
+% \end{enumerate}
+% The |update_tag()| function should return the (modified) contents
+% for writing to disk.
% For example, the function used by |l3build| itself is
% shown in Figure~\ref{fig:update-tag}.
+%
% \begin{figure}
% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6]
% -- Detail how to set the version automatically
@@ -1256,6 +1285,72 @@
% \label{fig:PDF}
% \end{figure}
%
+%
+% \subsection{Automated upload to CTAN}
+% \label{sec:upload}
+%
+% The CTAN upload process is backed by an API, which \pkg{l3build} can use
+% to send zip files for release. Along with the file, a variety of metadata
+% must be specified about the package, including the version, license, and so on.
+% A description of this metadata is outlined in Table~\ref{tab:upload-setup},
+% 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.
+%
+%
+% \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.}
+% \label{tab:upload-setup}
+% \begin{minipage}{\linewidth}
+% \begin{tabular}{@{}lccp{8cm}@{}}
+% \toprule
+% Field & Req. & Multi & Description \\
+% \midrule
+% \texttt{author } & \YES & & Author name (semicolon-separated for multiple) \\
+% \texttt{ctanPath } & \YES & & CTAN path \\
+% \texttt{email } & \YES & & Email address of uploader \\
+% \texttt{license } & \YES & \YES & Package license(s)\footnote{See \url{https://ctan.org/license}} \\
+% \texttt{pkg } & \YES & & Package name \\
+% \texttt{summary } & \YES & & One-line summary \\
+% \texttt{uploader } & \YES & & Name of uploader \\
+% \texttt{version } & \YES & & Package version \\
+% \midrule
+% \texttt{announcement} & & & Announcement text \\
+% \texttt{bugtracker } & & \YES & URL(s) of bug tracker \\
+% \texttt{description } & & & Short description/abstract \\
+% \texttt{development } & & \YES & URL(s) of development channels \\
+% \texttt{home } & & \YES & URL(s) of home page \\
+% \texttt{note } & & & Internal note to CTAN \\
+% \texttt{repository } & & \YES & URL(s) of source repositories \\
+% \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 \\
+% \bottomrule
+% \end{tabular}
+% \end{minipage}
+% \end{table}
+%
+%
+% \begin{figure}[p]
+% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6]
+% uploadconfig = {
+% pkg = "vertbars",
+% version = "v1.0c",
+% author = "Peter R Wilson; Will Robertson",
+% license = "lppl1.3c",
+% summary = "Mark vertical rules in margin of text",
+% ctanPath = "/macros/latex/contrib/vertbars",
+% repository = "https://github.com/wspr/herries-press/",
+% uploader = "Will Robertson",
+% email = [...],
+% update = true,
+% }
+% \end{lstlisting}
+% \caption{Example of \texttt{uploadconfig} from the \pkg{vertbars} package.}
+% \label{fig:uploadconfig}
+% \end{figure}
+%
% \section{Lua interfaces}
%
% Whilst for the majority of users the simple variable-based control methods
@@ -1608,7 +1703,7 @@
%
% Within a single group in the manifest listing, files can be matched against multiple variables.
% For example, for |sourcefiles={*.dtx,*.ins}| the following (unsorted) file listing might result:
-% \begin{itemize}
+% \begin{itemize}[nosep]
% \item foo.dtx
% \item bar.dtx
% \item foo.ins
@@ -1833,7 +1928,7 @@
\begingroup % within the scope of this groups each line needs to end in % !
\catcode`\^^M\active %
\gdef\SHOWFILE#1{%
- \typeout{-------- #1 (start) ---------}%
+ \typeout{-------- #1 (start) ---------}%
\IfFileExists{#1}%
{\begingroup %
\catcode`\^^M\active %
@@ -1844,7 +1939,7 @@
\message{\@@input #1 }%
\endgroup }%
{\message{Not found}}%
- \typeout{-------- #1 (end) -----------}%
+ \typeout{-------- #1 (end) -----------}%
}%
\endgroup
% \end{macrocode}
More information about the tex-live-commits
mailing list