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

On Tue, 3 Oct 2023 16:06:59 -0400
Jeff King wrote:

quoted

 DESCRIPTION
 -----------
-In its first form, the command provides the content or the type of an object in
+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 the content or the type of an object in
 the repository. The type is required unless `-t` or `-p` is used to find the
 object type, or `-s` is used to find the object size, or `--textconv` or
 `--filters` is used (which imply type "blob").

The existing text here is already a bit vague, considering the number of
operations it covers (like "-e", for example, which is not showing "the
content or the type" at all). But that is not new in your patch, and it
is maybe even OK to be a bit vague here, and let the OPTIONS section
cover the specifics.

So how about we just butcher the DESCRIPTION completely; after all, the
information it gives is not quite correct (other than what you already
mentioned, e.g., -e is omitted in the "type not required" part; one is
left to wonder what <format> refers to: you have to go read the OPTIONS
and BATCH OUTPUT sections anyway), and the correct parts only duplicate
information given in the following sections, providing opportunities to
become out of date when the command and its documentation evolve:

Changes (if we agree this is the way to go, I'll also update the --help
output):
  synopsis:
    - move the (--textconv | --filters) form before --batch, closer
      to the other non-batch forms
    - cosmetics: swap -t and -s, --filters and --textconv (sort
      alphabetically)
  description:
    - reformulate, omit vague/imprecise information better
      provided in the detailed options list

SYNOPSIS
    git cat-file <type> <object>
    git cat-file (-e | -p) <object>
    git cat-file (-s | -t) [--allow-unknown-type] <object>
    git cat-file (--filters | --textconv)
                 [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]
    git cat-file (--batch | --batch-check | --batch-command) [--batch-all-objects]
                 [--buffer] [--follow-symlinks] [--unordered]
                 [--filters | --textconv] [-Z]

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

quoted

-In the second form, a list of objects (separated by linefeeds) is provided on
+In batch mode, a list of objects (separated by linefeeds) is provided on
 stdin, and the SHA-1, type, and size of each object is printed on stdout. The
 output format can be overridden using the optional `<format>` argument. If
 either `--textconv` or `--filters` was specified, the input is expected to

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.

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

-- 
Štěpán

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