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

From: Jeff King <peff@peff.net>
Date: Oct 5, 2023, 21:01 UTC
Message-ID: <20231005210125.GA981206@coredump.intra.peff.net>
In-Reply-To: <20231005194852+0200.262756-stepnem@smrk.net>

On Thu, Oct 05, 2023 at 07:48:52PM +0200, Štěpán Němec wrote:

Show 12 quoted lines

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

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

Nope, I didn't even do that replacement consciously (I was just fleshing out my example, and ended up deciding nothing else needed to be changed). So "named" is fine by me.

Thanks.

-Peff