Re: [PATCH] Force listingblocks to be monospaced in manpages

Julian Phillips [off-list ref] writes:

I tried with your patch, both with asciidoc7 and asciidoc8.  Did
you really mean "⌂" above?  Replacing them with "."  gave
me a series of these changes (diff between output before and
after your patch with the "s/\⌂/./g" fixup):

        @@ -83,10 +83,13 @@
         .sp
         .RS 3n
         .nf
        +.ft C
             *** Commands ***
               1: status       2: update       3: revert       4: add untracked
               5: patch        6: diff         7: quit         8: help
             What now> 1
        +.ft
        +
         .fi
         .RE
         You also could say "s" or "sta" or "status" above as long as the choice is unique.

which seems reasonable, but I did not render them through roff.
WIth "⌂" I was getting:

        @@ -83,10 +83,14 @@
         .sp
         .RS 3n
         .nf
        +
        +	ft C
             *** Commands ***
               1: status       2: update       3: revert       4: add untracked
               5: patch        6: diff         7: quit         8: help
             What now> 1
        +	ft
        +
         .fi
         .RE
         You also could say "s" or "sta" or "status" above as long as the choice is unique.

whatever that 2302 is...

On Wed, 18 Jul 2007, Junio C Hamano wrote:

I tried with your patch, both with asciidoc7 and asciidoc8.  Did
you really mean "⌂" above?  Replacing them with "."  gave
me a series of these changes (diff between output before and
after your patch with the "s/\⌂/./g" fixup):

I did mean it.  I originally just had .ft, but I was getting \&.ft in the 
manpage, which then just came out as .ft in the console.

I got the ⌂ from 
http://docbook.sourceforge.net/release/xsl/current/manpages/utility.xsl, 
so I assumed it was the "correct" thing to use ...

This was with asciidoc 7 and docbook xsl stylesheet 1.72.0.

whatever that 2302 is...

⌂ (or U+2302) seems to be a character from the unicode "Misc. 
Technical" section ... looks a bit like a house.

See sixth bullet from 
http://docbook.sourceforge.net/release/xsl/current/RELEASE-NOTES.html#V1.72.0_Manpages

looks like it may need to depend on which docbook xsl version you are 
using ...

-- 
Julian

  ---
The only way to amuse some people is to slip and fall on an icy pavement.

For the html output we can use a stylesheet to make sure that the
listingblocks are presented in a monospaced font.  For the manpages do
it manually by inserting a ".ft C" before and ".ft" after the block in
question.  This makes the ascii-art diagrams readable in PS output.

In order for these roff commands to get through to the manpage they
have to be element encoded to prevent quoting.  In particular with
docbook xsl 1.72.0 and newer we have to use U+2302 instead of . to
prevent the roff command being escaped.  We also add a small perl
script for docbook < 1.72.0.

Signed-off-by: Julian Phillips <redacted>
---

On Thu, 19 Jul 2007, Julian Phillips wrote:

On Wed, 18 Jul 2007, Junio C Hamano wrote:

quoted

 I tried with your patch, both with asciidoc7 and asciidoc8.  Did
 you really mean "⌂" above?  Replacing them with "."  gave
 me a series of these changes (diff between output before and
 after your patch with the "s/\⌂/./g" fixup):

I did mean it.  I originally just had .ft, but I was getting \&.ft in the
manpage, which then just came out as .ft in the console.

I got the ⌂ from
http://docbook.sourceforge.net/release/xsl/current/manpages/utility.xsl, so I
assumed it was the "correct" thing to use ...

This was with asciidoc 7 and docbook xsl stylesheet 1.72.0.

quoted

 whatever that 2302 is...

⌂ (or U+2302) seems to be a character from the unicode "Misc.
Technical" section ... looks a bit like a house.

See sixth bullet from
http://docbook.sourceforge.net/release/xsl/current/RELEASE-NOTES.html#V1.72.0$

looks like it may need to depend on which docbook xsl version you are using
...

I couldn't find any way to detect the docbook version - perhaps someone more
with more knowledge of asciidoc might know?

Otherwise, something like this perhaps?

 Documentation/Makefile          |    3 +++
 Documentation/asciidoc.conf     |    6 ++++++
 Documentation/replace_U+2303.pl |    6 ++++++
 3 files changed, 15 insertions(+), 0 deletions(-)
 create mode 100755 Documentation/replace_U+2303.pl

diff --git a/Documentation/Makefile b/Documentation/Makefile
index b062757..e381b2e 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile

@@ -121,6 +121,9 @@ clean:
 
 %.1 %.5 %.7 : %.xml
 	xmlto -m callouts.xsl man $<
+	mv $@ $@.tmp
+	./replace_U+2303.pl < $@.tmp > $@
+	$(RM) $@.tmp
 
 %.xml : %.txt
 	$(RM) $@+ $@

diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 6b6220d..d54fe29 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf

@@ -27,7 +27,13 @@ ifdef::backend-docbook[]
 [listingblock]
 <example><title>{title}</title>
 <literallayout>
+ifdef::doctype-manpage[]
+&#10;&#x2302;ft C&#10;
+endif::doctype-manpage[]
 |
+ifdef::doctype-manpage[]
+&#10;&#x2302;ft&#10;
+endif::doctype-manpage[]
 </literallayout>
 {title#}</example>
 endif::backend-docbook[]

diff --git a/Documentation/replace_U+2303.pl b/Documentation/replace_U+2303.pl
new file mode 100755
index 0000000..b086949
--- /dev/null
+++ b/Documentation/replace_U+2303.pl

@@ -0,0 +1,6 @@
+#!/usr/bin/perl -w
+
+while ($line = <>) {
+	$line =~ s/^\x{2302}/./;
+	print $line;
+}

-- 
1.5.2.2

For the html output we can use a stylesheet to make sure that the
listingblocks are presented in a monospaced font.  For the manpages do
it manually by inserting a ".ft C" before and ".ft" after the block in
question.

In addition, also add an empty line after all verbatim blocks.

Signed-off-by: Jonas Fonseca <redacted>
---

  Julian Phillips [off-list ref] wrote Thu, Jul 19, 2007:
  > On Wed, 18 Jul 2007, Junio C Hamano wrote:
  > 
  > >I tried with your patch, both with asciidoc7 and asciidoc8.  Did
  > >you really mean "&#x2302;" above?  Replacing them with "."  gave
  > >me a series of these changes (diff between output before and
  > >after your patch with the "s/\&#x2302;/./g" fixup):
  > 
  > I did mean it.  I originally just had .ft, but I was getting \&.ft in the 
  > manpage, which then just came out as .ft in the console.
  
  This is because AsciiDoc does the escaping. I think it would be cleaner
  to do this thing when converting from DocBook to roff like we already
  do for other things.

  While fixing the above, a fix for separating verbatim blocks from any
  following blocks is easy to apply.

diff --git a/Documentation/callouts.xsl b/Documentation/callouts.xsl
index 6a361a2..44ab77d 100644
--- a/Documentation/callouts.xsl
+++ b/Documentation/callouts.xsl

@@ -27,4 +27,93 @@
   </xsl:if>
 </xsl:template>
 
+<!-- * Yes, address, synopsis, and funcsynopsisinfo are verbatim environments. -->
+<xsl:template match="literallayout|programlisting|screen|
+                     address|synopsis|funcsynopsisinfo">
+  <xsl:param name="indent">
+    <!-- * Only indent this verbatim if $man.indent.verbatims is -->
+    <!-- * non-zero and it is not a child of a *synopsis element -->
+    <xsl:if test="not($man.indent.verbatims = 0) and
+                  not(substring(local-name(..),
+                  string-length(local-name(..))-7) = 'synopsis')">
+      <xsl:text>Yes</xsl:text>
+    </xsl:if>
+  </xsl:param>
+
+  <xsl:choose>
+    <!-- * Check to see if this verbatim item is within a parent element that -->
+    <!-- * allows mixed content. -->
+    <!-- * -->
+    <!-- * If it is within a mixed-content parent, then a line space is -->
+    <!-- * already added before it by the mixed-block template, so we don't -->
+    <!-- * need to add one here. -->
+    <!-- * -->
+    <!-- * If it is not within a mixed-content parent, then we need to add a -->
+    <!-- * line space before it. -->
+    <xsl:when test="parent::caption|parent::entry|parent::para|
+                    parent::td|parent::th" /> <!-- do nothing -->
+    <xsl:otherwise>
+      <xsl:text>&#10;</xsl:text>
+      <xsl:text>.sp&#10;</xsl:text>
+    </xsl:otherwise>
+  </xsl:choose>
+  <xsl:if test="$indent = 'Yes'">
+    <!-- * start indented section -->
+    <xsl:text>.RS</xsl:text>
+    <xsl:if test="not($man.indent.width = '')">
+      <xsl:text> </xsl:text>
+      <xsl:value-of select="$man.indent.width"/>
+    </xsl:if>
+    <xsl:text>&#10;</xsl:text>
+  </xsl:if>
+  <xsl:choose>
+    <xsl:when test="self::funcsynopsisinfo">
+      <!-- * All Funcsynopsisinfo content is by default rendered in bold, -->
+      <!-- * because the man(7) man page says this: -->
+      <!-- * -->
+      <!-- *   For functions, the arguments are always specified using -->
+      <!-- *   italics, even in the SYNOPSIS section, where the rest of -->
+      <!-- *   the function is specified in bold -->
+      <!-- * -->
+      <!-- * Look through the contents of the man/man2 and man3 directories -->
+      <!-- * on your system, and you'll see that most existing pages do follow -->
+      <!-- * this "bold everything in function synopsis" rule. -->
+      <!-- * -->
+      <!-- * Users who don't want the bold output can choose to adjust the -->
+      <!-- * man.font.funcsynopsisinfo parameter on their own. So even if you -->
+      <!-- * don't personally like the way it looks, please don't change the -->
+      <!-- * default to be non-bold - because it's a convention that's -->
+      <!-- * followed is the vast majority of existing man pages that document -->
+      <!-- * functions, and we need to follow it by default, like it or no. -->
+      <xsl:text>.ft </xsl:text>
+      <xsl:value-of select="$man.font.funcsynopsisinfo"/>
+      <xsl:text>&#10;</xsl:text>
+      <xsl:text>.nf&#10;</xsl:text>
+      <xsl:apply-templates/>
+      <xsl:text>&#10;</xsl:text>
+      <xsl:text>.fi&#10;</xsl:text>
+      <xsl:text>.ft&#10;</xsl:text>
+    </xsl:when>
+    <xsl:otherwise>
+      <!-- * Other verbatims do not need to get bolded -->
+      <xsl:text>.nf&#10;</xsl:text>
+      <xsl:text>.ft C&#10;</xsl:text>
+      <xsl:apply-templates/>
+      <xsl:text>&#10;</xsl:text>
+      <xsl:text>.ft&#10;</xsl:text>
+      <xsl:text>&#10;</xsl:text>
+      <xsl:text>&#10;.fi&#10;</xsl:text>
+    </xsl:otherwise>
+  </xsl:choose>
+  <xsl:if test="$indent = 'Yes'">
+    <!-- * end indented section -->
+    <xsl:text>.RE&#10;</xsl:text>
+  </xsl:if>
+  <!-- * if first following sibling node of this verbatim -->
+  <!-- * environment is a text node, output a line of space before it -->
+  <xsl:if test="following-sibling::node()[1][name(.) = '']">
+    <xsl:text>.sp&#10;</xsl:text>
+  </xsl:if>
+</xsl:template>
+
 </xsl:stylesheet>

-- 
Jonas Fonseca

On Thu, 19 Jul 2007, Jonas Fonseca wrote:

For the html output we can use a stylesheet to make sure that the
listingblocks are presented in a monospaced font.  For the manpages do
it manually by inserting a ".ft C" before and ".ft" after the block in
question.

In addition, also add an empty line after all verbatim blocks.

Signed-off-by: Jonas Fonseca <redacted>
---

 Julian Phillips [off-list ref] wrote Thu, Jul 19, 2007:
 > On Wed, 18 Jul 2007, Junio C Hamano wrote:
 >
 > >I tried with your patch, both with asciidoc7 and asciidoc8.  Did
 > >you really mean "&#x2302;" above?  Replacing them with "."  gave
 > >me a series of these changes (diff between output before and
 > >after your patch with the "s/\&#x2302;/./g" fixup):
 >
 > I did mean it.  I originally just had .ft, but I was getting \&.ft in the
 > manpage, which then just came out as .ft in the console.

 This is because AsciiDoc does the escaping. I think it would be cleaner
 to do this thing when converting from DocBook to roff like we already
 do for other things.

No.  Docbook does the escaping (as it says here: 
http://docbook.sourceforge.net/release/xsl/current/RELEASE-NOTES.html#V1.72.0
).  I tried your approach first, but 1) I idn't want to copy that much 
from the docbook xsl, as then we won't get updates/changes/fixes etc, 2) I 
still had to use ⌂ _anyway_.

Just compare the chunk that you have copied from the docbook xsl to the 
version from 1.72.0 and you will find that all the '.'s have become 
⌂s ...

-- 
Julian

  ---
"It's when they say 2 + 2 = 5 that I begin to argue."
-- Eric Pepke

Julian Phillips [off-list ref] wrote Thu, Jul 19, 2007:

On Thu, 19 Jul 2007, Jonas Fonseca wrote:

quoted

This is because AsciiDoc does the escaping. I think it would be cleaner
to do this thing when converting from DocBook to roff like we already
do for other things.

No.  Docbook does the escaping (as it says here: 
http://docbook.sourceforge.net/release/xsl/current/RELEASE-NOTES.html#V1.72.0
).

Oops, yes, you are right.

I tried your approach first, but 1) I idn't want to copy that much 
from the docbook xsl, as then we won't get updates/changes/fixes etc, 2) I 
still had to use ⌂ _anyway_.

OK, I didn't think you tried it. Nevermind then.

-- 
Jonas Fonseca