Skip to content

Commit

Permalink
asciidoctor-extensions.rb.in: delete existing <refmiscinfo/>
Browse files Browse the repository at this point in the history
After the recent a38edab (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 a38edab, we used to just provide a few attributes to
Asciidoctor (and asciidoc). Commit 7a30134 (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 7a30134, 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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
  • Loading branch information
Martin Ågren authored and gitster committed Dec 21, 2024
1 parent f5f82c0 commit 298805c
Showing 1 changed file with 2 additions and 0 deletions.
2 changes: 2 additions & 0 deletions Documentation/asciidoctor-extensions.rb.in
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down

0 comments on commit 298805c

Please sign in to comment.