On Fri, Dec 03 2021, Eric Sunshine wrote:
> On Fri, Dec 3, 2021 at 4:15 AM Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> wrote:
>> On Thu, Dec 02 2021, Eric Sunshine wrote:
>> > -'git worktree list' [--porcelain]
>> > +'git worktree list' [-v | --porcelain]
>>
>> 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.
>>
>> Seems far preferrable to dual-maintaining all of these forever.
>>
>> But in the meantime this small fix is obviously correct.
>
> 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.)
True, I hadn't looked into how that worked before, but behold!
https://github.com/git/git-scm.com/blob/main/lib/tasks/index.rake
It seems to be a re-implementation of a non-trivial part of the doc
building process.
In any case, if we do end up generating more of the documentation
ourselves presumably any such concerns will be brought up then.
