quote in help code example

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.

On Mon, Oct 12, 2009 at 06:29:26PM +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'.

On Mon, 12 Oct 2009, Miklos Vajna wrote:

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

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

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.

On Tue, 13 Oct 2009, Miklos Vajna 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?
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´

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

In general, it's always a good idea, though I don't think it's necessary for the second time.

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.

Miklos Vajna wrote:

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.

Thomas Rast wrote:

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.

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

On Wed, Oct 21, 2009 at 10:24:42AM +0200, Thomas Rast <trast@student.ethz.ch> wrote:

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

- asciidoc 8.3.5, docbook-xsl 1.74.0, xmlto 0.0.20

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

Anders

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:

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

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:

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

Miklos Vajna <vmiklos@frugalware.org> writes:

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"?

On Wed, 21 Oct 2009, Junio C Hamano wrote:

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

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:

I'll take your word for it, but I cannot test with anything non-GNU.

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

On Wed, 21 Oct 2009, Thomas Rast wrote:

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.

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

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

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