{"thread":{"id":"21208","subject":"quote in help code example","startedAt":"2009-10-12T10:29:26Z","lastAt":"2009-10-22T08:19:06Z","messageCount":18,"participants":["bill lam","Miklos Vajna","Junio C Hamano","Thomas Rast","Anders Kaseorg"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"124684","messageId":"20091012102926.GA3937@debian.b2j","threadId":"21208","inReplyTo":null,"subject":"quote in help code example","fromName":"bill lam","fromEmail":"cbill.lam@gmail.com","sentAt":"2009-10-12T10:29:26Z","receivedAt":"2009-10-12T10:29:26Z","isPatch":false,"sender":{"key":"cbill.lam@gmail.com","avatar":null},"body":"In git man, eg. git help filter-branch\nThe code examples for command line or shell scripts inside .ft pairs\nuse (smart?) quote instead of single quotes, like\n\n .ft C\n git filter-branch --tree-filter ´rm filename´ HEAD\n .ft\n\nIs this intentional or just some configuration problem during\ncompiling.\n\n-- \nregards,\n====================================================\nGPG key 1024D/4434BAB3 2008-08-24\ngpg --keyserver subkeys.pgp.net --recv-keys 4434BAB3\n"},{"id":"124741","messageId":"20091012194016.GS23777@genesis.frugalware.org","threadId":"21208","inReplyTo":"20091012102926.GA3937@debian.b2j","subject":"Re: quote in help code example","fromName":"Miklos Vajna","fromEmail":"vmiklos@frugalware.org","sentAt":"2009-10-12T19:40:16Z","receivedAt":"2009-10-12T19:40:16Z","isPatch":false,"sender":{"key":"vmiklos@frugalware.org","avatar":"https://gravatar.com/avatar/401c1cbbb3a5d13e650c691a2c71d6fd0b80df1a01bc74d9f1972675dd58f2bd?d=mp&s=160"},"body":"On Mon, Oct 12, 2009 at 06:29:26PM +0800, bill lam wrote:\n> In git man, eg. git help filter-branch\n> The code examples for command line or shell scripts inside .ft pairs\n> use (smart?) quote instead of single quotes, like\n> \n> .ft C\n> git filter-branch --tree-filter ´rm filename´ HEAD\n> .ft\n> \n> Is this intentional or just some configuration problem during\n> compiling.\n\nJust a guess: do you have docbook-xsl >=1.73.0 and you did not set\nASCIIDOC_NO_ROFF?\n\nTry rebuilding the documentation using 'make ASCIIDOC_NO_ROFF=YesPlease'.\n"},{"id":"124749","messageId":"7v3a5oe2zo.fsf@alter.siamese.dyndns.org","threadId":"21208","inReplyTo":"20091012102926.GA3937@debian.b2j","subject":"Re: quote in help code example","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-10-12T21:06:35Z","receivedAt":"2009-10-12T21:06:35Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"bill lam writes:\n\n> In git man, eg. git help filter-branch\n> The code examples for command line or shell scripts inside .ft pairs\n> use (smart?) quote instead of single quotes, like\n>\n> .ft C\n> git filter-branch --tree-filter ´rm filename´ HEAD\n> .ft\n>\n> Is this intentional or just some configuration problem during\n> compiling.\n\nI see these in Documentation/Makefile:\n #\n # For asciidoc ...\n #\t-7.1.2,\tno extra settings are needed.\n #\t8.0-,\tset ASCIIDOC8.\n #\n\n #\n # For docbook-xsl ...\n #\t-1.68.1,\tset ASCIIDOC_NO_ROFF? (based on changelog from 1.73.0)\n #\t1.69.0,\t\tno extra settings are needed?\n #\t1.69.1-1.71.0,\tset DOCBOOK_SUPPRESS_SP?\n #\t1.71.1,\t\tno extra settings are needed?\n #\t1.72.0,\t\tset DOCBOOK_XSL_172.\n #\t1.73.0-,\tset ASCIIDOC_NO_ROFF\n #\n\n #\n # If you had been using DOCBOOK_XSL_172 in an attempt to get rid\n # of 'the \".ft C\" problem' in your generated manpages, and you\n # instead ended up with weird characters around callouts, try\n # using ASCIIDOC_NO_ROFF instead (it works fine with ASCIIDOC8).\n"},{"id":"124785","messageId":"20091013021616.GA10554@debian.b2j","threadId":"21208","inReplyTo":"20091012194016.GS23777@genesis.frugalware.org","subject":"Re: quote in help code example","fromName":"bill lam","fromEmail":"cbill.lam@gmail.com","sentAt":"2009-10-13T02:16:17Z","receivedAt":"2009-10-13T02:16:17Z","isPatch":false,"sender":{"key":"cbill.lam@gmail.com","avatar":null},"body":"On Mon, 12 Oct 2009, Miklos Vajna wrote:\n> On Mon, Oct 12, 2009 at 06:29:26PM +0800, bill lam wrote:\n> > In git man, eg. git help filter-branch\n> > The code examples for command line or shell scripts inside .ft pairs\n> > use (smart?) quote instead of single quotes, like\n> > \n> > .ft C\n> > git filter-branch --tree-filter ´rm filename´ HEAD\n> > .ft\n> > \n> > Is this intentional or just some configuration problem during\n> > compiling.\n> \n> Just a guess: do you have docbook-xsl >=1.73.0 and you did not set\n> ASCIIDOC_NO_ROFF?\n> \n> Try rebuilding the documentation using 'make ASCIIDOC_NO_ROFF=YesPlease'.\n\nI'm not familiar with how to twist git makefile. By adding a line to ./Makefile\n\n# Platform specific tweaks\n#\n\n# We choose to avoid \"if .. else if .. else .. endif endif\"\n# because maintaining the nesting to match is a pain. If\n# we had \"elif\" things would have been much nicer...\n\nASCIIDOC_NO_ROFF = YesPlease # <--- this line added\nifeq ($(uname_S),Linux)\n\nHowever, the man page still display the same\n\n .ft C\n git filter-branch --tree-filter ´rm filename´ HEAD\n .ft\n\nI use debian lenny 64bit with\nPackage: docbook-xsl\nVersion: 1.73.2.dfsg.1-5\n\nPackage: asciidoc\nVersion: 8.2.7-3~lenny1\n\n-- \nregards,\n====================================================\nGPG key 1024D/4434BAB3 2008-08-24\ngpg --keyserver subkeys.pgp.net --recv-keys 4434BAB3\n"},{"id":"124836","messageId":"20091013101916.GV23777@genesis.frugalware.org","threadId":"21208","inReplyTo":"20091013021616.GA10554@debian.b2j","subject":"Re: quote in help code example","fromName":"Miklos Vajna","fromEmail":"vmiklos@frugalware.org","sentAt":"2009-10-13T10:19:16Z","receivedAt":"2009-10-13T10:19:16Z","isPatch":false,"sender":{"key":"vmiklos@frugalware.org","avatar":"https://gravatar.com/avatar/401c1cbbb3a5d13e650c691a2c71d6fd0b80df1a01bc74d9f1972675dd58f2bd?d=mp&s=160"},"body":"On Tue, Oct 13, 2009 at 10:16:17AM +0800, bill lam wrote:\n> > Just a guess: do you have docbook-xsl >=1.73.0 and you did not set\n> > ASCIIDOC_NO_ROFF?\n> > \n> > Try rebuilding the documentation using 'make ASCIIDOC_NO_ROFF=YesPlease'.\n> \n> I'm not familiar with how to twist git makefile. By adding a line to ./Makefile\n> \n> # Platform specific tweaks\n> #\n> \n> # We choose to avoid \"if .. else if .. else .. endif endif\"\n> # because maintaining the nesting to match is a pain. If\n> # we had \"elif\" things would have been much nicer...\n> \n> ASCIIDOC_NO_ROFF = YesPlease # <--- this line added\n> ifeq ($(uname_S),Linux)\n> \n> However, the man page still display the same\n\nDon't edit the Makefile, just use the command 'make\nASCIIDOC_NO_ROFF=YesPlease'. Also make sure to do a 'make clean' in the\nDocumentation dir to get the manpages rebuilt.\n"},{"id":"124846","messageId":"20091013140622.GA3927@debian.b2j","threadId":"21208","inReplyTo":"20091013101916.GV23777@genesis.frugalware.org","subject":"Re: quote in help code example","fromName":"bill lam","fromEmail":"cbill.lam@gmail.com","sentAt":"2009-10-13T14:06:23Z","receivedAt":"2009-10-13T14:06:23Z","isPatch":false,"sender":{"key":"cbill.lam@gmail.com","avatar":null},"body":"On Tue, 13 Oct 2009, Miklos Vajna wrote:\n> On Tue, Oct 13, 2009 at 10:16:17AM +0800, bill lam wrote:\n> > > Just a guess: do you have docbook-xsl >=1.73.0 and you did not set\n> > > ASCIIDOC_NO_ROFF?\n> > > \n> > > Try rebuilding the documentation using 'make ASCIIDOC_NO_ROFF=YesPlease'.\n> > \n> > I'm not familiar with how to twist git makefile. By adding a line to ./Makefile\n> > \n> > # Platform specific tweaks\n> > #\n> > \n> > # We choose to avoid \"if .. else if .. else .. endif endif\"\n> > # because maintaining the nesting to match is a pain. If\n> > # we had \"elif\" things would have been much nicer...\n> > \n> > ASCIIDOC_NO_ROFF = YesPlease # <--- this line added\n> > ifeq ($(uname_S),Linux)\n> > \n> > However, the man page still display the same\n> \n> Don't edit the Makefile, just use the command 'make\n> ASCIIDOC_NO_ROFF=YesPlease'. Also make sure to do a 'make clean' in the\n> Documentation dir to get the manpages rebuilt.\n\nI run these commands \n\nmake ASCIIDOC_NO_ROFF=YesPlease prefix=/usr all doc info\nsudo make ASCIIDOC_NO_ROFF=YesPlease prefix=/usr install install-doc install-html install-info\n\n1. did I need to set ASCIIDOC_NO_ROFF in both lines?\n2. now the .ft pair fixed but it still displayed incorrect quote.\n\n git filter-branch --tree-filter ´rm filename´ HEAD\n\nit should be 'rm filename' not ´rm filename´\n\n-- \nregards,\n====================================================\nGPG key 1024D/4434BAB3 2008-08-24\ngpg --keyserver subkeys.pgp.net --recv-keys 4434BAB3\n"},{"id":"124850","messageId":"20091013153031.GX23777@genesis.frugalware.org","threadId":"21208","inReplyTo":"20091013140622.GA3927@debian.b2j","subject":"Re: quote in help code example","fromName":"Miklos Vajna","fromEmail":"vmiklos@frugalware.org","sentAt":"2009-10-13T15:30:31Z","receivedAt":"2009-10-13T15:30:31Z","isPatch":false,"sender":{"key":"vmiklos@frugalware.org","avatar":"https://gravatar.com/avatar/401c1cbbb3a5d13e650c691a2c71d6fd0b80df1a01bc74d9f1972675dd58f2bd?d=mp&s=160"},"body":"On Tue, Oct 13, 2009 at 10:06:23PM +0800, bill lam wrote:\n> I run these commands \n> \n> make ASCIIDOC_NO_ROFF=YesPlease prefix=/usr all doc info\n> sudo make ASCIIDOC_NO_ROFF=YesPlease prefix=/usr install install-doc install-html install-info\n> \n> 1. did I need to set ASCIIDOC_NO_ROFF in both lines?\n\nIn general, it's always a good idea, though I don't think it's necessary\nfor the second time.\n\n> 2. now the .ft pair fixed but it still displayed incorrect quote.\n> \n> git filter-branch --tree-filter ´rm filename´ HEAD\n> \n> it should be 'rm filename' not ´rm filename´\n\nI can reproduce that here as well, that's how it is in the official\nmanpages as well (see the man branch), so that's not specific to your\nsystem.\n"},{"id":"124885","messageId":"200910132215.46840.trast@student.ethz.ch","threadId":"21208","inReplyTo":"20091013153031.GX23777@genesis.frugalware.org","subject":"Re: quote in help code example","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2009-10-13T20:15:44Z","receivedAt":"2009-10-13T20:15:44Z","isPatch":false,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Miklos Vajna wrote:\n> On Tue, Oct 13, 2009 at 10:06:23PM +0800, bill lam wrote:\n> > 2. now the .ft pair fixed but it still displayed incorrect quote.\n> > \n> > git filter-branch --tree-filter ´rm filename´ HEAD\n> > \n> > it should be 'rm filename' not ´rm filename´\n> \n> I can reproduce that here as well, that's how it is in the official\n> manpages as well (see the man branch), so that's not specific to your\n> system.\n\nSame here. The patch below is a band-aid fix that works for me, but\nI'd rather have it tested on various docbook/asciidoc combinations if\nanyone still runs them.\n\nMy findings so far were that asciidoc correctly turns the apostrophe\ninto an ' entity in the .xml output, and xmlto then turns it into\n\\' instead of just ' in the troff output. Then, if the terminal\nappears to support Unicode (this can be disabled with LC_ALL=C or\nsuch) the formatter turns it into a \"real\" apostrophe that, of course,\nis not understood by any ASCII-based tool.\n\nSo far so good, and sounded like an easy debugging job, right? Not\nso. The buzzword-compliance people apparently felt it would be nice\nto wrap a bad joke of a language in the bad joke of a language that\nXML already is, and thus was XSL invented. Deep in the horrors of\nthese XSL files, in my case in\n\n /usr/share/xml/docbook/stylesheet/nwalsh/1.75.2/manpages/other.xsl\n\nthere's a template that, according to the comment near it, maltreats\nour apostrophes:\n\n * The backslash, dot, dash, and apostrophe (\\, ., -, ') characters\n * have special meaning for roff, so before we do any other\n * processing, we must escape those characters where they appear in\n * the source content.\n\nThe patch below just replaces said template with a no-op for git's\nmanpage creation. I have not been able to substantiate the claim that\napostrophes are special, and in fact with the patch my manpages look\nfine. Then again I don't know anything about roff syntax either, and\nmanuals seem a bit hard to come by.\n\nGrrr.\n\ndiff --git i/Documentation/manpage-base.xsl w/Documentation/manpage-base.xsl\nindex a264fa6..7c14469 100644\n--- i/Documentation/manpage-base.xsl\n+++ w/Documentation/manpage-base.xsl\n@@ -7,6 +7,11 @@\n \n \n \n+\n+ \n+ \n+\n+\n \n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"},{"id":"125072","messageId":"200910151402.56295.trast@student.ethz.ch","threadId":"21208","inReplyTo":"200910132215.46840.trast@student.ethz.ch","subject":"Re: quote in help code example","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2009-10-15T12:02:55Z","receivedAt":"2009-10-15T12:02:55Z","isPatch":false,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Thomas Rast wrote:\n> \n> The patch below just replaces said template with a no-op for git's\n> manpage creation. I have not been able to substantiate the claim that\n> apostrophes are special, and in fact with the patch my manpages look\n> fine. Then again I don't know anything about roff syntax either, and\n> manuals seem a bit hard to come by.\n\nActually, scratch the patch. I haven't been able to nail it yet, and\nI'm not sure I have the energy for another stab at this mess; but\nduring testing with older versions, I learned that they behave\ndifferently and the patch just shifts the breakage a bit.\n\nAlso, the single quotes are apparently special at the beginning of a\nline and to delimit function arguments, though not elsewhere. The\nbash manpage uses \\(aq to get a literal apostrophe, which I will aim\nto convert them to. Oddly enough, the groff(7) manpage does not\ndocument \\(aq, but lists \\(cq as the official escape for ' ... which\nthen turns out to mutate into this cursed non-apostrophe again. Sigh.\n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"},{"id":"125581","messageId":"ab31eb03b25272341b91e1f1132dab9d8a49e5b6.1256113282.git.trast@student.ethz.ch","threadId":"21208","inReplyTo":"200910151402.56295.trast@student.ethz.ch","subject":"[PATCH] Quote ' as \\(aq in manpages","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2009-10-21T08:24:42Z","receivedAt":"2009-10-21T08:24:42Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"The docbook/xmlto toolchain insists on quoting ' as \\'. This does\nachieve the quoting goal, but modern 'man' implementations turn the\napostrophe into a unicode \"proper\" apostrophe (given the right\ncircumstances), breaking code examples in many of our manpages.\n\nQuote them as \\(aq instead, which is an \"apostrophe quote\" as per the\ngroff_char manpage.\n\nSigned-off-by: Thomas Rast \n---\n\nI've had this around since my last rant, and it actually gives good\nresults with both setups I can test on, which are:\n\n- asciidoc 8.4.5, docbook-xsl 1.75.2, xmlto 0.0.18\n- asciidoc 8.2.7, docbook-xsl 1.73.2, xmlto 0.0.20\n\n\n Documentation/manpage-base.xsl | 9 +++++++++\n 1 files changed, 9 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/manpage-base.xsl b/Documentation/manpage-base.xsl\nindex a264fa6..bf74bb7 100644\n--- a/Documentation/manpage-base.xsl\n+++ b/Documentation/manpage-base.xsl\n@@ -7,6 +7,15 @@\n \n \n \n+\n+ \n+ \n+ \n+ '\n+ \\(aq\n+ \n+\n+\n \n-- \n1.6.5.1.144.g40216\n"},{"id":"125584","messageId":"20091021103843.GO6115@genesis.frugalware.org","threadId":"21208","inReplyTo":"ab31eb03b25272341b91e1f1132dab9d8a49e5b6.1256113282.git.trast@student.ethz.ch","subject":"Re: [PATCH] Quote ' as \\(aq in manpages","fromName":"Miklos Vajna","fromEmail":"vmiklos@frugalware.org","sentAt":"2009-10-21T10:38:43Z","receivedAt":"2009-10-21T10:38:43Z","isPatch":true,"sender":{"key":"vmiklos@frugalware.org","avatar":"https://gravatar.com/avatar/401c1cbbb3a5d13e650c691a2c71d6fd0b80df1a01bc74d9f1972675dd58f2bd?d=mp&s=160"},"body":"On Wed, Oct 21, 2009 at 10:24:42AM +0200, Thomas Rast wrote:\n> The docbook/xmlto toolchain insists on quoting ' as \\'. This does\n> achieve the quoting goal, but modern 'man' implementations turn the\n> apostrophe into a unicode \"proper\" apostrophe (given the right\n> circumstances), breaking code examples in many of our manpages.\n> \n> Quote them as \\(aq instead, which is an \"apostrophe quote\" as per the\n> groff_char manpage.\n> \n> Signed-off-by: Thomas Rast \n> ---\n> \n> I've had this around since my last rant, and it actually gives good\n> results with both setups I can test on, which are:\n> \n> - asciidoc 8.4.5, docbook-xsl 1.75.2, xmlto 0.0.18\n> - asciidoc 8.2.7, docbook-xsl 1.73.2, xmlto 0.0.20\n\nTested-by: Miklos Vajna \n\n- asciidoc 8.3.5, docbook-xsl 1.74.0, xmlto 0.0.20\n"},{"id":"125627","messageId":"alpine.DEB.2.00.0910211357160.5105@dr-wily.mit.edu","threadId":"21208","inReplyTo":"ab31eb03b25272341b91e1f1132dab9d8a49e5b6.1256113282.git.trast@student.ethz.ch","subject":"Re: [PATCH] Quote ' as \\(aq in manpages","fromName":"Anders Kaseorg","fromEmail":"andersk@mit.edu","sentAt":"2009-10-21T18:01:11Z","receivedAt":"2009-10-21T18:01:11Z","isPatch":true,"sender":{"key":"andersk@mit.edu","avatar":"https://avatars.githubusercontent.com/u/26471?v=4"},"body":"On Wed, 21 Oct 2009, Thomas Rast wrote:\n> The docbook/xmlto toolchain insists on quoting ' as \\'. This does\n> achieve the quoting goal, but modern 'man' implementations turn the\n> apostrophe into a unicode \"proper\" apostrophe (given the right\n> circumstances), breaking code examples in many of our manpages.\n> \n> Quote them as \\(aq instead, which is an \"apostrophe quote\" as per the\n> groff_char manpage.\n\n\\(aq is not portable to non-GNU roff. See\n http://bugs.debian.org/507673#65\n http://sourceforge.net/tracker/index.php?func=detail&aid=2412738&group_id=21935&atid=373747\nfor a proposed portable solution.\n\nAnders\n"},{"id":"125633","messageId":"7a3e6c8c5a11e14c19bc1a27608dcc78171c9feb.1256151199.git.trast@student.ethz.ch","threadId":"21208","inReplyTo":"alpine.DEB.2.00.0910211357160.5105@dr-wily.mit.edu","subject":"[PATCH v2] Quote ' as \\(aq in manpages","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2009-10-21T18:57:27Z","receivedAt":"2009-10-21T18:57:27Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"The docbook/xmlto toolchain insists on quoting ' as \\'. This does\nachieve the quoting goal, but modern 'man' implementations turn the\napostrophe into a unicode \"proper\" apostrophe (given the right\ncircumstances), breaking code examples in many of our manpages.\n\nQuote them as \\(aq instead, which is an \"apostrophe quote\" as per the\ngroff_char manpage.\n\nUnfortunately, as Anders Kaseorg kindly pointed out, this is not\nportable beyond groff, so we add an extra Makefile variable GNU_ROFF\nwhich you need to enable to get the new quoting.\n\nSigned-off-by: Thomas Rast \n---\n\n[Reinstated the Cc list, which I accidentally dropped when sending the\nfirst patch...]\n\nAnders Kaseorg wrote:\n> \\(aq is not portable to non-GNU roff. See\n> http://bugs.debian.org/507673#65\n> http://sourceforge.net/tracker/index.php?func=detail&aid=2412738&group_id=21935&atid=373747\n> for a proposed portable solution.\n\nThanks for pointing that out. Makes things a lot easier though. I'm\nreally beginning to enjoy the whole doc toolchain.\n\nI could not find a way to insert the proposed definitions into the\nheader by tweaking the xsls, so unless someone comes up with a way of\ndoing that, this is the best I can do.\n\nTo save you the effort of clicking the links, the header definitions\nwould be\n\n.ie \\n(.g .ds Aq \\(aq\n.el .ds Aq '\n\nand you then have to change the template to quote to \\(Aq instead.\n\n\n Documentation/Makefile | 3 +++\n Documentation/manpage-quote-apos.xsl | 16 ++++++++++++++++\n 2 files changed, 19 insertions(+), 0 deletions(-)\n create mode 100644 Documentation/manpage-quote-apos.xsl\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 06b0c57..68876d0 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -102,6 +102,9 @@ endif\n ifdef DOCBOOK_SUPPRESS_SP\n XMLTO_EXTRA += -m manpage-suppress-sp.xsl\n endif\n+ifdef GNU_ROFF\n+XMLTO_EXTRA += -m manpage-quote-apos.xsl\n+endif\n \n SHELL_PATH ?= $(SHELL)\n # Shell quote;\ndiff --git a/Documentation/manpage-quote-apos.xsl b/Documentation/manpage-quote-apos.xsl\nnew file mode 100644\nindex 0000000..aeb8839\n--- /dev/null\n+++ b/Documentation/manpage-quote-apos.xsl\n@@ -0,0 +1,16 @@\n+\n+\n+\n+\n+ \n+ \n+ \n+ '\n+ \\(aq\n+ \n+\n+\n+\n-- \n1.6.5.1.144.g316236\n"},{"id":"125651","messageId":"20091021213149.GX6115@genesis.frugalware.org","threadId":"21208","inReplyTo":"7a3e6c8c5a11e14c19bc1a27608dcc78171c9feb.1256151199.git.trast@student.ethz.ch","subject":"[PATCH] Document GNU_ROFF in Makefile","fromName":"Miklos Vajna","fromEmail":"vmiklos@frugalware.org","sentAt":"2009-10-21T21:31:49Z","receivedAt":"2009-10-21T21:31:49Z","isPatch":true,"sender":{"key":"vmiklos@frugalware.org","avatar":"https://gravatar.com/avatar/401c1cbbb3a5d13e650c691a2c71d6fd0b80df1a01bc74d9f1972675dd58f2bd?d=mp&s=160"},"body":"Signed-off-by: Miklos Vajna \n---\n\nOn Wed, Oct 21, 2009 at 08:57:27PM +0200, Thomas Rast wrote:\n> Unfortunately, as Anders Kaseorg kindly pointed out, this is not\n> portable beyond groff, so we add an extra Makefile variable GNU_ROFF\n> which you need to enable to get the new quoting.\n\nYou forgot to document this in Makefile. Maybe this could be just\nsquashed in, Junio will decide.\n\n Makefile | 3 +++\n 1 files changed, 3 insertions(+), 0 deletions(-)\n\ndiff --git a/Makefile b/Makefile\nindex fea237b..40da590 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -159,6 +159,9 @@ all::\n # Define ASCIIDOC_NO_ROFF if your DocBook XSL escapes raw roff directives\n # (versions 1.72 and later and 1.68.1 and earlier).\n #\n+# Define GNU_ROFF if you have GNU roff and you don't want to have pretty\n+# apostrophe so that cut&pasting examples to the shell will work.\n+#\n # Define NO_PERL_MAKEMAKER if you cannot use Makefiles generated by perl's\n # MakeMaker (e.g. using ActiveState under Cygwin).\n #\n-- \n1.6.5\n"},{"id":"125654","messageId":"alpine.DEB.2.00.0910211733310.5105@dr-wily.mit.edu","threadId":"21208","inReplyTo":"7a3e6c8c5a11e14c19bc1a27608dcc78171c9feb.1256151199.git.trast@student.ethz.ch","subject":"Re: [PATCH v2] Quote ' as \\(aq in manpages","fromName":"Anders Kaseorg","fromEmail":"andersk@mit.edu","sentAt":"2009-10-21T21:42:46Z","receivedAt":"2009-10-21T21:42:46Z","isPatch":true,"sender":{"key":"andersk@mit.edu","avatar":"https://avatars.githubusercontent.com/u/26471?v=4"},"body":"On Wed, 21 Oct 2009, Thomas Rast wrote:\n> Unfortunately, as Anders Kaseorg kindly pointed out, this is not \n> portable beyond groff, so we add an extra Makefile variable GNU_ROFF \n> which you need to enable to get the new quoting.\n\nNote that GNU_ROFF is a property of the target system on which the \nmanpages will be read, unlike the existing variables (ASCIIDOC8, \nDOCBOOK_XSL_172, ASCIIDOC_NO_ROFF) which are properties of the host system \non which they are built.\n\n> To save you the effort of clicking the links, the header definitions \n> would be\n>\n> .ie \\n(.g .ds Aq \\(aq\n> .el .ds Aq '\n>\n> and you then have to change the template to quote to \\(Aq instead.\n\nIf someone knows how to get this definition into the header, that would be \npreferable, because then you could read the same manpage on both GNU and \nnon-GNU systems instead of building separately for each.\n\nIt would be even better if someone would work with the Docbook developers \nto get this fixed upstream. (Unfortunately, there has been no reply to my \ncomment in their bug tracker.)\n\nAnders\n"},{"id":"125659","messageId":"7vk4yoz8sf.fsf@alter.siamese.dyndns.org","threadId":"21208","inReplyTo":"20091021213149.GX6115@genesis.frugalware.org","subject":"Re: [PATCH] Document GNU_ROFF in Makefile","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-10-21T22:22:56Z","receivedAt":"2009-10-21T22:22:56Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Miklos Vajna writes:\n\n> Signed-off-by: Miklos Vajna \n> ---\n>\n> On Wed, Oct 21, 2009 at 08:57:27PM +0200, Thomas Rast wrote:\n>> Unfortunately, as Anders Kaseorg kindly pointed out, this is not\n>> portable beyond groff, so we add an extra Makefile variable GNU_ROFF\n>> which you need to enable to get the new quoting.\n>\n> You forgot to document this in Makefile. Maybe this could be just\n> squashed in, Junio will decide.\n>\n> Makefile | 3 +++\n> 1 files changed, 3 insertions(+), 0 deletions(-)\n>\n> diff --git a/Makefile b/Makefile\n> index fea237b..40da590 100644\n> --- a/Makefile\n> +++ b/Makefile\n> @@ -159,6 +159,9 @@ all::\n> # Define ASCIIDOC_NO_ROFF if your DocBook XSL escapes raw roff directives\n> # (versions 1.72 and later and 1.68.1 and earlier).\n> #\n> +# Define GNU_ROFF if you have GNU roff and you don't want to have pretty\n> +# apostrophe so that cut&pasting examples to the shell will work.\n> +#\n\nThis makes it sound as if groff is the only roff implementation that has\nthis problem---iow, if we use non-GNU roff then the documentation comes\nout just fine. Is that the case?\n\nOr is the situation more like \"we know how to fix this for groff, and the\nfix is enabled if this variable is defined---on other roff implementations\nthe output is still broken\"?\n\n> # Define NO_PERL_MAKEMAKER if you cannot use Makefiles generated by perl's\n> # MakeMaker (e.g. using ActiveState under Cygwin).\n> #\n> -- \n> 1.6.5\n"},{"id":"125664","messageId":"alpine.DEB.2.00.0910211824220.5105@dr-wily.mit.edu","threadId":"21208","inReplyTo":"7vk4yoz8sf.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Document GNU_ROFF in Makefile","fromName":"Anders Kaseorg","fromEmail":"andersk@mit.edu","sentAt":"2009-10-21T22:51:33Z","receivedAt":"2009-10-21T22:51:33Z","isPatch":true,"sender":{"key":"andersk@mit.edu","avatar":"https://avatars.githubusercontent.com/u/26471?v=4"},"body":"On Wed, 21 Oct 2009, Junio C Hamano wrote:\n> > +# Define GNU_ROFF if you have GNU roff and you don't want to have pretty\n> > +# apostrophe so that cut&pasting examples to the shell will work.\n> \n> This makes it sound as if groff is the only roff implementation that has \n> this problem---iow, if we use non-GNU roff then the documentation comes \n> out just fine. Is that the case?\n\nYes:\n built without GNU_ROFF built with GNU_ROFF\n viewed with non-GNU roff correct (') wrong (no output!)\n viewed with GNU groff wrong (´) correct (')\n\nIn order to build a manpage that can be viewed correctly on both \nplatforms, the conditional logic should live in the manpage itself (as per \nthe bug comments I linked to and Thomas quoted from).\n\nAnders\n"},{"id":"125686","messageId":"232607a038ef84087b7c8c69e9038ec6c9f6ba01.1256199311.git.trast@student.ethz.ch","threadId":"21208","inReplyTo":"alpine.DEB.2.00.0910211824220.5105@dr-wily.mit.edu","subject":"[PATCH v3] Quote ' as \\(aq in manpages","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2009-10-22T08:19:06Z","receivedAt":"2009-10-22T08:19:06Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"The docbook/xmlto toolchain insists on quoting ' as \\'. This does\nachieve the quoting goal, but modern 'man' implementations turn the\napostrophe into a unicode \"proper\" apostrophe (given the right\ncircumstances), breaking code examples in many of our manpages.\n\nQuote them as \\(aq instead, which is an \"apostrophe quote\" as per the\ngroff_char manpage.\n\nUnfortunately, as Anders Kaseorg kindly pointed out, this is not\nportable beyond groff, so we add an extra Makefile variable GNU_ROFF\nwhich you need to enable to get the new quoting.\n\nThanks also to Miklos Vajna for documentation.\n\nSigned-off-by: Thomas Rast \n---\n\nAnders Kaseorg wrote:\n> On Wed, 21 Oct 2009, Junio C Hamano wrote:\n> > > +# Define GNU_ROFF if you have GNU roff and you don't want to have pretty\n> > > +# apostrophe so that cut&pasting examples to the shell will work.\n> > \n> > This makes it sound as if groff is the only roff implementation that has \n> > this problem---iow, if we use non-GNU roff then the documentation comes \n> > out just fine. Is that the case?\n> \n> Yes:\n\nI'll take your word for it, but I cannot test with anything non-GNU.\n\n> In order to build a manpage that can be viewed correctly on both \n> platforms, the conditional logic should live in the manpage itself (as per \n> the bug comments I linked to and Thomas quoted from).\n\nI reworded Miklos' doc patch a bit to indicate that it's about the\ntarget system, and also added a slightly longer comment to the\nDocumentation/Makefile for completeness.\n\n\n Documentation/Makefile | 8 ++++++++\n Documentation/manpage-quote-apos.xsl | 16 ++++++++++++++++\n Makefile | 4 ++++\n 3 files changed, 28 insertions(+), 0 deletions(-)\n create mode 100644 Documentation/manpage-quote-apos.xsl\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 06b0c57..cd5b439 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -103,6 +103,14 @@ ifdef DOCBOOK_SUPPRESS_SP\n XMLTO_EXTRA += -m manpage-suppress-sp.xsl\n endif\n \n+# If your target system uses GNU groff, it may try to render\n+# apostrophes as a \"pretty\" apostrophe using unicode. This breaks\n+# cut&paste, so you should set GNU_ROFF to force them to be ASCII\n+# apostrophes. Unfortunately does not work with non-GNU roff.\n+ifdef GNU_ROFF\n+XMLTO_EXTRA += -m manpage-quote-apos.xsl\n+endif\n+\n SHELL_PATH ?= $(SHELL)\n # Shell quote;\n SHELL_PATH_SQ = $(subst ','\\'',$(SHELL_PATH))\ndiff --git a/Documentation/manpage-quote-apos.xsl b/Documentation/manpage-quote-apos.xsl\nnew file mode 100644\nindex 0000000..aeb8839\n--- /dev/null\n+++ b/Documentation/manpage-quote-apos.xsl\n@@ -0,0 +1,16 @@\n+\n+\n+\n+\n+ \n+ \n+ \n+ '\n+ \\(aq\n+ \n+\n+\n+\ndiff --git a/Makefile b/Makefile\nindex fea237b..2ccbe4a 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -159,6 +159,10 @@ all::\n # Define ASCIIDOC_NO_ROFF if your DocBook XSL escapes raw roff directives\n # (versions 1.72 and later and 1.68.1 and earlier).\n #\n+# Define GNU_ROFF if your target system uses GNU groff. This forces\n+# apostrophes to be ASCII so that cut&pasting examples to the shell\n+# will work.\n+#\n # Define NO_PERL_MAKEMAKER if you cannot use Makefiles generated by perl's\n # MakeMaker (e.g. using ActiveState under Cygwin).\n #\n-- \n1.6.5.1.144.g316236\n"}]}