quote in help code example
Subsystems (2)
In git man, eg. git help filter-branch
The code examples for command line or shell scripts inside .ft pairs use (smart?) quote instead of single quotes, like
.ft C git filter-branch --tree-filter ´rm filename´ HEAD .ft
Is this intentional or just some configuration problem during compiling.
Signature · 4 lines
regards, ==================================================== GPG key 1024D/4434BAB3 2008-08-24 gpg --keyserver subkeys.pgp.net --recv-keys 4434BAB3
Quoted 10 lines · bill lam
In git man, eg. git help filter-branch
The code examples for command line or shell scripts inside .ft pairs use (smart?) quote instead of single quotes, like.ft C git filter-branch --tree-filter ´rm filename´ HEAD .ftIs this intentional or just some configuration problem during compiling.
Just a guess: do you have docbook-xsl >=1.73.0 and you did not set ASCIIDOC_NO_ROFF?
Try rebuilding the documentation using 'make ASCIIDOC_NO_ROFF=YesPlease'.
Quoted 9 lines · Miklos Vajna
Quoted 8 lines · bill lam
In git man, eg. git help filter-branch
The code examples for command line or shell scripts inside .ft pairs use (smart?) quote instead of single quotes, like.ft C git filter-branch --tree-filter ´rm filename´ HEAD .ft
Quoted 7 lines
Quoted 2 lines
Is this intentional or just some configuration problem during compiling.
Just a guess: do you have docbook-xsl >=1.73.0 and you did not set
ASCIIDOC_NO_ROFF?Try rebuilding the documentation using 'make ASCIIDOC_NO_ROFF=YesPlease'.
I'm not familiar with how to twist git makefile. By adding a line to ./Makefile
# Platform specific tweaks
#
# We choose to avoid "if .. else if .. else .. endif endif"
# because maintaining the nesting to match is a pain. If # we had "elif" things would have been much nicer...
ASCIIDOC_NO_ROFF = YesPlease # <--- this line added
ifeq ($(uname_S),Linux)
However, the man page still display the same
.ft C git filter-branch --tree-filter ´rm filename´ HEAD .ft
I use debian lenny 64bit with
Package: docbook-xsl
Version: 1.73.2.dfsg.1-5
Package: asciidoc
Version: 8.2.7-3~lenny1
Signature · 4 lines
regards, ==================================================== GPG key 1024D/4434BAB3 2008-08-24 gpg --keyserver subkeys.pgp.net --recv-keys 4434BAB3
Quoted 10 lines · bill lam
Quoted 4 lines
Just a guess: do you have docbook-xsl >=1.73.0 and you did not set
ASCIIDOC_NO_ROFF?Try rebuilding the documentation using 'make ASCIIDOC_NO_ROFF=YesPlease'.
I'm not familiar with how to twist git makefile. By adding a line to ./Makefile
# Platform specific tweaks
#
Quoted 8 lines
# We choose to avoid "if .. else if .. else .. endif endif"
# because maintaining the nesting to match is a pain. If # we had "elif" things would have been much nicer...
ASCIIDOC_NO_ROFF= YesPlease # <--- this line added
ifeq ($(uname_S),Linux)However, the man page still display the same
Don't edit the Makefile, just use the command 'make ASCIIDOC_NO_ROFF=YesPlease'. Also make sure to do a 'make clean' in the Documentation dir to get the manpages rebuilt.
Quoted 15 lines · Miklos Vajna
Quoted 14 lines · bill lam
Quoted 4 lines
Just a guess: do you have docbook-xsl >=1.73.0 and you did not set
ASCIIDOC_NO_ROFF?Try rebuilding the documentation using 'make ASCIIDOC_NO_ROFF=YesPlease'.
I'm not familiar with how to twist git makefile. By adding a line to ./Makefile
# Platform specific tweaks
## We choose to avoid "if .. else if .. else .. endif endif"
# because maintaining the nesting to match is a pain. If # we had "elif" things would have been much nicer...
Quoted 8 lines
Quoted 4 lines
ASCIIDOC_NO_ROFF= YesPlease # <--- this line added
ifeq ($(uname_S),Linux)However, the man page still display the same
Don't edit the
Makefile, just use the command 'make ASCIIDOC_NO_ROFF=YesPlease'. Also make sure to do a 'make clean' in the Documentation dir to get the manpages rebuilt.
I run these commands
make ASCIIDOC_NO_ROFF=YesPlease prefix=/usr all doc info
sudo make ASCIIDOC_NO_ROFF=YesPlease prefix=/usr install install-doc install-html install-info
1. did I need to set ASCIIDOC_NO_ROFF in both lines?
2. now the .ft pair fixed but it still displayed incorrect quote.
git filter-branch --tree-filter ´rm filename´ HEAD
it should be 'rm filename' not ´rm filename´
Signature · 4 lines
regards, ==================================================== GPG key 1024D/4434BAB3 2008-08-24 gpg --keyserver subkeys.pgp.net --recv-keys 4434BAB3
Quoted 6 lines · bill lam
I run these commands
make ASCIIDOC_NO_ROFF=YesPlease prefix=/usr all doc info
sudo make ASCIIDOC_NO_ROFF=YesPlease prefix=/usr install install-doc install-html install-info1. did I need to set
ASCIIDOC_NO_ROFFin both lines?
In general, it's always a good idea, though I don't think it's necessary for the second time.
Quoted 5 lines
2. now the .ft pair fixed but it still displayed incorrect quote.
git filter-branch --tree-filter ´rm filename´ HEAD
it should be 'rm filename' not ´rm filename´
I can reproduce that here as well, that's how it is in the official manpages as well (see the man branch), so that's not specific to your system.
Quoted 10 lines · Miklos Vajna
Quoted 5 lines · bill lam
2. now the .ft pair fixed but it still displayed incorrect quote.
git filter-branch --tree-filter ´rm filename´ HEAD
it should be 'rm filename' not ´rm filename´
I can reproduce that here as well, that's how it is in the official manpages as well (see the man branch), so that's not specific to your system.
Same here. The patch below is a band-aid fix that works for me, but I'd rather have it tested on various docbook/asciidoc combinations if anyone still runs them.
My findings so far were that asciidoc correctly turns the apostrophe into an ' entity in the .xml output, and xmlto then turns it into \' instead of just ' in the troff output. Then, if the terminal appears to support Unicode (this can be disabled with LC_ALL=C or such) the formatter turns it into a "real" apostrophe that, of course, is not understood by any ASCII-based tool.
So far so good, and sounded like an easy debugging job, right? Not so. The buzzword-compliance people apparently felt it would be nice to wrap a bad joke of a language in the bad joke of a language that XML already is, and thus was XSL invented. Deep in the horrors of these XSL files, in my case in
/usr/share/xml/docbook/stylesheet/nwalsh/1.75.2/manpages/other.xsl
there's a template that, according to the comment near it, maltreats our apostrophes:
* The backslash, dot, dash, and apostrophe (\, ., -, ') characters
* have special meaning for roff, so before we do any other
* processing, we must escape those characters where they appear in
* the source content.
The patch below just replaces said template with a no-op for git's manpage creation. I have not been able to substantiate the claim that apostrophes are special, and in fact with the patch my manpages look fine. Then again I don't know anything about roff syntax either, and manuals seem a bit hard to come by.
Grrr.
Documentation/manpage-base.xsl +5 -0
@@ -7,6 +7,11 @@ <xsl:param name="man.output.quietly" select="1"/> <xsl:param name="refentry.meta.get.quietly" select="1"/> +<xsl:template name="escape.apostrophe"> + <xsl:param name="content"/> + <xsl:value-of select="$content"/> +</xsl:template> + <!-- convert asciidoc callouts to man page format; git.docbook.backslash and git.docbook.dot params must be supplied by another XSL file or other means -->
Signature · 2 lines
Thomas Rast
trast@{inf,student}.ethz.chQuoted 10 lines · bill lam
In git man, eg. git help filter-branch
The code examples for command line or shell scripts inside .ft pairs use (smart?) quote instead of single quotes, like.ft C git filter-branch --tree-filter ´rm filename´ HEAD .ftIs this intentional or just some configuration problem during compiling.
I see these in Documentation/Makefile:
#
# For asciidoc ...
# -7.1.2, no extra settings are needed.
# 8.0-, set ASCIIDOC8.
#
#
# For docbook-xsl ...
# -1.68.1, set ASCIIDOC_NO_ROFF? (based on changelog from 1.73.0)
# 1.69.0, no extra settings are needed?
# 1.69.1-1.71.0, set DOCBOOK_SUPPRESS_SP?
# 1.71.1, no extra settings are needed?
# 1.72.0, set DOCBOOK_XSL_172.
# 1.73.0-, set ASCIIDOC_NO_ROFF
#
#
# If you had been using DOCBOOK_XSL_172 in an attempt to get rid
# of 'the ".ft C" problem' in your generated manpages, and you # instead ended up with weird characters around callouts, try # using ASCIIDOC_NO_ROFF instead (it works fine with ASCIIDOC8).
Quoted 6 lines · Thomas Rast
The patch below just replaces said template with a no-op for git's manpage creation. I have not been able to substantiate the claim that apostrophes are special, and in fact with the patch my manpages look fine. Then again I don't know anything about roff syntax either, and manuals seem a bit hard to come by.
Actually, scratch the patch. I haven't been able to nail it yet, and I'm not sure I have the energy for another stab at this mess; but during testing with older versions, I learned that they behave differently and the patch just shifts the breakage a bit.
Also, the single quotes are apparently special at the beginning of a line and to delimit function arguments, though not elsewhere. The bash manpage uses \(aq to get a literal apostrophe, which I will aim to convert them to. Oddly enough, the groff(7) manpage does not document \(aq, but lists \(cq as the official escape for ' ... which then turns out to mutate into this cursed non-apostrophe again. Sigh.
Signature · 2 lines
Thomas Rast
trast@{inf,student}.ethz.chPATCH 1/1 Quote ' as \(aq in manpages
The docbook/xmlto toolchain insists on quoting ' as \'. This does achieve the quoting goal, but modern 'man' implementations turn the apostrophe into a unicode "proper" apostrophe (given the right circumstances), breaking code examples in many of our manpages.
Quote them as \(aq instead, which is an "apostrophe quote" as per the groff_char manpage.
---
I've had this around since my last rant, and it actually gives good results with both setups I can test on, which are:
- asciidoc 8.4.5, docbook-xsl 1.75.2, xmlto 0.0.18
- asciidoc 8.2.7, docbook-xsl 1.73.2, xmlto 0.0.20
Documentation/manpage-base.xsl | 9 +++++++++ 1 files changed, 9 insertions(+), 0 deletions(-)
Documentation/manpage-base.xsl +9 -0
@@ -7,6 +7,15 @@ <xsl:param name="man.output.quietly" select="1"/> <xsl:param name="refentry.meta.get.quietly" select="1"/> +<xsl:template name="escape.apostrophe"> + <xsl:param name="content"/> + <xsl:call-template name="string.subst"> + <xsl:with-param name="string" select="$content"/> + <xsl:with-param name="target">'</xsl:with-param> + <xsl:with-param name="replacement">\(aq</xsl:with-param> + </xsl:call-template> +</xsl:template> + <!-- convert asciidoc callouts to man page format; git.docbook.backslash and git.docbook.dot params must be supplied by another XSL file or other means -->
Signature · 1 line
1.6.5.1.144.g40216
Re: [PATCH] Quote ' as \(aq in manpages
Quoted 8 lines · Thomas Rast
The docbook/xmlto toolchain insists on quoting ' as \'. This does achieve the quoting goal, but modern 'man' implementations turn the apostrophe into a unicode "proper" apostrophe (given the right circumstances), breaking code examples in many of our manpages.
Quote them as \(aq instead, which is an "apostrophe quote" as per the
groff_charmanpage.
Quoted 8 lines
Signed-off-by Thomas Rast <[email protected]>---
I've had this around since my last rant, and it actually gives good results with both setups I can test on, which are:
- asciidoc 8.4.5, docbook-xsl 1.75.2, xmlto 0.0.18
- asciidoc 8.2.7, docbook-xsl 1.73.2, xmlto 0.0.20
- asciidoc 8.3.5, docbook-xsl 1.74.0, xmlto 0.0.20
Re: [PATCH] Quote ' as \(aq in manpages
In reply to Thomas RastQuoted 7 lines · Thomas Rast
The docbook/xmlto toolchain insists on quoting ' as \'. This does achieve the quoting goal, but modern 'man' implementations turn the apostrophe into a unicode "proper" apostrophe (given the right circumstances), breaking code examples in many of our manpages.
Quote them as \(aq instead, which is an "apostrophe quote" as per the
groff_charmanpage.
\(aq is not portable to non-GNU roff. See
http://bugs.debian.org/507673#65
http://sourceforge.net/tracker/index.php?func=detail&aid=2412738&group_id=21935&atid=373747
for a proposed portable solution.
Anders
PATCH v2 1/1 Quote ' as \(aq in manpages
The docbook/xmlto toolchain insists on quoting ' as \'. This does achieve the quoting goal, but modern 'man' implementations turn the apostrophe into a unicode "proper" apostrophe (given the right circumstances), breaking code examples in many of our manpages.
Quote them as \(aq instead, which is an "apostrophe quote" as per the groff_char manpage.
Unfortunately, as Anders Kaseorg kindly pointed out, this is not portable beyond groff, so we add an extra Makefile variable GNU_ROFF which you need to enable to get the new quoting.
---
[Reinstated the Cc list, which I accidentally dropped when sending the first patch...]
Quoted 4 lines · Anders Kaseorg
\(aq is not portable to non-GNU roff. See
http://bugs.debian.org/507673#65
http://sourceforge.net/tracker/index.php?func=detail&aid=2412738&group_id=21935&atid=373747
for a proposed portable solution.
Thanks for pointing that out. Makes things a lot easier though. I'm really beginning to enjoy the whole doc toolchain.
I could not find a way to insert the proposed definitions into the header by tweaking the xsls, so unless someone comes up with a way of doing that, this is the best I can do.
To save you the effort of clicking the links, the header definitions would be
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
and you then have to change the template to quote to \(Aq instead.
Documentation/Makefile | 3 +++ Documentation/manpage-quote-apos.xsl | 16 ++++++++++++++++ 2 files changed, 19 insertions(+), 0 deletions(-) create mode 100644 Documentation/manpage-quote-apos.xsl
Documentation/Makefile +3 -0
@@ -102,6 +102,9 @@ endif ifdef DOCBOOK_SUPPRESS_SP XMLTO_EXTRA += -m manpage-suppress-sp.xsl endif +ifdef GNU_ROFF +XMLTO_EXTRA += -m manpage-quote-apos.xsl +endif SHELL_PATH ?= $(SHELL) # Shell quote;
Documentation/manpage-quote-apos.xsl new file +16 -0
@@ -0,0 +1,16 @@ +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<!-- work around newer groff/man setups using a prettier apostrophe + that unfortunately does not quote anything when cut&pasting + examples to the shell --> +<xsl:template name="escape.apostrophe"> + <xsl:param name="content"/> + <xsl:call-template name="string.subst"> + <xsl:with-param name="string" select="$content"/> + <xsl:with-param name="target">'</xsl:with-param> + <xsl:with-param name="replacement">\(aq</xsl:with-param> + </xsl:call-template> +</xsl:template> + +</xsl:stylesheet>
Signature · 1 line
1.6.5.1.144.g316236
PATCH 1/1 Document GNU_ROFF in Makefile
---
Quoted 3 lines · Thomas Rast
Unfortunately, as Anders Kaseorg kindly pointed out, this is not portable beyond groff, so we add an extra
MakefilevariableGNU_ROFFwhich you need to enable to get the new quoting.
You forgot to document this in Makefile. Maybe this could be just squashed in, Junio will decide.
Makefile | 3 +++ 1 files changed, 3 insertions(+), 0 deletions(-)
Makefile +3 -0
@@ -159,6 +159,9 @@ all:: # Define ASCIIDOC_NO_ROFF if your DocBook XSL escapes raw roff directives # (versions 1.72 and later and 1.68.1 and earlier). # +# Define GNU_ROFF if you have GNU roff and you don't want to have pretty +# apostrophe so that cut&pasting examples to the shell will work. +# # Define NO_PERL_MAKEMAKER if you cannot use Makefiles generated by perl's # MakeMaker (e.g. using ActiveState under Cygwin). #
Signature · 1 line
1.6.5
Re: [PATCH] Document GNU_ROFF in Makefile
Quoted 19 lines · Miklos Vajna
Signed-off-by Miklos Vajna <[email protected]>---
Quoted 3 lines · Thomas Rast
Unfortunately, as Anders Kaseorg kindly pointed out, this is not portable beyond groff, so we add an extra
MakefilevariableGNU_ROFFwhich you need to enable to get the new quoting.You forgot to document this in
Makefile. Maybe this could be just squashed in, Junio will decide.Makefile | 3 +++ 1 files changed, 3 insertions(+), 0 deletions(-)Makefile +0
-0
Makefile all:: · line 164
Quoted 6 lines
Makefile +3
-0@@ -159,6 +159,9 @@ all:: # Define ASCIIDOC_NO_ROFF if your DocBook XSL escapes raw roff directives # (versions 1.72 and later and 1.68.1 and earlier). # +# Define GNU_ROFF if you have GNU roff and you don't want to have pretty +# apostrophe so that cut&pasting examples to the shell will work. +#
This makes it sound as if groff is the only roff implementation that has this problem---iow, if we use non-GNU roff then the documentation comes out just fine. Is that the case?
Or is the situation more like "we know how to fix this for groff, and the fix is enabled if this variable is defined---on other roff implementations the output is still broken"?
Quoted 5 lines
Makefile +0
-0# Define NO_PERL_MAKEMAKER if you cannot use Makefiles generated by perl's # MakeMaker (e.g. using ActiveState under Cygwin). #Signature · 1 line
1.6.5
Re: [PATCH] Document GNU_ROFF in Makefile
Quoted 6 lines · Junio C Hamano
Makefile all:: · line 163
Quoted 2 lines
Makefile +2
-0+# Define GNU_ROFF if you have GNU roff and you don't want to have pretty +# apostrophe so that cut&pasting examples to the shell will work.This makes it sound as if groff is the only roff implementation that has this problem---iow, if we use non-GNU roff then the documentation comes out just fine. Is that the case?
Yes:
built without GNU_ROFF built with GNU_ROFF
viewed with non-GNU roff correct (') wrong (no output!)
viewed with GNU groff wrong (´) correct (')
In order to build a manpage that can be viewed correctly on both platforms, the conditional logic should live in the manpage itself (as per the bug comments I linked to and Thomas quoted from).
Anders
Re: [PATCH v2] Quote ' as \(aq in manpages
In reply to Thomas RastQuoted 3 lines · Thomas Rast
Unfortunately, as Anders Kaseorg kindly pointed out, this is not portable beyond groff, so we add an extra
MakefilevariableGNU_ROFFwhich you need to enable to get the new quoting.
Note that GNU_ROFF is a property of the target system on which the manpages will be read, unlike the existing variables (ASCIIDOC8, DOCBOOK_XSL_172, ASCIIDOC_NO_ROFF) which are properties of the host system on which they are built.
Quoted 7 lines
To save you the effort of clicking the links, the header definitions would be
.ie \n(.g .ds Aq \(aq
.el .ds Aq 'and you then have to change the template to quote to \(Aq instead.
If someone knows how to get this definition into the header, that would be preferable, because then you could read the same manpage on both GNU and non-GNU systems instead of building separately for each.
It would be even better if someone would work with the Docbook developers to get this fixed upstream. (Unfortunately, there has been no reply to my comment in their bug tracker.)
Anders
PATCH v3 1/1 Quote ' as \(aq in manpages
In reply to Anders KaseorgThe docbook/xmlto toolchain insists on quoting ' as \'. This does achieve the quoting goal, but modern 'man' implementations turn the apostrophe into a unicode "proper" apostrophe (given the right circumstances), breaking code examples in many of our manpages.
Quote them as \(aq instead, which is an "apostrophe quote" as per the groff_char manpage.
Unfortunately, as Anders Kaseorg kindly pointed out, this is not portable beyond groff, so we add an extra Makefile variable GNU_ROFF which you need to enable to get the new quoting.
Thanks also to Miklos Vajna for documentation.
---
Quoted 9 lines · Anders Kaseorg
Quoted 6 lines · Junio C Hamano
Review
Quoted 2 lines
(quoted diff) +2
-0+# Define GNU_ROFF if you have GNU roff and you don't want to have pretty +# apostrophe so that cut&pasting examples to the shell will work.This makes it sound as if groff is the only roff implementation that has this problem---iow, if we use non-GNU roff then the documentation comes out just fine. Is that the case?
Yes:
I'll take your word for it, but I cannot test with anything non-GNU.
Quoted 3 lines
In order to build a manpage that can be viewed correctly on both platforms, the conditional logic should live in the manpage itself (as per the bug comments I linked to and Thomas quoted from).
I reworded Miklos' doc patch a bit to indicate that it's about the target system, and also added a slightly longer comment to the Documentation/Makefile for completeness.
Documentation/Makefile | 8 ++++++++ Documentation/manpage-quote-apos.xsl | 16 ++++++++++++++++ Makefile | 4 ++++ 3 files changed, 28 insertions(+), 0 deletions(-) create mode 100644 Documentation/manpage-quote-apos.xsl
Documentation/Makefile +8 -0
@@ -103,6 +103,14 @@ ifdef DOCBOOK_SUPPRESS_SP XMLTO_EXTRA += -m manpage-suppress-sp.xsl endif +# If your target system uses GNU groff, it may try to render +# apostrophes as a "pretty" apostrophe using unicode. This breaks +# cut&paste, so you should set GNU_ROFF to force them to be ASCII +# apostrophes. Unfortunately does not work with non-GNU roff. +ifdef GNU_ROFF +XMLTO_EXTRA += -m manpage-quote-apos.xsl +endif + SHELL_PATH ?= $(SHELL) # Shell quote; SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH))
Documentation/manpage-quote-apos.xsl new file +16 -0
@@ -0,0 +1,16 @@ +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<!-- work around newer groff/man setups using a prettier apostrophe + that unfortunately does not quote anything when cut&pasting + examples to the shell --> +<xsl:template name="escape.apostrophe"> + <xsl:param name="content"/> + <xsl:call-template name="string.subst"> + <xsl:with-param name="string" select="$content"/> + <xsl:with-param name="target">'</xsl:with-param> + <xsl:with-param name="replacement">\(aq</xsl:with-param> + </xsl:call-template> +</xsl:template> + +</xsl:stylesheet>
Makefile +4 -0
@@ -159,6 +159,10 @@ all:: # Define ASCIIDOC_NO_ROFF if your DocBook XSL escapes raw roff directives # (versions 1.72 and later and 1.68.1 and earlier). # +# Define GNU_ROFF if your target system uses GNU groff. This forces +# apostrophes to be ASCII so that cut&pasting examples to the shell +# will work. +# # Define NO_PERL_MAKEMAKER if you cannot use Makefiles generated by perl's # MakeMaker (e.g. using ActiveState under Cygwin). #
Signature · 1 line
1.6.5.1.144.g316236