On Mon, Dec 06 2021, Eric Sunshine wrote:

On Sun, Dec 5, 2021 at 4:12 AM Junio C Hamano [off-list ref] wrote:

quoted

Eric Sunshine [off-list ref] writes:

quoted

On Fri, Dec 3, 2021 at 4:15 AM Ævar Arnfjörð Bjarmason [off-list ref] wrote:

quoted

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.