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

From: Štěpán Němec <stepnem@smrk.net>
Date: Oct 9, 2023, 08:36 UTC
Message-ID: <20231009103651+0200.580831-stepnem@smrk.net>
In-Reply-To: <20231005210125.GA981206@coredump.intra.peff.net>

On Thu, 5 Oct 2023 17:01:25 -0400 Jeff King wrote:

Show 20 quoted lines

> On Thu, Oct 05, 2023 at 07:48:52PM +0200, Štěpán Němec wrote:
>
>> > 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
>
> Ah, true, I was thinking that the DESCRIPTION section would be the first
> thing users would read, but I didn't notice the headline. I agree that
> what it says is probably sufficient (though arguably "type and size" is
> slightly inaccurate there; I said "details" in my proposed text but
> maybe that is too vague).

We could also leave the NAME vague(r) and put an additional sentence at the beginning of DESCRIPTION:

NAME
    git-cat-file - Provide contents or details of repository objects

SYNOPSIS
    [...]

DESCRIPTION
    Output the contents or other properties such as size, type or delta
    information of one or more objects.

    The command can operate [...]

-- 
Štěpán