[PATCH 0/3] Asciidoctor fixes for 2.48.0

[PATCH 0/3] Asciidoctor fixes for 2.48.0

[Martin Ågren]

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(-)

-- 
2.48.0.rc0.241.g3cddc25e2a

[PATCH 1/3] asciidoctor-extensions.rb.in: delete existing <refmiscinfo/>

[Martin Ågren]

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"
-- 
2.48.0.rc0.241.g3cddc25e2a

[PATCH 2/3] asciidoctor-extensions.rb.in: add missing word

[Martin Ågren]

Commit a38edab7c8 (Makefile: generate doc versions via GIT-VERSION-GEN,
2024-12-06) stopped providing an attribute value "Git $(GIT_VERSION)" to
asciidoc/Asciidoctor over the command line. Instead, we now provide the
attribute to asciidoc through a generated asciidoc.conf, where the value
is generated as "Git @GIT_VERSION@".

In the similar mechanism for Asciidoctor, we forgot the "Git" prefix.
Restore it.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/asciidoctor-extensions.rb.in | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/asciidoctor-extensions.rb.in b/Documentation/asciidoctor-extensions.rb.in
index d8d06f9a57..fd1b84c2be 100644
--- a/Documentation/asciidoctor-extensions.rb.in
+++ b/Documentation/asciidoctor-extensions.rb.in
@@ -32,7 +32,7 @@ module Git
           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=\"source\">Git @GIT_VERSION@</refmiscinfo>\n" \
             "<refmiscinfo class=\"manual\">Git Manual</refmiscinfo>\n"
           output = output.sub(/<\/refmeta>/, new_tags + "</refmeta>")
         end
-- 
2.48.0.rc0.241.g3cddc25e2a

[PATCH 3/3] asciidoctor-extensions.rb.in: inject GIT_DATE

[Martin Ågren]

After a38edab7c8 (Makefile: generate doc versions via GIT-VERSION-GEN,
2024-12-06), we no longer inject GIT_DATE when building with
Asciidoctor.

Replace the <date/> tag in the XML to inject the value of GIT_DATE.
Unlike <refmiscinfo/> as handled in a recent commit, we have no reason
to expect that this tag might be missing, so there's no need for "maybe
remove, then add" and we can just outright replace the one that
Asciidoctor has generated based on the mtime of the source file.

Compared to pre-a38edab7c8, we now end up injecting this also in the
build of Git.3pm, which until now has been using the mtime of Git.pm.
That is arguably even a good change since it results in more
reproducible builds.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/asciidoctor-extensions.rb.in | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/asciidoctor-extensions.rb.in b/Documentation/asciidoctor-extensions.rb.in
index fd1b84c2be..2494f17a51 100644
--- a/Documentation/asciidoctor-extensions.rb.in
+++ b/Documentation/asciidoctor-extensions.rb.in
@@ -31,6 +31,7 @@ module Git
         if document.basebackend? 'docbook'
           output = output.sub(/<refmiscinfo class="source">.*?<\/refmiscinfo>/, "")
           output = output.sub(/<refmiscinfo class="manual">.*?<\/refmiscinfo>/, "")
+          output = output.sub(/<date>.*?<\/date>/, "<date>@GIT_DATE@</date>")
           new_tags = "" \
             "<refmiscinfo class=\"source\">Git @GIT_VERSION@</refmiscinfo>\n" \
             "<refmiscinfo class=\"manual\">Git Manual</refmiscinfo>\n"
-- 
2.48.0.rc0.241.g3cddc25e2a

Re: [PATCH 0/3] Asciidoctor fixes for 2.48.0

[Junio C Hamano]

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.
>
> 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(-)

Re: [PATCH 1/3] asciidoctor-extensions.rb.in: delete existing <refmiscinfo/>

[Patrick Steinhardt]

On Sat, Dec 21, 2024 at 12:18:16AM +0100, Martin Ågren wrote:
> 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.

Okay. So if I understand correctly, we used to have the exact same
values for those tags twice with newer versions of Asciidoctor, but
starting with the change we have one "empty" set of tags and one set of
tags that contain the replaced values. And because Asciidoctor ignores
the latter the end result is that we have empty ref info.

> 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.

Okay, makes sense.

> 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"

And this looks as expected.

Patrick

Re: [PATCH 0/3] Asciidoctor fixes for 2.48.0

[Patrick Steinhardt]

On Fri, Dec 20, 2024 at 06:42:21PM -0800, Junio C Hamano wrote:
> 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 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.

So thanks to all the people that are helping out in this context!

Patrick

Re: [PATCH 0/3] Asciidoctor fixes for 2.48.0

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

>> 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.

FWIW, from the project maintainer's point of view, the trickling
rate of all of your series was not overly too fast.  As long as the
reactions to problems discovered can keep up with the same rate, I
do not share the "smaller increments as we did too much too fast"
sentiment myself.

If you are referring to the fact that you have to scramble and fix
the reported breakages on multiple fronts quickly near the end of
year holiday season to keep the release candidate healthy, and
regretting that we went a little too fast, then yeah, I can
understand it and we may want to pace ourselves the next time to
lessen the stress on all of us a bit ;-)

> So thanks to all the people that are helping out in this context!

Yes, big thanks to everybody.