man

[jlaurens]

Here is a proposal for a man page, comments and suggestions are welcome before it is ever turned into a commit. you can man ./l3build.1.txt to see the man page live. It uses rather basic formatting commands but should be tested in various OS. Below is a version with no format attributes (no bold, no underline).

L3BUILD(1)                  General Commands Manual                 L3BUILD(1)

NAME
       l3build - utility to build, check, upload to CTAN packages for TeX,
       LaTeX or ConTeXt

SYNOPSIS
       l3build target [options] [--] [name1 name2...]
       l3build --version
       l3build --help|-h

DESCRIPTION
       The l3build utility is part of the l3build bundle. It is designed to
       support the development of high-quality TeX, LaTeX and ConTeXt code by
       providing:

       •   A unit testing system
       •   Automated typesetting of code sources
       •   A reliable packaging system for CTAN releases

       The l3build utility needs to run in a properly setup directory. All
       explanations are detailed in the full pdf manual, available by running
       the command `texdoc l3build`.

TARGETS AND OPTIONS
       The targets and their options are:

       check
           Runs automated tests name1, name2... or all the tests when no name
           is provided

           --config|-c cfg1,cfg2...
               Sets the config(s) used for running tests
           --dirty
               Skips cleaning up the test area
           --engine|-E engine1,engine2...
               Sets the engine(s) to use for running test
           --epoch epoch
               Sets the epoch to use for running test
            --first test_name
               Name of the first test to run
           --halt-on-error|-H
               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
            --last test_name
               Name of the last test to run
           --rerun
               Runs tests without unpacking/set up
           --show-log-on-error
               To be used in addition to --halt-on-error and results in the
               full .log file of a failed test to be shown on the console
           --show-saves|-S
               When tests fail, prints the l3build save commands needed to
               regenerate the tests assuming that the failures were false
               negatives
           --shuffle
               Shuffles the order in which tests run
           --stdengine|-s
               Run tests only with the standard engine (which can vary between
               configurations)

       clean
           Removes all temporary files created by check, doc, ctan targets

       ctan
           Starts by running check, and if it succeeds an adapted install.
           Finally creates an archive of the package and its documentation,
           suitable for uploading to CTAN.  All options of these targets are
           accepted, except that --engine is ignored.

       doc
           Typesets all documentation files

           --epoch epoch
               Sets the epoch to use for typesetting
           --rerun
               Skips setup: simply retypeset

       help
           Prints help similar to this page

       install
           Copies all package files into the user's home texmf tree in the
           form of the TeX Directory Structure.

           --dry-run
               Runs the target but does not copy any files: simply lists those
               that would be installed
           --full
               Includes the docand sourcetrees
           --texmfhome
               Location of user texmf tree

       manifest
           Creates a manifest file

       save
           Runs like target check for all given names, saves the output of the
           test to a .tlg file, name1 is required

           --dirty
               Skips cleaning up the test area
           --engine|-e engine1,engine2...
               Sets the engine(s) used to build test validation log for saving

       tag
           Updates release tags in files

           --date date
               Sets the date to insert into sources

           When provided, name1 is used to tag the sources

       uninstall
           Uninstalls files from the local texmf tree

           --dry-run
               Simulates uninstall
           --texmfhome
               Location of user texmf tree

       unpack
           Unpacks the source files into the build tree

           --quiet|-q
               Suppresses TeX output

       upload
           Upload the package zip file (created using ctan) to CTAN for public
           release

           --dry-run
               Simulates upload
           --email address
               Email address of CTAN uploader, takes precedence over --file
           --file|-F file
               Takes the announcement from the given file
           --message|-m message
               Text for announcement message, takes precedence over --file

           When provided name1 is used to tag the sources, taking precedence
           over file contents

       version
            Prints version information and exits

SPECIAL OPTIONS
       Next options are treated first, target can be omitted:

           --help|-h
               Prints help similar to this page ad exits, takes precedence
               over --version
           --version
               Prints version information and exits

       Last option is shared by all the targets:

           --debug
               Runs target in debug mode (not supported by all targets)

SEE ALSO
       Full manual available via `texdoc l3build`.
       Repository : https://github.com/latex3/l3build
       Bug tracker: https://github.com/latex3/l3build/issues

