We recently regressed our rendering with Asciidoctor 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.
Match for "d:literal" in addition to 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 matching without the namespace 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. As pointed out by
Peff in review of this patch, one can use `MAN_KEEP_FORMATTING=1
./doc-diff <...>`
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 for all three programs, as expected, and that with the
MAN_KEEP_FORMATTING trick, AsciiDoc yields no diff, whereas with
Asciidoctor, we get bold literals, just like we want.
Signed-off-by: Martin Ågren <martin.agren@xxxxxxxxx>
---
Range-diff against v1:
1: fb5372c3cf ! 1: a22ed4896c manpage-bold-literal.xsl: provide namespaced template for "d:literal"
@@ Metadata
Author: Martin Ågren <martin.agren@xxxxxxxxx>
## Commit message ##
- manpage-bold-literal.xsl: provide namespaced template for "d:literal"
+ manpage-bold-literal.xsl: match for namespaced "d:literal" in template
- 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.
+ We recently regressed our rendering with Asciidoctor 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
@@ Commit message
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
+ Match for "d:literal" in addition to 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
+ uses.) Note that we need to keep matching without the namespace for
AsciiDoc.
This boldness was introduced by 5121a6d993 ("Documentation: option to
@@ Commit message
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.
+ without any boldness, i.e., it "only" compares text. As pointed out by
+ Peff in review of this patch, one can use `MAN_KEEP_FORMATTING=1
+ ./doc-diff <...>`
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 for all three programs, as expected.
+ empty output for all three programs, as expected, and that with the
+ MAN_KEEP_FORMATTING trick, AsciiDoc yields no diff, whereas with
+ Asciidoctor, we get bold literals, just like we want.
Signed-off-by: Martin Ågren <martin.agren@xxxxxxxxx>
@@ Documentation/manpage-bold-literal.xsl
<!-- 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:template match="literal">
++<xsl:template match="literal|d:literal">
<xsl:value-of select="$git.docbook.backslash"/>
<xsl:text>fB</xsl:text>
+ <xsl:apply-templates/>
Documentation/manpage-bold-literal.xsl | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/Documentation/manpage-bold-literal.xsl b/Documentation/manpage-bold-literal.xsl
index 608eb5df62..94d6c1b545 100644
--- a/Documentation/manpage-bold-literal.xsl
+++ b/Documentation/manpage-bold-literal.xsl
@@ -1,12 +1,13 @@
<!-- 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="literal">
+<xsl:template match="literal|d:literal">
<xsl:value-of select="$git.docbook.backslash"/>
<xsl:text>fB</xsl:text>
<xsl:apply-templates/>
--
2.24.0.rc2
