Re: [PATCH v5 0/3] doc: introducing synopsis para

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 24, 2024, 17:16 UTC
Message-ID: <xmqq5xqlug4l.fsf@gitster.g>
In-Reply-To: <pull.1766.v5.git.1727161730.gitgitgadget@gmail.com>

"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:

> Changes since V4:
>
>  * used BRE in sed filter
>  * rework the processing of three dots

The topic has been deep in 'next' already, and I wasn't expecting a wholesale replacement. But thanks for updating.

As the patches are more in the technology demonstration phase by converting only a few pages and making sure other uses of `` outside the synopsis section in unconverted pages are not broken, we can declare that the three-patch series will not be in 2.47 and will keep it in 'next'. So let me revert the merge of the previous one out of 'next' and queue this one afresh to 'seen' to see how well it works.

Josh (or whoever is taking over this week from him at Google), can you see if the breakage you saw that stopped us merging the topic before it causes us trouble on 'master' reproduces with this version (either by running "make doc" on the topic branch by itself, or on 'seen' that merges the topic) in your environment that had trouble with the previous round?

It would also be highly appreciated if other macOS users try "make doc" and see the resulting git-init and git-clone documentation pages are reasonable, both for the previous round that has been cooking in 'next' and for this latest round. Inputs from folks on more mainstream platforms with modern asciidoc/asciidoctor toolchain would also help. The more people we have who look at how the new way the synopsis section is written and how the resulting documents get rendered, the more fairly we can assess the value of this topic.

Thanks.