AUTHORS
       Copyright (C) 2014-2024 The LaTeX Project

TeX, LaTeX, ConTeXt               2024-05-27                        L3BUILD(1)

l3build.1.txt

[josephwright]

We already have an (auto-generated) man entry ...

[jlaurens]

Yes, please take some time to compare both man pages.

[josephwright]

Like other (La)TeX code and tools, the documentation for l3build is provided by texdoc - man support is there essentially to keep KB happy :)

[josephwright]

(Key of course being that anything in addition to texdoc needs to be kept in-sync, which really means auto-generation in some way.)

[jlaurens]

This man page contains things that are not in l3build.pdf. And things more correct as well.

[jlaurens]

The actual page is buggy, due to the approximate md to nroff translator.

[josephwright]

@jlaurens if you find errors in l3build.dtx, please let us know: they will need to be addressed there

[jlaurens]

The problem is first to agree on what is an error...

[FrankMittelbach]

The problem is first to agree on what is an error...

how true.

but in general I think (a slightly inferior) autogenerated man page is preferable over one that has to be maintained manually and so will get stale over time ... the main documentation is l3build.dtx and anything else should derive from that. l3build ---help says use texdoc l3build for more info and imho that fine and so does man l3build

[jlaurens]

So man l3build would be slightly inferior to the man page above.

[josephwright]

The problem is first to agree on what is an error...

Please do give details - I am not sure what errors there are in the docs, but do want to fix any

[jlaurens]

Good news. Let me start smoothly:

• quite every l3build ... usage is incorrect. Very annoying
• section 1.3: targets are sorted alphabetically whereas they should be organized semantically. The same for options. Extremely annoying.
• section 5.6 is absolutely useless as is. Annoying.

Plus the errors in some previous PRs of mine.

[josephwright]

* quite every `l3build ...` usage is incorrect. Very annoying

I'm not at all sure what you mean here: as far as I know, the targets are described correctly. Could you be more specific?

* section 1.3: targets are sorted alphabetically whereas they should be organized semantically. The same for options. Extremely annoying.

That's a judgement not a error: to me (at least), alphabetical is the logical choice.

* section 5.6 is absolutely useless as is. Annoying.

I'm really not sure what you mean here: we certainly allow for additional targets, so that does need coverage. Perhaps it could be improved - it's not something that's been used a lot beyond the team ourselves.

Plus the errors in some previous PRs of mine.

[jlaurens]

* quite every `l3build ...` usage is incorrect. Very annoying

I'm not at all sure what you mean here: as far as I know, the targets are described correctly. Could you be more specific?

line 349, missing [--] [<name(s)>] lines 354, 358, 361, 362 <name(s)> is to the left of the options lines 401, and all similar \begin{buildcmd}{...}}, missing [<options>]

BTW, <name1> <name2>... is far better than <name(s)>.

* section 1.3: targets are sorted alphabetically whereas they should be organized semantically. The same for options. Extremely annoying.

That's a judgement not a error: to me (at least), alphabetical is the logical choice.

The alphabetical order is more practical for the programmer or natural to you. What you find logical is also a judgment. Alphabetical ordering is useful when you already know the target but not if you only know what you want to do. Semantical ordering is always useful. Moreover, semantical ordering allows to group targets in subsections and share informations for a better understanding. For example alphabetically, check is so long before save, but semantically and chronologically check should be just after save. And then, you can detail the options for save and say in the check section that options are the same plus supplemental ones.

Does --rerun concern the check? Because it is only mentioned in the check <name(s)> section.... Of course I know the answer...

So the choice of alphabetical order here is not really driven by communication considerations, which can be considered an error in a documentation.

* section 5.6 is absolutely useless as is. Annoying.

I'm really not sure what you mean here: we certainly allow for additional targets, so that does need coverage. Perhaps it could be improved - it's not something that's been used a lot beyond the team ourselves.

My bad, it is only the option_list part that can't work as is because it is only used by require"l3build-arguments" long before build.lua is ever executed.

If target_list is amended in build.lua, then it is too late to have the changes in the help(). There are also some subtleties with the bundle structure that should be addressed.

[u-fischer]

but semantically and chronologically check should be just after save

