@@ -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/>
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@gmail.com> --- Range-diff against v1: 1: fb5372c3cf ! 1: a22ed4896c manpage-bold-literal.xsl: provide namespaced template for "d:literal" @@ Metadata Author: Martin Ågren <martin.agren@gmail.com> ## 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@gmail.com> @@ 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(-)