Manpage rendering faults
I often read manpages using a `man -t whatever | ggv -' command, since I like how it is rendered in PostScript. However, it turns out that some things in the Git manpages don't really render very well using that method. For example, in the git-rebase manpage, there are two history graphs that look like this when reading the manpages normally in a terminal:
A---B---C topic
/D---E---F---G master
and then
A'--B'--C' topic
/D---E---F---G master
However, in the PostScript rendering, they look rather like this:
A---B---C topic
/
D---E---F---G master
and then
A'--B'--C' topic
/D---E---F---G master
It took me quite a while to figure out that the rendering was wrong. Before that, I just couldn't figure out why git-rebase would do that. :)
Unfortunately, I can't say that I have a fix available -- particularly as I don't really know anything at all about asciidoc. I thought I'd at least let you know, though.
Fredrik Tolf
Quoted 6 lines · Fredrik Tolf
I often read manpages using a `man -t whatever | ggv -' command, since I like how it is rendered in PostScript. However, it turns out that some things in the Git manpages don't really render very well using that method. For example, in the git-rebase manpage, there are two history graphs that look like this when reading the manpages normally in a terminal:
It's a proportional font issue ...
Running "groff -Tps -f C -man $(man -w git-rebase) | ggv -" should display it correctly. (The "-f C" being the part the man doesn't do)
No idea how to make it use that font by default though ... not even sure if you can put that kind of information into a man page?
Signature · 7 lines
Julian --- Dinner suggestion #302 (Hacker's De-lite): 1 tin imported Brisling sardines in tomato sauce 1 pouch Chocolate Malt Carnation Instant Breakfast 1 carton milk
Quoted 9 lines · Julian Phillips
Quoted 6 lines · Fredrik Tolf
I often read manpages using a `man -t whatever | ggv -' command, since I like how it is rendered in PostScript. However, it turns out that some things in the Git manpages don't really render very well using that method. For example, in the git-rebase manpage, there are two history graphs that look like this when reading the manpages normally in a terminal:
Quoted 7 lines
It's a proportional font issue ...
Running "groff -Tps -f C -man $(man -w git-rebase) | ggv -" should display it correctly. (The "-f C" being the part the man doesn't do)
No idea how to make it use that font by default though ... not even sure if you can put that kind of information into a man page?
Well, if it were a "pure" manpage, I'd try to use pic(1) to do it for the PS version, but I don't suspect asciidoc has a similar feature. I don't actually know, though -- again, I know virtually nothing about asciidoc.
Fredrik Tolf
PATCH 1/1 Force listingblocks to be monospaced in manpages
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 order for these roff commands to get through to the manpage they have to be element encoded to prevent quoting.
---
Quoted 16 lines · Fredrik Tolf
Quoted 14 lines · Julian Phillips
Quoted 6 lines · Fredrik Tolf
I often read manpages using a `man -t whatever | ggv -' command, since I like how it is rendered in PostScript. However, it turns out that some things in the Git manpages don't really render very well using that method. For example, in the git-rebase manpage, there are two history graphs that look like this when reading the manpages normally in a terminal:
It's a proportional font issue ...
Running "groff -Tps -f C -man $(man -w git-rebase) | ggv -" should display it correctly. (The "-f C" being the part the man doesn't do)
Quoted 7 lines
Quoted 2 lines
No idea how to make it use that font by default though ... not even sure if you can put that kind of information into a man page?
Well, if it were a "pure" manpage, I'd try to use pic(1) to do it for the PS version, but I don't suspect asciidoc has a similar feature. I don't actually know, though -- again, I know virtually nothing about asciidoc.
How about this?
Seems to work for me - but I'm not an asciidoc/docbook/roff expert ...
Documentation/asciidoc.conf | 6 ++++++ 1 files changed, 6 insertions(+), 0 deletions(-)
Documentation/asciidoc.conf +6 -0
@@ -27,7 +27,13 @@ ifdef::backend-docbook[] [listingblock] <example><title>{title}</title> <literallayout> +ifdef::doctype-manpage[] + ⌂ft C +endif::doctype-manpage[] | +ifdef::doctype-manpage[] + ⌂ft +endif::doctype-manpage[] </literallayout> {title#}</example> endif::backend-docbook[]
Signature · 1 line
1.5.2.2
Re: [PATCH] Force listingblocks to be monospaced in manpages
Quoted 26 lines · Julian Phillips
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 order for these roff commands to get through to the manpage they have to be element encoded to prevent quoting.
Signed-off-by Julian Phillips <[email protected]>...
How about this?Seems to work for me - but I'm not an asciidoc/docbook/roff expert ...
Documentation/asciidoc.conf | 6 ++++++ 1 files changed, 6 insertions(+), 0 deletions(-)Documentation/asciidoc.conf +0
-0@@ -27,7 +27,13 @@ ifdef::backend-docbook[] [listingblock] <example><title>{title}</title> <literallayout>
Documentation/asciidoc.conf ifdef::backend-docbook[] · line 39
Quoted 10 lines
Documentation/asciidoc.conf +6
-0+ifdef::doctype-manpage[] + ⌂ft C +endif::doctype-manpage[] | +ifdef::doctype-manpage[] + ⌂ft +endif::doctype-manpage[] </literallayout> {title#}</example> endif::backend-docbook[]
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...
Re: [PATCH] Force listingblocks to be monospaced in manpages
Quoted 4 lines · Junio C Hamano
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 1 line
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 ...
Signature · 4 lines
Julian --- The only way to amuse some people is to slip and fall on an icy pavement.
PATCH 1/1 Force listingblocks to be monospaced in manpages
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.
---
Quoted 19 lines · Julian Phillips
Quoted 4 lines · Junio C Hamano
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 1 line
whatever that 2302 is...
Quoted 10 lines
⌂ (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
Documentation/Makefile +3 -0
@@ -121,6 +121,9 @@ clean: %.1 %.5 %.7 : %.xml xmlto -m callouts.xsl man $< + mv $@ [email protected] + ./replace_U+2303.pl < [email protected] > $@ + $(RM) [email protected] %.xml : %.txt $(RM) $@+ $@
Documentation/asciidoc.conf +6 -0
@@ -27,7 +27,13 @@ ifdef::backend-docbook[] [listingblock] <example><title>{title}</title> <literallayout> +ifdef::doctype-manpage[] + ⌂ft C +endif::doctype-manpage[] | +ifdef::doctype-manpage[] + ⌂ft +endif::doctype-manpage[] </literallayout> {title#}</example> endif::backend-docbook[]
Documentation/replace_U+2303.pl new file +6 -0
@@ -0,0 +1,6 @@ +#!/usr/bin/perl -w + +while ($line = <>) { + $line =~ s/^\x{2302}/./; + print $line; +}
Signature · 1 line
1.5.2.2
Re: [PATCH] Force listingblocks to be monospaced in manpages
Quoted 5 lines · Julian Phillips
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.
This does not work at all for docbook 1.71. I get "^<TAB>ft C" as output from xmlto.
Re: [PATCH] Force listingblocks to be monospaced in manpages
Quoted 10 lines · Junio C Hamano
Quoted 5 lines · Julian Phillips
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.
This does not work at all for docbook 1.71. I get "^<TAB>ft C" as output from xmlto.
Oh, well ... that's handy? :S
I've just checked, and I do have a machine with docbook < 1.72, so I'll see if I can get something working on both. Probably early next week since I'm away this weekend.
Signature · 4 lines
Julian --- Words are the voice of the heart.
PATCH 1/1 Update listingblock monospace fix to support all docbook versions
The previous fix to force the listingblock to be monospaced would not work for docbook versions 1.72 or newer, as they now escape leading '.'s and you have to use U+2302 instead. However you can't use U+2302 in ealier versions ...
So this uses the string '#GIT#SET#MAN#FONT#', and then changes that to .ft using a post-process perl script.
Not pretty, but it works.
---
Quoted 10 lines · Julian Phillips
Quoted 8 lines · Junio C Hamano
Quoted 5 lines · Julian Phillips
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.
Quoted 8 lines
Quoted 2 lines
This does not work at all for docbook 1.71. I get "^<TAB>ft C" as output from xmlto.
Oh, well ... that's handy? :S
I've just checked, and I do have a machine with docbook < 1.72, so I'll see if I can get something working on both. Probably early next week since I'm away this weekend.
This works ... but I'm not particularly proud of it.
I've done this a patch ontop of master, since you seem to have already pushed out the tweaked version of my original patch.
Documentation/Makefile | 3 +++ Documentation/asciidoc.conf | 4 ++-- Documentation/insert_man_font_commands.pl | 6 ++++++ 3 files changed, 11 insertions(+), 2 deletions(-) create mode 100755 Documentation/insert_man_font_commands.pl
Documentation/Makefile +3 -0
@@ -121,6 +121,9 @@ clean: %.1 %.5 %.7 : %.xml xmlto -m callouts.xsl man $< + mv $@ [email protected] + ./insert_man_font_commands.pl < [email protected] > $@ + $(RM) [email protected] %.xml : %.txt $(RM) $@+ $@
Documentation/asciidoc.conf +2 -2
@@ -28,11 +28,11 @@ ifdef::backend-docbook[] <example><title>{title}</title> <literallayout> ifdef::doctype-manpage[] - .ft C + #GIT#SET#MAN#FONT# C endif::doctype-manpage[] | ifdef::doctype-manpage[] - .ft + #GIT#SET#MAN#FONT# endif::doctype-manpage[] </literallayout> {title#}</example>
Documentation/insert_man_font_commands.pl new file +6 -0
@@ -0,0 +1,6 @@ +#!/usr/bin/perl -w + +while ($line = <>) { + $line =~ s/^#GIT#SET#MAN#FONT#/.ft/; + print $line; +}
Signature · 1 line
1.5.2.2
Re: [PATCH] Update listingblock monospace fix to support all docbook versions
Documentation/insert_man_font_commands.pl line 6
Quoted 4 lines · Julian Phillips
Documentation/insert_man_font_commands.pl new file +4
-0+while ($line = <>) { + $line =~ s/^#GIT#SET#MAN#FONT#/.ft/; + print $line; +}
Why not use perl -pe "s/^#GIT#SET#MAN#FONT#/.ft/" or an equivalent sed command in the Makefile instead of having this as a separate script?
~~ Brian
Re: [PATCH] Update listingblock monospace fix to support all docbook versions
Quoted 9 lines · Brian Gernhardt
Documentation/insert_man_font_commands.pl line 6
Quoted 4 lines · Julian Phillips
Documentation/insert_man_font_commands.pl new file +4
-0+while ($line = <>) { + $line =~ s/^#GIT#SET#MAN#FONT#/.ft/; + print $line; +}Why not use
perl -pe "s/^#GIT#SET#MAN#FONT#/.ft/"or an equivalent sed command in theMakefileinstead of having this as a separate script?
Only because my perl foo is too weak to know the perl form, and I didn't know how to get sed to replace unicode characters - which the original version of the script did. I rewrote the script in my lunchbreak after I failed to find any better way to solve the problem, and it didn't occur to me to move it to sed at that point.
However, given the other issues with docbook xsl 1.72 I think it would cleaner to simply say that git doesn't support 1.72. I wouldn't be surprised if other projects weren't taking that approach.
Signature · 5 lines
Julian --- It's computer hardware, of course it's worth having <g> -- Espy on #Debian
Re: [PATCH] Update listingblock monospace fix to support all docbook versions
In reply to Julian PhillipsQuoted 4 lines · Julian Phillips
So this uses the string '#GIT#SET#MAN#FONT#', and then changes that to .ft using a post-process perl script.
Not pretty, but it works.
Owwwww... pain.
Unless anybody else has better fix I'd say we go with this.
Thanks.
PATCH 1/1 Force listingblocks to be monospaced in manpages
In reply to Julian PhillipsFor 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.
---
Julian Phillips <[email protected]> wrote Thu, Jul 19, 2007:
Quoted 9 lines · Junio C Hamano
Quoted 5 lines
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.
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.
Documentation/callouts.xsl +89 -0
@@ -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> </xsl:text> + <xsl:text>.sp </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> </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> </xsl:text> + <xsl:text>.nf </xsl:text> + <xsl:apply-templates/> + <xsl:text> </xsl:text> + <xsl:text>.fi </xsl:text> + <xsl:text>.ft </xsl:text> + </xsl:when> + <xsl:otherwise> + <!-- * Other verbatims do not need to get bolded --> + <xsl:text>.nf </xsl:text> + <xsl:text>.ft C </xsl:text> + <xsl:apply-templates/> + <xsl:text> </xsl:text> + <xsl:text>.ft </xsl:text> + <xsl:text> </xsl:text> + <xsl:text> .fi </xsl:text> + </xsl:otherwise> + </xsl:choose> + <xsl:if test="$indent = 'Yes'"> + <!-- * end indented section --> + <xsl:text>.RE </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 </xsl:text> + </xsl:if> +</xsl:template> + </xsl:stylesheet>
Signature · 1 line
Jonas Fonseca
Re: [PATCH] Force listingblocks to be monospaced in manpages
Quoted 18 lines · Jonas Fonseca
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 <[email protected]>---
Julian Phillips <[email protected]> wrote Thu, Jul 19, 2007:
Quoted 7 lines · Junio C Hamano
Quoted 5 lines
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):
Quoted 6 lines
Quoted 2 lines
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 ...
Signature · 5 lines
Julian --- "It's when they say 2 + 2 = 5 that I begin to argue." -- Eric Pepke
Re: [PATCH] Force listingblocks to be monospaced in manpages
Julian Phillips <[email protected]> wrote Thu, Jul 19, 2007:
Quoted 8 lines · Jonas Fonseca
Quoted 3 lines
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.
Quoted 3 lines
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.
Signature · 1 line
Jonas Fonseca