[PATCH] doc txt & -h consistency: fix recent "cat-file" inconsistency

[PATCH] doc txt & -h consistency: fix recent "cat-file" inconsistency

[Ævar Arnfjörð Bjarmason]

The cat-file SYNOPSIS and help output were made consistent in
83dc443439c (cat-file: don't whitespace-pad "(...)" in SYNOPSIS and
usage output, 2022-01-10).

They then drifted apart again in 440c705ea63 (cat-file: add
--batch-command mode, 2022-02-18). Let's fix that and list the new
--batch-command option in the SYNOPSIS section.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/git-cat-file.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt
index 70c5b4f12d1..24a811f0ef6 100644
--- a/Documentation/git-cat-file.txt
+++ b/Documentation/git-cat-file.txt
@@ -12,7 +12,7 @@ SYNOPSIS
 'git cat-file' <type> <object>
 'git cat-file' (-e | -p) <object>
 'git cat-file' (-t | -s) [--allow-unknown-type] <object>
-'git cat-file' (--batch | --batch-check) [--batch-all-objects]
+'git cat-file' (--batch | --batch-check | --batch-command) [--batch-all-objects]
 	     [--buffer] [--follow-symlinks] [--unordered]
 	     [--textconv | --filters]
 'git cat-file' (--textconv | --filters)
-- 
2.36.0.rc0.849.g2d5b5d9ab01

Re: [PATCH] doc txt & -h consistency: fix recent "cat-file" inconsistency

[Junio C Hamano]

Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:

> Subject: Re: [PATCH] doc txt & -h consistency: fix recent "cat-file" inconsistency

IOW ...

> -'git cat-file' (--batch | --batch-check) [--batch-all-objects]
> +'git cat-file' (--batch | --batch-check | --batch-command) [--batch-all-objects]

... we forgot to add "--batch-command" to the documentation, even
though we added it to the usage text in the source.

And explained that way, this change makes quite a lot of sense.

It could be a worthwhile longer-term goal to make it consistent
between the synopsis and the usage text", but we are far away from
such a goal.  I'd rather keep such a topic outside this focused fix.

Given that we have been pushing to stop listing individual options
in SYNOPSIS, and instead using <option> placeholder, and also list
different operation mode of a single command on separate lines,
between

    $ git commit -h 2>&1 | sed -e '/^$/q'
    $ git commit --help | sed -ne '/^SYNOPSIS/,/^$/p'

we would want to pick the one we have from the command (i.e. the
former) and update the documentation source for the latter.

    Side note: and no, we do not want to tie the documentation to a
    particular build too tightly, and it is a no-no to generate the
    documentation source from 'git cmd -h' output.  Even when an
    option is conditionally excluded from a particular build, I'd
    like to be able to build and publish documentation for wider
    audience than just to myself.

Somebody needs to go through the comparison of individual
subcommands and present a good plan.  I find that, in comparison
between the -h and --help output, neither is quite satisfactory for
"git bisect", for example.  It would be a huge task and would be a
distraction during the pre-release period.

Thanks.

Re: [PATCH] doc txt & -h consistency: fix recent "cat-file" inconsistency

[Ævar Arnfjörð Bjarmason]

On Thu, Apr 07 2022, Junio C Hamano wrote:

> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:
>
>> Subject: Re: [PATCH] doc txt & -h consistency: fix recent "cat-file" inconsistency
>
> IOW ...
>
>> -'git cat-file' (--batch | --batch-check) [--batch-all-objects]
>> +'git cat-file' (--batch | --batch-check | --batch-command) [--batch-all-objects]
>
> ... we forgot to add "--batch-command" to the documentation, even
> though we added it to the usage text in the source.
>
> And explained that way, this change makes quite a lot of sense.
>
> It could be a worthwhile longer-term goal to make it consistent
> between the synopsis and the usage text", but we are far away from
> such a goal.  I'd rather keep such a topic outside this focused fix.

