On Tue, Oct 03, 2023 at 10:25:13AM +0200, Štěpán Němec wrote:
> The DESCRIPTION's "first form" is actually the 1st, 2nd, 3rd and 5th
> form in SYNOPSIS, the "second form" is the 4th one.
>
> Interestingly, this state of affairs was introduced in
> 97fe7250753b (cat-file docs: fix SYNOPSIS and "-h" output, 2021-12-28)
> with the claim of "Now the two will match again." ("the two" being
> DESCRIPTION and SYNOPSIS)...
>
> Ordinals are hard, let's try talking about batch and non-batch mode
> instead.
Thanks, I think this is a good direction. Two things I noticed:
> DESCRIPTION
> -----------
> -In its first form, the command provides the content or the type of an object in
> +This command can operate in two modes, depending on whether an option from
> +the `--batch` family is specified.
> +
> +In non-batch mode, the command provides the content or the type of an object in
> the repository. The type is required unless `-t` or `-p` is used to find the
> object type, or `-s` is used to find the object size, or `--textconv` or
> `--filters` is used (which imply type "blob").
The existing text here is already a bit vague, considering the number of
operations it covers (like "-e", for example, which is not showing "the
content or the type" at all). But that is not new in your patch, and it
is maybe even OK to be a bit vague here, and let the OPTIONS section
cover the specifics.
> -In the second form, a list of objects (separated by linefeeds) is provided on
> +In batch mode, a list of objects (separated by linefeeds) is provided on
> stdin, and the SHA-1, type, and size of each object is printed on stdout. The
> output format can be overridden using the optional `<format>` argument. If
> either `--textconv` or `--filters` was specified, the input is expected to
I think this got a bit inaccurate with "--batch-command", which is a
whole different mode itself compared to --batch and --batch-check. I
don't think your patch is really making anything worse, but arguably
there are three "major modes" here.
-Peff
