From: Eric Sunshine Date: Mon, 06 Dec 2021 13:34:11 GMT Subject: Re: [PATCH 2/2] git-worktree.txt: add missing `-v` to synopsis for `worktree list` Message-ID: In-Reply-To: On Sun, Dec 5, 2021 at 4:12 AM Junio C Hamano wrote: > Eric Sunshine writes: > > On Fri, Dec 3, 2021 at 4:15 AM Ævar Arnfjörð Bjarmason 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.