patch, 3 partsAsciidoctor fixes for 2.48.0

> After the recent a38edab7c8 (Makefile: generate doc versions via
> GIT-VERSION-GEN, 2024-12-06), building with Asciidoctor results in
> manpages where the headers no longer contain "Git Manual" and the
> footers no longer identify the built Git version.
> 
> Before a38edab7c8, we used to just provide a few attributes to
> Asciidoctor (and asciidoc). Commit 7a30134358 (asciidoctor-extensions:
> provide `<refmiscinfo/>`, 2019-09-16) noted that older versions of
> Asciidoctor didn't propagate those attributes into the built XML files,
> so we started injecting them ourselves from this script. With newer
> versions of Asciidoctor, we'd end up with some harmless duplication
> among the tags in the final XML.

> Post-a38edab7c8, we don't provide these attributes and Asciidoctor
> inserts empty-ish values. After our additions from 7a30134358, we get
> 
>   <refmiscinfo class="source">&#160;</refmiscinfo>
>   <refmiscinfo class="manual">&#160;</refmiscinfo>
>   <refmiscinfo class="source">2.47.1.[...]</refmiscinfo>
>   <refmiscinfo class="manual">Git Manual</refmiscinfo>
> 
> When these are handled, it appears to be first come first served,
> meaning that our additions have no effect and we regress as described in
> the first paragraph.
> 
> Remove existing "source" or "manual" <refmiscinfo/> tags before adding
> ours. I considered removing all <refmiscinfo/> to get a nice clean
> slate, instead of just those two that we want to replace to be a bit
> more precise. I opted for the latter. Maybe one day, Asciidoctor learns
> to insert something useful there which `xmlto` can pick up and make good
> use of -- let's not interfere.

> Signed-off-by: Martin Ågren <martin.agren@gmail.com>
> ---
>  Documentation/asciidoctor-extensions.rb.in | 2 ++
>  1 file changed, 2 insertions(+)
> 
> diff --git a/Documentation/asciidoctor-extensions.rb.in b/Documentation/asciidoctor-extensions.rb.in
> index c4c200dace..d8d06f9a57 100644
> --- a/Documentation/asciidoctor-extensions.rb.in
> +++ b/Documentation/asciidoctor-extensions.rb.in
> @@ -29,6 +29,8 @@ module Git
>      class DocumentPostProcessor < Asciidoctor::Extensions::Postprocessor
>        def process document, output
>          if document.basebackend? 'docbook'
> +          output = output.sub(/<refmiscinfo class="source">.*?<\/refmiscinfo>/, "")
> +          output = output.sub(/<refmiscinfo class="manual">.*?<\/refmiscinfo>/, "")
>            new_tags = "" \
>              "<refmiscinfo class=\"source\">@GIT_VERSION@</refmiscinfo>\n" \
>              "<refmiscinfo class=\"manual\">Git Manual</refmiscinfo>\n"

> The Asciidoctor build of the documentation regressed a bit with
> a38edab7c8 (Makefile: generate doc versions via GIT-VERSION-GEN,
> 2024-12-06).
>
> I think these issues and fixes are fairly orthogonal to the recent
> discussions beginning at [1], with fixes being discussed beginning at
> [2]. I've tested these here patches on top of that series' v1 [2]
> rebased onto a38edab7c8, as well as on top of its recent v3 [3] as
> applied on the indicated base-commit.
>
> With these patches, I can use
>
>   make USE_ASCIIDOCTOR=YesPlease doc
>
> and
>
>   ./doc-diff --asciidoctor <...> <...>
>
> with similar results as pre-a38edab7c8.
>
> On top of current master [4], these patches help, but for "doc-diff",
> the GIT_VERSION injection is still broken (as expected, that's why
> [1,2,3] exist). These here patches don't refer to doc-diff or those
> other patches [2,3] and could go in independently or on top.
>
> These patches are based on [3] applied on its indicated base-commit.
>
> [1] https://lore.kernel.org/git/20241218113324.GA594795@coredump.intra.peff.net/
>
> [2] https://lore.kernel.org/git/20241219-b4-pks-git-version-via-environment-v1-0-9393af058240@pks.im/
>
> [3] https://lore.kernel.org/git/20241220-b4-pks-git-version-via-environment-v3-0-1fd79b52a5fb@pks.im/
>
> [4] v2.48.0-rc0-38-gff795a5c5e

>
> Martin
>
> Martin Ågren (3):
>   asciidoctor-extensions.rb.in: delete existing <refmiscinfo/>
>   asciidoctor-extensions.rb.in: add missing word
>   asciidoctor-extensions.rb.in: inject GIT_DATE
>
>  Documentation/asciidoctor-extensions.rb.in | 5 ++++-
>  1 file changed, 4 insertions(+), 1 deletion(-)

> Martin Ågren <martin.agren@gmail.com> writes:
> 
> > The Asciidoctor build of the documentation regressed a bit with
> > a38edab7c8 (Makefile: generate doc versions via GIT-VERSION-GEN,
> > 2024-12-06).
> >
> > I think these issues and fixes are fairly orthogonal to the recent
> > discussions beginning at [1], with fixes being discussed beginning at
> > [2]. I've tested these here patches on top of that series' v1 [2]
> > rebased onto a38edab7c8, as well as on top of its recent v3 [3] as
> > applied on the indicated base-commit.
> >
> > With these patches, I can use
> >
> >   make USE_ASCIIDOCTOR=YesPlease doc
> >
> > and
> >
> >   ./doc-diff --asciidoctor <...> <...>
> >
> > with similar results as pre-a38edab7c8.
> >
> > On top of current master [4], these patches help, but for "doc-diff",
> > the GIT_VERSION injection is still broken (as expected, that's why
> > [1,2,3] exist). These here patches don't refer to doc-diff or those
> > other patches [2,3] and could go in independently or on top.
> >
> > These patches are based on [3] applied on its indicated base-commit.
> >
> > [1] https://lore.kernel.org/git/20241218113324.GA594795@coredump.intra.peff.net/
> >
> > [2] https://lore.kernel.org/git/20241219-b4-pks-git-version-via-environment-v1-0-9393af058240@pks.im/
> >
> > [3] https://lore.kernel.org/git/20241220-b4-pks-git-version-via-environment-v3-0-1fd79b52a5fb@pks.im/
> >
> > [4] v2.48.0-rc0-38-gff795a5c5e
> 
> Thanks.  [2][3] are something we have to have before we can tag 2.48
> to have a healthy build with the usual Makefile; so is a working
> Asciidoctor based documentation generation, so building your doc
> toolchain fixes on top of the fixes for 'GIT-VERSION-GEN' does not
> give us any practical problem.
> 
> Thanks for a fix.  Will queue.

>> Thanks.  [2][3] are something we have to have before we can tag 2.48
>> to have a healthy build with the usual Makefile; so is a working
>> Asciidoctor based documentation generation, so building your doc
>> toolchain fixes on top of the fixes for 'GIT-VERSION-GEN' does not
>> give us any practical problem.
>> 
>> Thanks for a fix.  Will queue.
>
> Thanks indeed, the changes look good to me.
>
> I guess my key learning is to do largish patch series like the build
> refactorings in smaller increments next time. I considered doing it
> several times while implementing the series, but shied away from it. I
> guess it would have been easier for everyone involved and would have led
> to fewer issues though if I did split it up.