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

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

  In batch mode, arguments are read from standard input.

quoted

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.

This is not obvious to me (the "three major modes" part).  AIUI it's
still mainly a batch (read from stdin) vs. non-batch (args on command
line) dichotomy.  The details differ (just args vs. command + args), but
so does e.g. -e differ in providing information via exit code rather
than stdout.

Yeah, I think you understand it correctly. But what the current text
(both before and after your proposed patch) says about batch mode is:

  In batch mode, a list of objects (separated by linefeeds) is provided
  on stdin, [...]

which I think is not really true of --batch-command. But the rewrite you
suggest above takes care of that nicely, I think.

(But please note I'm not trying to pose as an expert here: this all
started with me coming to git-cat-file(1) to _learn_ about cat-file
and finding the description more than a little confusing.)

That is a very valuable perspective. I am probably too much an expert in
cat-file, and it has rotted my brain. ;)

-Peff