Skip to contentSkip to conversation

quote in help code example

PATCH In review bill lam 5 participants 18 messages Jun 15, 2016

Subsystems (2)
lore
Share & tools
lore

bill lam

author
#0 lore raw

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
#1 lore raw
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
   .ft

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'.

author
#2 lore raw
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
#3 lore raw
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.

author
#4 lore raw
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
#5 lore raw
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-info

1. did I need to set ASCIIDOC_NO_ROFF in 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.

#6 lore raw
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 &apos; 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
index a264fa6..7c14469 100644
@@ -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.ch
#7 lore raw
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.ch
#8 lore raw

PATCH 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
index a264fa6..bf74bb7 100644
@@ -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
Tested-by on v1 1/1
#9 lore raw

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_char manpage.

Quoted 8 lines

---

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

#10 lore raw

Re: [PATCH] Quote ' as \(aq in manpages

In reply to Thomas Rast
Quoted 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_char manpage.

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

#11 lore raw

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
index 06b0c57..68876d0 100644
@@ -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
new file mode 100644
index 0000000..aeb8839
@@ -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
#12 lore raw

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 Makefile variable GNU_ROFF which 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
index fea237b..40da590 100644
@@ -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
#13 lore raw

Re: [PATCH] Document GNU_ROFF in Makefile

Quoted 19 lines · Miklos Vajna

---

Quoted 3 lines · Thomas Rast

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.

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
index fea237b..40da590 100644

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
#14 lore raw

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

#15 lore raw

PATCH v3 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.

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
index 06b0c57..cd5b439 100644
@@ -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
new file mode 100644
index 0000000..aeb8839
@@ -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
index fea237b..2ccbe4a 100644
@@ -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
#16 lore raw

Re: [PATCH v2] Quote ' as \(aq in manpages

In reply to Thomas Rast
Quoted 3 lines · Thomas Rast

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.

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

#17 lore raw
In reply to bill lam
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
   .ft

Is 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).