On Sun, Dec 5, 2021 at 4:12 AM Junio C Hamano <gitster@xxxxxxxxx> wrote:
> Eric Sunshine <sunshine@xxxxxxxxxxxxxx> writes:
> > On Fri, Dec 3, 2021 at 4:15 AM Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> 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.
