System queries with Lua: l3sys-query

[Joseph Wright]

On 06/03/2024 23:13, Karl Berry wrote:
> - Both --help and --version start with a blank line. It's better not to do
> this, so that |sed 1q and the like can do something useful. There are
> scripts that collect that info.

Done (personally I find this a bit 'busy, but there we go).

> - If bad option or missing argument, don't give full help message.
> Instead, a la most GNU programs:
>
>    cp: missing file operand
>    Try 'cp --help' for more information.
>
>    cp: unrecognized option '--x'
>    Try 'cp --help' for more information.
Adjusted

> - If options are given with the pwd <cmd>, give an error message instead
> of silently ignoring:
> $ texlua l3sys-query.lua pwd -r
> /u/karl/tmp

Done

> - Similarly with unrecognized commands. "texlua l3sys-query.lua foo"
> should say something like "l3sys-query: unrecognized command: foo".

Adjusted inspired by the Git text:

     (base) joseph at palladium l3sys-query % ./l3sys-query.lua bong
     l3sys-query: 'bong' is not a l3sys-query command. See 'l3sys-query
       --help'.

(I haven't implemented the 'most similar command' business.)

> - In the --help msg, please give a sentence or two about what the program
> does, e.g. (if more features are added later, could be generalized):
>     Output the name or listing of the current directory.
>
> - In the --help, please explain what a <spec> is. Or use <glob>,
> and then explain that [...] is not supported (I gather).

There are two reasons here. First, I imagine that over time we might
want a more general 'thing' here rather than just a glob. For a start, I
suspect allowing a Lua pattern might be handy. I see Git uses "[<args>]"
here - would that make sense? (I'll hold off making a change until you
are David, at least, say this reads OK.)

Second, coming from a Windows background, the "[...]" syntax at the
command line is entire alien. So to me it's a gap I don't see. More
immediately, the code we have used to convert globs to patterns needs
about 30 lines for the */? setup and about 70 for "[...]". At the time
we set that up for l3build, the balance felt like it made more sense to
avoid "[...]". If we need it, we can add it - it's just a question of
copy-pasting some MIT-licensed code.

> - I suggest "Valid <cmd>s are:" instead of "Valid commands",
> likewise "Valid <options> are:", to refer back to the syntax line.

Done

> Apparently --sort takes an option, but the --help msg doesn't say that,
> or explain what it can be.
>
>     --sort            Method used to sort directory listing
>
>     --sort <type>     Method used to sort directory listing
>                        ...
> Ditto for --exclude, --type, any other options that take arguments.
> It's best, and conventional, to actually list the allowed values, but if
> you don't want to do that, at least indicate that an argument is
> required.
>
> I imagine it's all explained in the manual, but ...

That's the hope :)

> Please don't forget to make a man page. --thanks, karl.

We've set up to auto-generate, as it's the same as the help text: run
"l3build doc" to give the man page.

Joseph

P.S. I will attempt to update l3build with similar comments - have had
lots of opportunity to improve my Lua coding since we first wrote l3build :)