quote in help code example

quote in help code example

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

-- 
regards,
====================================================
GPG key 1024D/4434BAB3 2008-08-24
gpg --keyserver subkeys.pgp.net --recv-keys 4434BAB3

Re: quote in help code example

[Miklos Vajna]

[-- Attachment #1: Type: text/plain, Size: 579 bytes --]

On Mon, Oct 12, 2009 at 06:29:26PM +0800, bill lam <cbill.lam@gmail.com> wrote:
> 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'.

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: quote in help code example

[Junio C Hamano]

bill lam <cbill.lam@gmail.com> writes:

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

Re: quote in help code example

[bill lam]

On Mon, 12 Oct 2009, Miklos Vajna wrote:
> On Mon, Oct 12, 2009 at 06:29:26PM +0800, bill lam <cbill.lam@gmail.com> wrote:
> > 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'.

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

-- 
regards,
====================================================
GPG key 1024D/4434BAB3 2008-08-24
gpg --keyserver subkeys.pgp.net --recv-keys 4434BAB3

Re: quote in help code example

[Miklos Vajna]

[-- Attachment #1: Type: text/plain, Size: 892 bytes --]

On Tue, Oct 13, 2009 at 10:16:17AM +0800, bill lam <cbill.lam@gmail.com> wrote:
> > 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

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.

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: quote in help code example

[bill lam]

On Tue, 13 Oct 2009, Miklos Vajna wrote:
> On Tue, Oct 13, 2009 at 10:16:17AM +0800, bill lam <cbill.lam@gmail.com> wrote:
> > > 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
> 
> 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´

-- 
regards,
====================================================
GPG key 1024D/4434BAB3 2008-08-24
gpg --keyserver subkeys.pgp.net --recv-keys 4434BAB3

Re: quote in help code example

[Miklos Vajna]

[-- Attachment #1: Type: text/plain, Size: 759 bytes --]

On Tue, Oct 13, 2009 at 10:06:23PM +0800, bill lam <cbill.lam@gmail.com> wrote:
> 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.

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

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: quote in help code example

[Thomas Rast]

[-- Attachment #1: Type: Text/Plain, Size: 2721 bytes --]

Miklos Vajna wrote:
> On Tue, Oct 13, 2009 at 10:06:23PM +0800, bill lam <cbill.lam@gmail.com> wrote:
> > 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.

diff --git i/Documentation/manpage-base.xsl w/Documentation/manpage-base.xsl
index a264fa6..7c14469 100644
--- i/Documentation/manpage-base.xsl
+++ w/Documentation/manpage-base.xsl
@@ -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 -->

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 197 bytes --]

Re: quote in help code example

[Thomas Rast]

Thomas Rast wrote:
> 
> 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.

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

[PATCH] Quote ' as \(aq in manpages

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

Signed-off-by: Thomas Rast <trast@student.ethz.ch>
---

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

diff --git a/Documentation/manpage-base.xsl b/Documentation/manpage-base.xsl
index a264fa6..bf74bb7 100644
--- a/Documentation/manpage-base.xsl
+++ b/Documentation/manpage-base.xsl
@@ -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 -->
-- 
1.6.5.1.144.g40216

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

[Miklos Vajna]

[-- Attachment #1: Type: text/plain, Size: 872 bytes --]

On Wed, Oct 21, 2009 at 10:24:42AM +0200, Thomas Rast <trast@student.ethz.ch> wrote:
> 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.
> 
> Signed-off-by: Thomas Rast <trast@student.ethz.ch>
> ---
> 
> 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

Tested-by: Miklos Vajna <vmiklos@frugalware.org>

- asciidoc 8.3.5, docbook-xsl 1.74.0, xmlto 0.0.20

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

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

[Anders Kaseorg]

On Wed, 21 Oct 2009, Thomas Rast wrote:
> 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

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

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

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.

Signed-off-by: Thomas Rast <trast@student.ethz.ch>
---

[Reinstated the Cc list, which I accidentally dropped when sending the
first patch...]

Anders Kaseorg wrote:
> \(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

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 06b0c57..68876d0 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -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;
diff --git a/Documentation/manpage-quote-apos.xsl b/Documentation/manpage-quote-apos.xsl
new file mode 100644
index 0000000..aeb8839
--- /dev/null
+++ b/Documentation/manpage-quote-apos.xsl
@@ -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>
-- 
1.6.5.1.144.g316236

[PATCH] Document GNU_ROFF in Makefile

[Miklos Vajna]

Signed-off-by: Miklos Vajna <vmiklos@frugalware.org>
---

On Wed, Oct 21, 2009 at 08:57:27PM +0200, Thomas Rast <trast@student.ethz.ch> wrote:
> 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(-)

diff --git a/Makefile b/Makefile
index fea237b..40da590 100644
--- a/Makefile
+++ b/Makefile
@@ -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).
 #
-- 
1.6.5

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

[Anders Kaseorg]

On Wed, 21 Oct 2009, Thomas Rast wrote:
> 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.

> 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

Re: [PATCH] Document GNU_ROFF in Makefile

[Junio C Hamano]

Miklos Vajna <vmiklos@frugalware.org> writes:

> Signed-off-by: Miklos Vajna <vmiklos@frugalware.org>
> ---
>
> On Wed, Oct 21, 2009 at 08:57:27PM +0200, Thomas Rast <trast@student.ethz.ch> wrote:
>> 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(-)
>
> diff --git a/Makefile b/Makefile
> index fea237b..40da590 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -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"?

>  # Define NO_PERL_MAKEMAKER if you cannot use Makefiles generated by perl's
>  # MakeMaker (e.g. using ActiveState under Cygwin).
>  #
> -- 
> 1.6.5

Re: [PATCH] Document GNU_ROFF in Makefile

[Anders Kaseorg]

On Wed, 21 Oct 2009, Junio C Hamano wrote:
> > +# 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

[PATCH v3] Quote ' as \(aq in manpages

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

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.

Signed-off-by: Thomas Rast <trast@student.ethz.ch>
---

Anders Kaseorg wrote:
> On Wed, 21 Oct 2009, Junio C Hamano wrote:
> > > +# 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.

> 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

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 06b0c57..cd5b439 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -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))
diff --git a/Documentation/manpage-quote-apos.xsl b/Documentation/manpage-quote-apos.xsl
new file mode 100644
index 0000000..aeb8839
--- /dev/null
+++ b/Documentation/manpage-quote-apos.xsl
@@ -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>
diff --git a/Makefile b/Makefile
index fea237b..2ccbe4a 100644
--- a/Makefile
+++ b/Makefile
@@ -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).
 #
-- 
1.6.5.1.144.g316236