Re: [PATCH 2/2] git-worktree.txt: add missing `-v` to synopsis for `worktree list`

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Mon, Dec 06 2021, Eric Sunshine wrote:

> On Sun, Dec 5, 2021 at 4:12 AM Junio C Hamano <gitster@pobox.com> wrote:
>> Eric Sunshine <sunshine@sunshineco.com> writes:
>> > On Fri, Dec 3, 2021 at 4:15 AM Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:
>> >> Aside: I've been thinking of hacking something up to just change all
>> >> these "[verse]" bits in the *.txt source to:
>> >>
>> >>     [verse]
>> >>     $(git worktree -h)
>> >>
>> >> And then have the doc build process pick that up, run 'git $name -h', do
>> >> some light search/replacement (e.g. "$cmd" to "'$cmd'") and build the
>> >> docs like that.
>> >
>> > One caution that springs to mind is that there may be external tooling
>> > which processes these documentation files directly, and such a change
>> > might break them. (The one which popped to mind immediately was the
>> > git-scm.{org,com} website, though I don't know what their tooling
>> > looks like.)
>>
>> Also it would slow us down by making the .txt variant we see in the
>> source tree harder to read (or in this case, impossible to see without
>> building the documentation).
>
> Taking this point into consideration, a middle-ground alternative to
> Ævar's idea would be to add tooling which only compares (by some
> definition of "compare") the output of `git blah -h` with the synopsis
> in `git-blah.txt` and complains if there are significant differences
> (by some definition "significant" and "difference"). It doesn't
> automate-away the work of keeping the synopsis up-to-date, but at
> least would flag inconsistencies.

Or we could do the reverse and move the source code version of it to be
generated from the [verse] sections in the documentation.

Anyway, it's not something I was planning to work on any time soon, just
something I'd thought was a good idea for a while, especially given the
differences and divergenge. That can be viewed with:

    parallel -k '
        git {} -h 2>&1 | grep -e "^usage" -e "^   or";
        git help {} 2>&1 | grep -A20 SYNOPSIS | grep -B20 DESCRIPTION
    ' ::: $(git --list-cmds=builtins) | less

It's a long-standing UX issue, and we keep re-introducing divergence
between the two.

If we're going to insist that the version in the *.txt file isn't
generated that categorically closes the door to some logical follow-ups.

E.g. having parse-options automatically generate alternates in cases
where options are mutually exclusive, or adding color output to this
where we color short/long options differently than arguments etc.

That and e.g. translators needing to do less work for the translated
manpages (we already have the translated output in the C code).

Well, I suppose we could have a generating step and then commit the
equivalent of the compiled file (or section) into git.git every time we
add/change an option.

In general I don't think it's a worthwhile goal to keep the .txt
versions of the docs as some human-readable 1=1 mapping to what you'd
get if you generated them. That's already not the case due to includes,
and e.g. in this case accepting some reasonable amount of
auto-generation would make them easier to maintain.