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

From: Štěpán Němec <stepnem@smrk.net>
Date: Oct 5, 2023, 17:48 UTC
Message-ID: <20231005194852+0200.262756-stepnem@smrk.net>
In-Reply-To: <20231005171827.GC975921@coredump.intra.peff.net>

On Thu, 5 Oct 2023 13:18:27 -0400 Jeff King wrote:

Show 20 quoted lines

> On Thu, Oct 05, 2023 at 01:20:18PM +0200, Štěpán Němec wrote:
>
>> So how about we just butcher the DESCRIPTION completely;
>> [...]
>> DESCRIPTION
>>     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 information on an object
>>     named on the command line.
>> 
>>     In batch mode, arguments are read from standard input.
>> 
>> [That's all for a summary, read the following sections for details.]
>
> Yeah, I think that is a big improvement over the status quo. I might
> also be worth starting with a single-sentence overview of what is common
> to both modes. Something like:
>
>   Output the contents or details of one or more objects. [...]

I thought about that when proposing the rewrite, but feel that it would again just duplicate what's said elsewhere, in this case even before, not after, in the very first line of the man page:

    git-cat-file - Provide content or type and size information for
    repository objects

Show 5 quoted lines

>   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 information on a single object
>   given on the command line.

    ^^^^^
Any particular reason you prefer "given" to "named"?  However absurd a
notion of giving an actual object on the command line might seem, to me
"named" is better in that it leaves no room for such misinterpretation.
And the <object> description in OPTIONS talks about "ways to spell
object names", building on the same concept.

-- 
Štěpán