From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Fri, 08 Apr 2022 08:55:46 GMT
Subject: Re: [PATCH] doc txt & -h consistency: fix recent "cat-file" inconsistency
Message-ID: <220408.864k34c4wo.gmgdl@evledraar.gmail.com>
In-Reply-To: <xmqqv8vkr64h.fsf@gitster.g>


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.