Yes, I just sent this one in because it's usage new in this release,
thank for merging it.

> Given that we have been pushing to stop listing individual options
> in SYNOPSIS, and instead using <option> placeholder, and also list
> different operation mode of a single command on separate lines,
> between
>
>     $ git commit -h 2>&1 | sed -e '/^$/q'
>     $ git commit --help | sed -ne '/^SYNOPSIS/,/^$/p'
>
> we would want to pick the one we have from the command (i.e. the
> former) and update the documentation source for the latter.

I think both should have the long form, but we don't need to argue that
point here.

> Somebody needs to go through the comparison of individual
> subcommands and present a good plan.  I find that, in comparison
> between the -h and --help output, neither is quite satisfactory for
> "git bisect", for example.  It would be a huge task and would be a
> distraction during the pre-release period.

I have a branch locally that fixes a lot more of these, it just uses
"sed" to extract both the -h output and the SYNOPSIS from the .txt,
normalizes both sides (e.g. getting rid of ASCIIDOC-markup) and does a
test_cmp of the two.

It finds a lot of issues which are worth fixing, and which I have some
queued patches for (but yeah, not during the rc etc.).

A lot have nothing to do with the "long form or <options>?" question. But just:

 * Basic formatting issues, e.g. using [-v|--version] instead of [-v |
   --version], or whitespace-padding or whatever.

 * Things like referring to <path> in .txt, and <pathspec> in -h, we
   should pick one and stick to it.

 * Cases where we're 100% the same but miss 1-2 options, e.g. this
   cat-file case, there's plenty more like it, e.g. ls-remote's -h is
   missing "[--sort=<key>]" (but nothing else).

>     Side note: and no, we do not want to tie the documentation to a
>     particular build too tightly, and it is a no-no to generate the
>     documentation source from 'git cmd -h' output.  Even when an
>     option is conditionally excluded from a particular build, I'd
>     like to be able to build and publish documentation for wider
>     audience than just to myself.

I don't have changes to do that, but I think the particular concern
you're airing here isn't an issue at all.

I.e. whatever other issues we'd enocunter with such auto-generation we
do not have *options* that are conditional on compilation, nor do we
have commands that we build and don't build the corresponding
documentation for.

Or the other way aroun,d i.e. if we don't build the command, we don't
build the docs, that's what EXCLUDED_PROGRAMS in the Makefile ferried up
to Documentation/Makefile is doing.

Anyway, I mentioned that as a solution in some past thread, but I think
it's probably not worth it v.s. just a test scraping and comparing the
two.

It's not that big of a deal to update both, it's mainly just that we're
forgetting it now because we have no structural checks in place.

And if we did come up with such a script but didn't want building the
docs to require a C compiler we could always make it something you run
as a developer and commit the result, which is pretty much what we do
now, just without the benefit of such a script.

Re: [PATCH] doc txt & -h consistency: fix recent "cat-file" inconsistency

[Junio C Hamano]

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

> I think both should have the long form, but we don't need to argue that
> point here.

Right.

>>     Side note: and no, we do not want to tie the documentation to a
>>     particular build too tightly, and it is a no-no to generate the
>>     documentation source from 'git cmd -h' output.  Even when an
>>     option is conditionally excluded from a particular build, I'd
>>     like to be able to build and publish documentation for wider
>>     audience than just to myself.
>
> I don't have changes to do that, but I think the particular concern
> you're airing here isn't an issue at all.
>
> I.e. whatever other issues we'd enocunter with such auto-generation we
> do not have *options* that are conditional on compilation, nor do we
> have commands that we build and don't build the corresponding
> documentation for.

The above seems to only scratch the status quo, while I was with
maintainer's hat on when I wrote the above, and was considering
future possibilities as well.  I can very much see us accepting a
patch to make "git grep -h" not showing "-P" when Git is built
without pcre support, for example.

Saying "at all", is a bit too strong with the argument you have, I
am afraid.