From: Philippe Proulx <eeppeliteloop@gmail.com>
Date: Mon, 3 May 2021 19:46:51 +0000 (-0400)
Subject: doc/man/manpage.xsl: do not indent the title of an admonition block
X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=commitdiff_plain;h=65750bcdda3dd71b72683573d35a662c0b467a8f;hp=e358ddd51a5be6017f524523ac10d7c17fb78f65

doc/man/manpage.xsl: do not indent the title of an admonition block

See the new comment in `manpage.xsl` for more details.

I copied and modified some upstream DocBook XSL (as found in
`xsl/manpages/block.xsl`).

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
Change-Id: I765ce37957907edb4088a4212c1b12af8b485e60
---

diff --git a/doc/man/manpage.xsl b/doc/man/manpage.xsl
index d576e1406..5f6a39642 100644
--- a/doc/man/manpage.xsl
+++ b/doc/man/manpage.xsl
@@ -1,7 +1,7 @@
 <?xml version='1.0'?>
 <xsl:stylesheet version="1.0"
                 xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
-    <!-- callouts -->
+    <!-- Callouts -->
     <xsl:template match="*[local-name() = 'co']">
         <xsl:value-of select="concat('\','fB(',substring-after(@id,'-'),')','\','fR')"/>
     </xsl:template>
@@ -18,7 +18,7 @@
         <xsl:text>br&#10;</xsl:text>
     </xsl:template>
 
-    <!-- links -->
+    <!-- Links -->
     <xsl:template match="*[local-name() = 'ulink']">
         <xsl:apply-templates/><xsl:text> &lt;</xsl:text><xsl:value-of select="@url"/><xsl:text>&gt;</xsl:text>
     </xsl:template>
@@ -26,13 +26,87 @@
         <xsl:text>\fI</xsl:text><xsl:apply-templates/><xsl:text>\fR</xsl:text>
     </xsl:template>
 
-    <!-- literal -->
+    <!-- Literal -->
     <xsl:template match="*[local-name() = 'literal']">
         <xsl:text>\fB</xsl:text>
         <xsl:value-of select="." />
         <xsl:text>\fR</xsl:text>
     </xsl:template>
 
-    <!-- disable end notes -->
+    <!--
+        Make admonitions look like this:
+
+            Some paragraph.
+
+            Note
+                Sit sed culpa elit dolore esse irure dolor amet magna
+                veniam elit ut.
+
+                Duis adipisicing magna quis in in in reprehenderit
+                proident minim cupidatat dolore sit minim deserunt duis dolore ex ea.
+
+            Next paragraph.
+
+        instead of:
+
+            Some paragraph.
+
+                Note
+                Sit sed culpa elit dolore esse irure dolor amet magna
+                veniam elit ut.
+
+                Duis adipisicing magna quis in in in reprehenderit
+                proident minim cupidatat dolore sit minim deserunt duis
+                dolore ex ea.
+
+            Next paragraph.
+
+        This looks better when, for example, you put a note immediately
+        after a list:
+
+        Ambiguous:
+            •   Some list item.
+
+            •   Some other list item.
+
+                Note
+                Does this note apply to the last list item or to the
+                previous block?
+
+        Clear:
+            •   Some list item.
+
+            •   Some other list item.
+
+            Note
+                This note applies to the previous block.
+    -->
+    <xsl:template match="caution|important|note|tip|warning">
+        <xsl:call-template name="roff-if-start">
+            <xsl:with-param name="condition">n</xsl:with-param>
+        </xsl:call-template>
+        <xsl:text>.sp&#10;</xsl:text>
+        <xsl:call-template name="roff-if-end"/>
+        <xsl:if test="not($man.output.better.ps.enabled = 0)">
+            <xsl:text>.BM yellow&#10;</xsl:text>
+        </xsl:if>
+        <xsl:call-template name="pinch.together"/>
+        <xsl:text>.ps +1&#10;</xsl:text>
+        <xsl:call-template name="make.bold.title"/>
+        <xsl:text>.ps -1&#10;</xsl:text>
+        <xsl:text>.br&#10;</xsl:text>
+        <xsl:text>.RS 4&#10;</xsl:text>
+        <xsl:apply-templates/>
+        <xsl:text>.sp .5v&#10;</xsl:text>
+        <xsl:if test="not($man.output.better.ps.enabled = 0)">
+            <xsl:text>.EM yellow&#10;</xsl:text>
+        </xsl:if>
+        <xsl:text>.RE&#10;</xsl:text>
+    </xsl:template>
+
+    <!-- Disable end notes -->
     <xsl:param name="man.endnotes.are.numbered">0</xsl:param>
+
+    <!-- Disable hyphenation, except for URLs -->
+    <xsl:param name="man.hyphenate">0</xsl:param>
 </xsl:stylesheet>