On Thu, 5 Oct 2023 17:01:25 -0400
Jeff King wrote:
> 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
