We recently regressed our rendering of "literal" elements in our
manpages, i.e, stuff we have placed within `backticks` in order to
render as monospace. In particular, we lost the bold rendering of such
literal text.
The culprit is f6461b82b9 ("Documentation: fix build with Asciidoctor 2",
2019-09-15), where we switched from DocBook 4.5 to DocBook 5 with
Asciidoctor. As part of the switch, we started using the namespaced
DocBook XSLT stylesheets rather than the non-namespaced ones. (See
f6461b82b9 for more details on why we changed to the namespaced ones.)
The bold literals are implemented as an XSLT snippet <xsl:template
match="literal">...</xsl:template>. Now that we use namespaces, this
doesn't pick up our literals like it used to.
Add an exact copy of the template where we match for "d:literal" instead
of just "literal", after defining the d namespace. ("d" is what
http://docbook.sourceforge.net/release/xsl-ns/current/manpages/docbook.xsl
uses.) Note that we need to keep the non-namespaced version for
AsciiDoc.
This boldness was introduced by 5121a6d993 ("Documentation: option to
render literal text as bold for manpages", 2009-03-27) and made the
default in 5945717009 ("Documentation: bold literals in man",
2016-05-31).
One reason this was not caught in review is that our doc-diff tool diffs
without any boldness, i.e., it "only" compares text.
This has been optically tested with AsciiDoc 8.6.10, Asciidoctor 1.5.5
and Asciidoctor 2.0.10. I've also verified that doc-diff produces the
empty output in all three cases, as expected.
Signed-off-by: Martin Ågren <martin.agren@xxxxxxxxx>
---
I've kept thinking lately that "wow, are we behind on marking up stuff
to be monospaced/boldened"...
I'm pretty sure about the background here, but I'm not at all sure
that this is the prettiest or correctest fix.
Not sure if this problem is bad enough (and the fix good enough) for
this to go into 2.24, but I offer this anyway.
There are more manpage-*.xsl -- manpage-suppress-sp.xsl looks like it
would have the exact same problem. But before diving in too deep, I'd
rather submit this one to see if it's in the right direction at all.
Martin
Documentation/manpage-bold-literal.xsl | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/Documentation/manpage-bold-literal.xsl b/Documentation/manpage-bold-literal.xsl
index 608eb5df62..172388d6cf 100644
--- a/Documentation/manpage-bold-literal.xsl
+++ b/Documentation/manpage-bold-literal.xsl
@@ -1,11 +1,20 @@
<!-- manpage-bold-literal.xsl:
special formatting for manpages rendered from asciidoc+docbook -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
+ xmlns:d="http://docbook.org/ns/docbook";
version="1.0">
<!-- render literal text as bold (instead of plain or monospace);
this makes literal text easier to distinguish in manpages
viewed on a tty -->
+<xsl:template match="d:literal">
+ <xsl:value-of select="$git.docbook.backslash"/>
+ <xsl:text>fB</xsl:text>
+ <xsl:apply-templates/>
+ <xsl:value-of select="$git.docbook.backslash"/>
+ <xsl:text>fR</xsl:text>
+</xsl:template>
+
<xsl:template match="literal">
<xsl:value-of select="$git.docbook.backslash"/>
<xsl:text>fB</xsl:text>
--
2.24.0.rc2
