[prev in list] [next in list] [prev in thread] [next in thread] 

List:       git
Subject:    [PATCH v2] manpage-bold-literal.xsl: match for namespaced "d:literal" in template
From:       Martin Ågren <martin.agren () gmail ! com>
Date:       2019-10-31 6:22:27
Message-ID: 20191031062227.14535-1-martin.agren () gmail ! com
[Download RAW message or body]

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

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

[prev in list] [next in list] [prev in thread] [next in thread]