Well no. I typically use check (with option -S) before I (re)save as I much more often change existing tests than write new ones. Which shows the problem of semantical ordering: As l3build addresses a large variety of use cases it is not always clear which semantical ordering is the best, a "neutral" ordering by alphabet is easier here.

[josephwright]

I'm not at all sure what you mean here: as far as I know, the targets are described correctly. Could you be more specific?

line 349, missing [--] [<name(s)>] lines 354, 358, 361, 362 <name(s)> is to the left of the options lines 401, and all similar \begin{buildcmd}{...}}, missing [<options>]

I think this reflects a difference in expectation. The l3build docs assume that with the general form of command line input in mind, the info should be given in an easy-to-read way but without giving formal details. (Aside: I didn't draft the initial doc structure - and it has always made sense to me.) Thus we have

• Line 349, 'missing [--] [<name(s)>]' -

  We could adjust here - I'm not sure we need the [--] but could add the [<name(s)>] (which with hindsight should
  have been [<value(s)>], but that ship has sailed).

• Lines 354, 358, 361, 362 '<name(s)> is to the left of the options'

  The aim here is to show where the various targets take <name(s)> - whether or not options also apply is a distraction

• \begin{buildcmd}{...}}, missing [<options>]

  Again, the aim here is to signpost the targets - adding formal stuff about options would make the docs harder to parse in my view

BTW, <name1> <name2>... is far better than <name(s)>.

At least to me, <name1>, etc., suggests a fixed maximum number (perhaps as I mainly code in TeX, where number of arguments is strictly limited).

[jlaurens]

[...] The l3build docs assume that with the general form of command line input in mind [...]

What is really a "general form of command line input"? Beware: "in mind" ⇒ Cognitive pressure ⇒ less understanding capacities ⇒ reading difficulties Of course this no longer applies when reading the document for the nth time, n big enough

, the info should be given in an easy-to-read way but without giving formal details. (Aside: I didn't draft the initial doc structure - and it has always made sense to me.)

Ok for the overall document structure. But there is no structure on the target list documentation, except alphabetical ordering: there is no real sense to make here. More meaning should help.

Thus we have

• Line 349, 'missing [--] [<name(s)>]' - We could adjust here - I'm not sure we need the [--] but could add the [<name(s)>]

Consider this similar to the SYNOPSIS content of the man page and l3build help: "could" ⇒ "must". [--] is standard when there is a risk of collision, even with near 0% probability. No big cost.

(which with hindsight should have been [<value(s)>], but that ship has sailed).

Numbers and boolean are not expected, so "name" is a good choice. On the contrary, "command" seems a bit more appropriate than "target", except for l3build manifest: we wonder for what noble cause is this manifestation.

• Lines 354, 358, 361, 362 '<name(s)> is to the left of the options' The aim here is to show where the various targets take <name(s)> - whether or not options also apply is a distraction

This contradicts "where ⟨target⟩ can be one of the following:"

• \begin{buildcmd}{...}}, missing [<options>] Again, the aim here is to signpost the targets - adding formal stuff about options would make the docs harder to parse in my view

signpost ⇒ implicit complex deciphering ⇒ reading difficulties IMO, the target reader finds "|check| target" easier to read (=decipher+understand) than "$ |l3build check|".

BTW, <name1> <name2>... is far better than <name(s)>.

At least to me, <name1>, etc., suggests a fixed maximum number (perhaps as I mainly code in TeX, where number of arguments is strictly limited).

That is not really a problem, on the contrary this is sane. The command line arguments are limited in size (and sometimes number) and this is system dependent. However, reaching the limit hardly ever happens in everyday use. Of course the limit is far bigger than with raw TeX, even if it is possible to emulate in TeX more than 9 arguments in some situations.

[jlaurens]

@u-fischer

but semantically and chronologically check should be just after save

Well no. I typically use check (with option -S) before I (re)save as I much more often change existing tests than write new ones. Which shows the problem of semantical ordering: As l3build addresses a large variety of use cases it is not always clear which semantical ordering is the best, a "neutral" ordering by alphabet is easier here.

1. This is usage, not semantics.
2. check does nothing without a prior save

[josephwright]

2. `check` does nothing without a prior `save`

Sure, but which you need first depends on where in a development cycle you are, and what you are doing. Similarly, install is useful when using someone else's package, but is much less so if it's your own code and you are making changes.