* quote in help code example @ 2009-10-12 10:29 bill lam 2009-10-12 19:40 ` Miklos Vajna 2009-10-12 21:06 ` quote in help code example Junio C Hamano 0 siblings, 2 replies; 18+ messages in thread From: bill lam @ 2009-10-12 10:29 UTC (permalink / raw) To: git 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 ^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: quote in help code example 2009-10-12 10:29 quote in help code example bill lam @ 2009-10-12 19:40 ` Miklos Vajna 2009-10-13 2:16 ` bill lam 2009-10-12 21:06 ` quote in help code example Junio C Hamano 1 sibling, 1 reply; 18+ messages in thread From: Miklos Vajna @ 2009-10-12 19:40 UTC (permalink / raw) To: bill lam; +Cc: git [-- 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 --] ^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: quote in help code example 2009-10-12 19:40 ` Miklos Vajna @ 2009-10-13 2:16 ` bill lam 2009-10-13 10:19 ` Miklos Vajna 0 siblings, 1 reply; 18+ messages in thread From: bill lam @ 2009-10-13 2:16 UTC (permalink / raw) To: Miklos Vajna; +Cc: git 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 ^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: quote in help code example 2009-10-13 2:16 ` bill lam @ 2009-10-13 10:19 ` Miklos Vajna 2009-10-13 14:06 ` bill lam 0 siblings, 1 reply; 18+ messages in thread From: Miklos Vajna @ 2009-10-13 10:19 UTC (permalink / raw) To: bill lam; +Cc: git [-- 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 --] ^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: quote in help code example 2009-10-13 10:19 ` Miklos Vajna @ 2009-10-13 14:06 ` bill lam 2009-10-13 15:30 ` Miklos Vajna 0 siblings, 1 reply; 18+ messages in thread From: bill lam @ 2009-10-13 14:06 UTC (permalink / raw) To: Miklos Vajna; +Cc: git 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 ^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: quote in help code example 2009-10-13 14:06 ` bill lam @ 2009-10-13 15:30 ` Miklos Vajna 2009-10-13 20:15 ` Thomas Rast 0 siblings, 1 reply; 18+ messages in thread From: Miklos Vajna @ 2009-10-13 15:30 UTC (permalink / raw) To: bill lam; +Cc: git [-- 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 --] ^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: quote in help code example 2009-10-13 15:30 ` Miklos Vajna @ 2009-10-13 20:15 ` Thomas Rast 2009-10-15 12:02 ` Thomas Rast 0 siblings, 1 reply; 18+ messages in thread From: Thomas Rast @ 2009-10-13 20:15 UTC (permalink / raw) To: Miklos Vajna; +Cc: bill lam, git [-- 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 ' 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 --] ^ permalink raw reply related [flat|nested] 18+ messages in thread
* Re: quote in help code example 2009-10-13 20:15 ` Thomas Rast @ 2009-10-15 12:02 ` Thomas Rast 2009-10-21 8:24 ` [PATCH] Quote ' as \(aq in manpages Thomas Rast 0 siblings, 1 reply; 18+ messages in thread From: Thomas Rast @ 2009-10-15 12:02 UTC (permalink / raw) To: Miklos Vajna; +Cc: bill lam, git 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 ^ permalink raw reply [flat|nested] 18+ messages in thread
* [PATCH] Quote ' as \(aq in manpages 2009-10-15 12:02 ` Thomas Rast @ 2009-10-21 8:24 ` Thomas Rast 2009-10-21 10:38 ` Miklos Vajna 2009-10-21 18:01 ` Anders Kaseorg 0 siblings, 2 replies; 18+ messages in thread From: Thomas Rast @ 2009-10-21 8:24 UTC (permalink / raw) To: git; +Cc: Junio C Hamano 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 ^ permalink raw reply related [flat|nested] 18+ messages in thread
* Re: [PATCH] Quote ' as \(aq in manpages 2009-10-21 8:24 ` [PATCH] Quote ' as \(aq in manpages Thomas Rast @ 2009-10-21 10:38 ` Miklos Vajna 2009-10-21 18:01 ` Anders Kaseorg 1 sibling, 0 replies; 18+ messages in thread From: Miklos Vajna @ 2009-10-21 10:38 UTC (permalink / raw) To: Thomas Rast; +Cc: git, Junio C Hamano [-- 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 --] ^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH] Quote ' as \(aq in manpages 2009-10-21 8:24 ` [PATCH] Quote ' as \(aq in manpages Thomas Rast 2009-10-21 10:38 ` Miklos Vajna @ 2009-10-21 18:01 ` Anders Kaseorg 2009-10-21 18:57 ` [PATCH v2] " Thomas Rast 1 sibling, 1 reply; 18+ messages in thread From: Anders Kaseorg @ 2009-10-21 18:01 UTC (permalink / raw) To: Thomas Rast; +Cc: git, Junio C Hamano 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 ^ permalink raw reply [flat|nested] 18+ messages in thread
* [PATCH v2] Quote ' as \(aq in manpages 2009-10-21 18:01 ` Anders Kaseorg @ 2009-10-21 18:57 ` Thomas Rast 2009-10-21 21:31 ` [PATCH] Document GNU_ROFF in Makefile Miklos Vajna 2009-10-21 21:42 ` [PATCH v2] " Anders Kaseorg 0 siblings, 2 replies; 18+ messages in thread From: Thomas Rast @ 2009-10-21 18:57 UTC (permalink / raw) To: git; +Cc: Anders Kaseorg, Miklos Vajna, Junio C Hamano, bill lam 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 ^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH] Document GNU_ROFF in Makefile 2009-10-21 18:57 ` [PATCH v2] " Thomas Rast @ 2009-10-21 21:31 ` Miklos Vajna 2009-10-21 22:22 ` Junio C Hamano 2009-10-21 21:42 ` [PATCH v2] " Anders Kaseorg 1 sibling, 1 reply; 18+ messages in thread From: Miklos Vajna @ 2009-10-21 21:31 UTC (permalink / raw) To: Thomas Rast; +Cc: git, Anders Kaseorg, Junio C Hamano, bill lam 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 ^ permalink raw reply related [flat|nested] 18+ messages in thread
* Re: [PATCH] Document GNU_ROFF in Makefile 2009-10-21 21:31 ` [PATCH] Document GNU_ROFF in Makefile Miklos Vajna @ 2009-10-21 22:22 ` Junio C Hamano 2009-10-21 22:51 ` Anders Kaseorg 0 siblings, 1 reply; 18+ messages in thread From: Junio C Hamano @ 2009-10-21 22:22 UTC (permalink / raw) To: Miklos Vajna; +Cc: Thomas Rast, git, Anders Kaseorg, Junio C Hamano, bill lam 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 ^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH] Document GNU_ROFF in Makefile 2009-10-21 22:22 ` Junio C Hamano @ 2009-10-21 22:51 ` Anders Kaseorg 2009-10-22 8:19 ` [PATCH v3] Quote ' as \(aq in manpages Thomas Rast 0 siblings, 1 reply; 18+ messages in thread From: Anders Kaseorg @ 2009-10-21 22:51 UTC (permalink / raw) To: Junio C Hamano; +Cc: Miklos Vajna, Thomas Rast, git, bill lam 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 ^ permalink raw reply [flat|nested] 18+ messages in thread
* [PATCH v3] Quote ' as \(aq in manpages 2009-10-21 22:51 ` Anders Kaseorg @ 2009-10-22 8:19 ` Thomas Rast 0 siblings, 0 replies; 18+ messages in thread From: Thomas Rast @ 2009-10-22 8:19 UTC (permalink / raw) To: git; +Cc: Anders Kaseorg, Miklos Vajna, Junio C Hamano, bill lam 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 ^ permalink raw reply related [flat|nested] 18+ messages in thread
* Re: [PATCH v2] Quote ' as \(aq in manpages 2009-10-21 18:57 ` [PATCH v2] " Thomas Rast 2009-10-21 21:31 ` [PATCH] Document GNU_ROFF in Makefile Miklos Vajna @ 2009-10-21 21:42 ` Anders Kaseorg 1 sibling, 0 replies; 18+ messages in thread From: Anders Kaseorg @ 2009-10-21 21:42 UTC (permalink / raw) To: Thomas Rast; +Cc: git, Miklos Vajna, Junio C Hamano, bill lam 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 ^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: quote in help code example 2009-10-12 10:29 quote in help code example bill lam 2009-10-12 19:40 ` Miklos Vajna @ 2009-10-12 21:06 ` Junio C Hamano 1 sibling, 0 replies; 18+ messages in thread From: Junio C Hamano @ 2009-10-12 21:06 UTC (permalink / raw) To: bill lam; +Cc: git 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). ^ permalink raw reply [flat|nested] 18+ messages in thread
end of thread, other threads:[~2009-10-22 8:19 UTC | newest] Thread overview: 18+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2009-10-12 10:29 quote in help code example bill lam 2009-10-12 19:40 ` Miklos Vajna 2009-10-13 2:16 ` bill lam 2009-10-13 10:19 ` Miklos Vajna 2009-10-13 14:06 ` bill lam 2009-10-13 15:30 ` Miklos Vajna 2009-10-13 20:15 ` Thomas Rast 2009-10-15 12:02 ` Thomas Rast 2009-10-21 8:24 ` [PATCH] Quote ' as \(aq in manpages Thomas Rast 2009-10-21 10:38 ` Miklos Vajna 2009-10-21 18:01 ` Anders Kaseorg 2009-10-21 18:57 ` [PATCH v2] " Thomas Rast 2009-10-21 21:31 ` [PATCH] Document GNU_ROFF in Makefile Miklos Vajna 2009-10-21 22:22 ` Junio C Hamano 2009-10-21 22:51 ` Anders Kaseorg 2009-10-22 8:19 ` [PATCH v3] Quote ' as \(aq in manpages Thomas Rast 2009-10-21 21:42 ` [PATCH v2] " Anders Kaseorg 2009-10-12 21:06 ` quote in help code example Junio C Hamano
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).