Subject: Re: [bug#74878] [PATCH 2/2] scripts: substitute: Improve the help output.

From: Ludovic Courtès <[email-masked]>
Date: Mon, 23 Dec 2024 18:39:07 +0100

Hi,

Richard Sent <[email-masked]> skribis:

> Clarify that arguments are read from standard input and that --query expects a
> command.
>
> * guix/scripts/substitute.scm (show-help): Reword.
>
> Change-Id: Ifc197d5e10e43663f1e05039ce29086f6a21b943

[...]

>  (define (show-help)
>    (display (G_ "Usage: guix substitute OPTION [ARGUMENT]...
> -Internal tool to substitute a pre-built binary to a local build.\n"))
> +Internal tool to substitute a pre-built binary to a local build.
> +
> +ARGUMENT is read from standard input, not from the command line.\n"))

I find this sentence confusing since the usage line above shows that
it’s a command-line argument.  But since there’s no such argument, we
can just remove “[ARGUMENT]...” from the usage line.

>    (display (G_ "
> -      --query            report on the availability of substitutes for the
> -                         store file names passed on the standard input"))
> +      --query COMMAND STORE-FILE ...
> +                         Run query COMMAND with STORE-FILE to report on
> +                         the availability of substitutes"))

I think this also adds to the confusion since ‘--query’ doesn’t actually
take any arguments.

Note that the protocol ‘guix-daemon’ and ‘guix substitute’ is
purposefully undocumented: it’s an implementation detail and users are
not supposed to use ‘guix substitute’ directly.

Thoughts?

Ludo’.