Re: [PATCH] doc/cat-file: clarify description regarding various command forms

From: Jeff King <peff@peff.net>
Date: Oct 3, 2023, 20:06 UTC
Message-ID: <20231003200659.GC1562@coredump.intra.peff.net>
In-Reply-To: <20231003082513.3003520-1-stepnem@smrk.net>

On Tue, Oct 03, 2023 at 10:25:13AM +0200, Štěpán Němec wrote:

Show 10 quoted lines

> 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:

Show 10 quoted lines

>  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.

Show 5 quoted lines

> -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