{"thread":{"id":"25767","subject":"groff .ft command use in asciidoc","startedAt":"2010-11-17T09:52:34Z","lastAt":"2010-11-20T01:48:09Z","messageCount":16,"participants":["Andi Kleen","Jonathan Nieder","Jeff King","Alejandro Riveira Fernández","Drew Northup","Junio C Hamano","Todd Zullinger"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"156039","messageId":"20101117095233.GA23817@basil.fritz.box","threadId":"25767","inReplyTo":null,"subject":"groff .ft command use in asciidoc","fromName":"Andi Kleen","fromEmail":"andi@firstfloor.org","sentAt":"2010-11-17T09:52:34Z","receivedAt":"2010-11-17T09:52:34Z","isPatch":false,"sender":{"key":"andi@firstfloor.org","avatar":null},"body":"\nHi,\n\nThe git manpages on my opensuse 11.3 (git 1.7.1-1.14)\nfrequently use the .ft command the opensuse groff does not \nrender.\n\nFor example from the final output of \"man git-commit\":\n\n           .ft C\n           $ edit hello.c\n           $ git rm goodbye.c\n           $ git add hello.c\n           $ git commit\n           .ft\n\n\nSo the .ft commands are visible.  It's really a cosmetic issue \nonly, but looks ugly and irritates me every time I \nlook something up in the man pages.\n\nI double checked against current git.git and the problem \nis still there, because .ft C is configured in \nDocumentation/asciidoc.conf\n\nNot sure what the best solution is. Stop using .ft\nand change asciidocs configuration?\n\n\n-Andi \n\n\n-- \nak@linux.intel.com -- Speaking for myself only.\n"},{"id":"156041","messageId":"20101117101516.GA12416@burratino","threadId":"25767","inReplyTo":"20101117095233.GA23817@basil.fritz.box","subject":"Re: groff .ft command use in asciidoc","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-11-17T10:15:16Z","receivedAt":"2010-11-17T10:15:16Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi,\n\nAndi Kleen wrote:\n\n> The git manpages on my opensuse 11.3 (git 1.7.1-1.14)\n> frequently use the .ft command the opensuse groff does not \n> render.\n> \n> For example from the final output of \"man git-commit\":\n> \n>            .ft C\n>            $ edit hello.c\n>            $ git rm goodbye.c\n>            $ git add hello.c\n>            $ git commit\n>            .ft\n\nThis is in my opinion a bug: unless you use ASCIIDOC_NO_ROFF, git's\nasciidoc.conf will include raw roff directives in the docbook markup\nit generates.  And then docbook will escape the periods, producing\nthe output you see.\n\nThe workaround is very simple: set ASCIIDOC_NO_ROFF to nonempty\nwhen you build documentation.\n\nI think the only reason this is not the default is that no one has\ntested it with old DocBook XSL versions, but I'm not sure.\nDocumentation/Makefile has some notes about this.\n\nHope that helps,\nJonathan\n"},{"id":"156044","messageId":"20101117115245.GB23656@basil.fritz.box","threadId":"25767","inReplyTo":"20101117101516.GA12416@burratino","subject":"Re: groff .ft command use in asciidoc","fromName":"Andi Kleen","fromEmail":"andi@firstfloor.org","sentAt":"2010-11-17T11:52:46Z","receivedAt":"2010-11-17T11:52:46Z","isPatch":false,"sender":{"key":"andi@firstfloor.org","avatar":null},"body":"> This is in my opinion a bug: unless you use ASCIIDOC_NO_ROFF, git's\n> asciidoc.conf will include raw roff directives in the docbook markup\n> it generates.  And then docbook will escape the periods, producing\n> the output you see.\n\nI see. Thanks for the explanation.\n\n> \n> The workaround is very simple: set ASCIIDOC_NO_ROFF to nonempty\n> when you build documentation.\n\nI will suggest to the opensuse git maintainers to set that variable.\n \n> I think the only reason this is not the default is that no one has\n> tested it with old DocBook XSL versions, but I'm not sure.\n> Documentation/Makefile has some notes about this.\n\nIt would be nice if that worked out of the box.\n\n-Andi\n\n-- \nak@linux.intel.com -- Speaking for myself only.\n"},{"id":"156048","messageId":"20101117143855.GA1987@sigill.intra.peff.net","threadId":"25767","inReplyTo":"20101117101516.GA12416@burratino","subject":"Re: groff .ft command use in asciidoc","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-11-17T14:38:55Z","receivedAt":"2010-11-17T14:38:55Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Nov 17, 2010 at 04:15:16AM -0600, Jonathan Nieder wrote:\n\n> This is in my opinion a bug: unless you use ASCIIDOC_NO_ROFF, git's\n> asciidoc.conf will include raw roff directives in the docbook markup\n> it generates.  And then docbook will escape the periods, producing\n> the output you see.\n\nIIRC, that depends very much on the versions of asciidoc and docbook you\nhave. Once upon a time, not setting ASCIIDOC_NO_ROFF was required for\nsane output.\n\nAndi, I would be curious to hear which asciidoc and docbook-xsl versions\nyou are using.\n\n> I think the only reason this is not the default is that no one has\n> tested it with old DocBook XSL versions, but I'm not sure.\n> Documentation/Makefile has some notes about this.\n\nAt the time those knobs came into being, the defaults were set for\nthen-current versions of the software. I suspect ASCIIDOC8 and\nASCIIDOC_NO_ROFF should be the default these days.\n\n-Peff\n"},{"id":"156053","messageId":"20101117154829.GE23656@basil.fritz.box","threadId":"25767","inReplyTo":"20101117143855.GA1987@sigill.intra.peff.net","subject":"Re: groff .ft command use in asciidoc","fromName":"Andi Kleen","fromEmail":"andi@firstfloor.org","sentAt":"2010-11-17T15:48:29Z","receivedAt":"2010-11-17T15:48:29Z","isPatch":false,"sender":{"key":"andi@firstfloor.org","avatar":null},"body":"On Wed, Nov 17, 2010 at 09:38:55AM -0500, Jeff King wrote:\n> On Wed, Nov 17, 2010 at 04:15:16AM -0600, Jonathan Nieder wrote:\n> Andi, I would be curious to hear which asciidoc and docbook-xsl versions\n> you are using.\n\nI see this with the git rpms in opensuse 11.3 which I didn't build.\nBut presumably it's built with asciidoc 8.4.5-5.1 and 1.75.2-7.1\n\n-Andi \n\n-- \nak@linux.intel.com -- Speaking for myself only.\n"},{"id":"156120","messageId":"ic3or7$dfi$1@dough.gmane.org","threadId":"25767","inReplyTo":"20101117101516.GA12416@burratino","subject":"Re: groff .ft command use in asciidoc","fromName":"Alejandro Riveira Fernández","fromEmail":"ariveira@gmail.com","sentAt":"2010-11-18T17:47:19Z","receivedAt":"2010-11-18T17:47:19Z","isPatch":false,"sender":{"key":"ariveira@gmail.com","avatar":null},"body":"On Wed, 17 Nov 2010 04:15:16 -0600, Jonathan Nieder wrote:\n\n\n> \n> This is in my opinion a bug: unless you use ASCIIDOC_NO_ROFF, git's\n> asciidoc.conf will include raw roff directives in the docbook markup it\n> generates.  And then docbook will escape the periods, producing the\n> output you see.\n> \n> The workaround is very simple: set ASCIIDOC_NO_ROFF to nonempty when you\n> build documentation.\n\n I use make quick-install-man which, afaik, installs man pages \n\"prerendered\" from the man branch and i see the same artifact.\n \n So can those man pages be rendered with this workaraound?\n \n Thanks\n\n\n\n> Hope that helps,\n> Jonathan\n"},{"id":"156138","messageId":"1290114671.2316.12.camel@drew-northup.unet.maine.edu","threadId":"25767","inReplyTo":"ic3or7$dfi$1@dough.gmane.org","subject":"Re: groff .ft command use in asciidoc","fromName":"Drew Northup","fromEmail":"drew.northup@maine.edu","sentAt":"2010-11-18T21:11:11Z","receivedAt":"2010-11-18T21:11:11Z","isPatch":false,"sender":{"key":"drew.northup@maine.edu","avatar":"https://avatars.githubusercontent.com/u/18331571?v=4"},"body":"\nOn Thu, 2010-11-18 at 17:47 +0000, Alejandro Riveira Fernández wrote:\n> On Wed, 17 Nov 2010 04:15:16 -0600, Jonathan Nieder wrote:\n \n> > This is in my opinion a bug: unless you use ASCIIDOC_NO_ROFF, git's\n> > asciidoc.conf will include raw roff directives in the docbook markup it\n> > generates.  And then docbook will escape the periods, producing the\n> > output you see.\n> > \n> > The workaround is very simple: set ASCIIDOC_NO_ROFF to nonempty when you\n> > build documentation.\n> \n>  I use make quick-install-man which, afaik, installs man pages \n> \"prerendered\" from the man branch and i see the same artifact.\n>  \n>  So can those man pages be rendered with this workaraound?\n>  \n>  Thanks\n\nOut of curiosity I went ahead and ran that make script. I then ran the\nfollowing in the directory that the manpage directories were written out\nto (an alternate DESTDIR):\n\n[dnorthup@drew-northup man]$ grep -R \"\\.ft\" *\n[dnorthup@drew-northup man]$ \n\nNote that it returned nothing. This is based on the current git.git. (I\njust pulled to be sure of that...)\n\nAs noted, all that make script essentially does is write out the\nmanpages found in origin/man--so it matters not what my current platform\nis.\n\nRun \"man git-commit\" in one terminal open up a second and run \"ps ax |\ngrep man\" and report on the results. \n\n-- \n-Drew Northup N1XIM\n   AKA RvnPhnx on OPN\n________________________________________________\n\"As opposed to vegetable or mineral error?\"\n-John Pescatore, SANS NewsBites Vol. 12 Num. 59\n"},{"id":"156143","messageId":"20101119001514.4cd0c4d9@varda","threadId":"25767","inReplyTo":"1290114671.2316.12.camel@drew-northup.unet.maine.edu","subject":"Re: groff .ft command use in asciidoc","fromName":"Alejandro Riveira Fernández","fromEmail":"ariveira@gmail.com","sentAt":"2010-11-18T23:15:14Z","receivedAt":"2010-11-18T23:15:14Z","isPatch":false,"sender":{"key":"ariveira@gmail.com","avatar":null},"body":"El Thu, 18 Nov 2010 16:11:11 -0500\nDrew Northup <drew.northup@maine.edu> escribió:\n\n> \n> On Thu, 2010-11-18 at 17:47 +0000, Alejandro Riveira Fernández wrote:\n> > On Wed, 17 Nov 2010 04:15:16 -0600, Jonathan Nieder wrote:\n>  \n> > > This is in my opinion a bug: unless you use ASCIIDOC_NO_ROFF, git's\n> > > asciidoc.conf will include raw roff directives in the docbook markup it\n> > > generates.  And then docbook will escape the periods, producing the\n> > > output you see.\n> > > \n> > > The workaround is very simple: set ASCIIDOC_NO_ROFF to nonempty when you\n> > > build documentation.\n> > \n> >  I use make quick-install-man which, afaik, installs man pages \n> > \"prerendered\" from the man branch and i see the same artifact.\n> >  \n> >  So can those man pages be rendered with this workaraound?\n> >  \n> >  Thanks\n> \n> Out of curiosity I went ahead and ran that make script. I then ran the\n> following in the directory that the manpage directories were written out\n> to (an alternate DESTDIR):\n\n Doh! ... the problem was between chair and keyboard. i used alternate DESTDIR\n with the make all and make install but with quick.-install-man i forgot to set \n it; so the man pages were old versions from when i actually builded the man\n pages myself\n Sorry for the wasted time ...\n\n> \n> [dnorthup@drew-northup man]$ grep -R \"\\.ft\" *\n> [dnorthup@drew-northup man]$ \n> \n After correcting the above\n $ grep -R \"\\.ft\" *\n man3/private-Error.3pm:.ft CW\n man3/private-Error.3pm:.ft R\n man3/Git.3pm:.ft CW\n man3/Git.3pm:.ft R\n \n Which are probably letfovers from previous builds ...\n   \n> Note that it returned nothing. This is based on the current git.git. (I\n> just pulled to be sure of that...)\n\n Thanks for checking and again. Sorry\n\n> \n> As noted, all that make script essentially does is write out the\n> manpages found in origin/man--so it matters not what my current platform\n> is.\n> \n> Run \"man git-commit\" in one terminal open up a second and run \"ps ax |\n> grep man\" and report on the results. \n\n For the sake of completeness\n  $ ps ax | grep man\n    585 ?        S<     0:00 [kondemand]\n   4994 ?        S      0:00 gnome-power-manager\n  32649 pts/2    S+     0:00 man git-commit\n  32690 pts/4    S+     0:00 grep man\n\n Bye.\n"},{"id":"156197","messageId":"20101119175424.GA13276@sigill.intra.peff.net","threadId":"25767","inReplyTo":"20101117154829.GE23656@basil.fritz.box","subject":"Re: groff .ft command use in asciidoc","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-11-19T17:54:24Z","receivedAt":"2010-11-19T17:54:24Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Nov 17, 2010 at 04:48:29PM +0100, Andi Kleen wrote:\n\n> On Wed, Nov 17, 2010 at 09:38:55AM -0500, Jeff King wrote:\n> > On Wed, Nov 17, 2010 at 04:15:16AM -0600, Jonathan Nieder wrote:\n> > Andi, I would be curious to hear which asciidoc and docbook-xsl versions\n> > you are using.\n> \n> I see this with the git rpms in opensuse 11.3 which I didn't build.\n> But presumably it's built with asciidoc 8.4.5-5.1 and 1.75.2-7.1\n\nThanks. I think technically that is a bug in opensuse's packaging, as\nthey are not setting the right knobs for their version. However, I think\nthese days we can make it easier for them. Perhaps it is time to apply\nthis:\n\n-- >8 --\nSubject: [PATCH] docs: default to more modern toolset\n\nWhen the ASCIIDOC8 and ASCIIDOC_NO_ROFF knobs were built,\nmany people were still on asciidoc 7 and using older\nversions of docbook-xsl. These days, even the almost\n2-year-old Debian stable needs these knobs turned.\n\nSo let's turn them by default. The new knobs ASCIIDOC7 and\nASCIIDOC_ROFF can be used to get the old behavior if people\nare on older systems.\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\nThese defaults work on Debian stable and further. It sounds like\nopensuse 11.3, too. I don't know about Fedora, but I suspect they are at\nleast as far along as Debian stable.\n\nRHEL5 has asciidoc8, but docbook-xsl 1.69, which means it still needs\nASCIIDOC_ROFF enabled. RHEL6 is just out last week. So we are\ntechnically breaking at least RHEL5 people (along with anybody with\nancient systems) until they tweak their knobs.\n\nHowever, I think it is worth it to avoid the hassle for the vast\nmajority of people on modern systems.\n\n Documentation/Makefile           |   23 ++++++++---------------\n Documentation/RelNotes/1.7.4.txt |    4 ++++\n INSTALL                          |    5 +++--\n Makefile                         |   10 +++++-----\n config.mak.in                    |    2 +-\n configure.ac                     |   12 ++++++------\n 6 files changed, 27 insertions(+), 29 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex e117bc4..36989b7 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -63,35 +63,28 @@ endif\n \n #\n # For asciidoc ...\n-#\t-7.1.2,\tno extra settings are needed.\n-#\t8.0-,\tset ASCIIDOC8.\n+#\t-7.1.2,\tset ASCIIDOC7\n+#\t8.0-,\tno extra settings are needed\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+#\t-1.68.1,\tno extra settings are needed?\n+#\t1.69.0,\t\tset ASCIIDOC_ROFF?\n #\t1.69.1-1.71.0,\tset DOCBOOK_SUPPRESS_SP?\n-#\t1.71.1,\t\tno extra settings are needed?\n+#\t1.71.1,\t\tset ASCIIDOC_ROFF?\n #\t1.72.0,\t\tset DOCBOOK_XSL_172.\n-#\t1.73.0-,\tset ASCIIDOC_NO_ROFF\n+#\t1.73.0-,\tno extra settings are needed\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-#\n-\n-ifdef ASCIIDOC8\n+ifndef ASCIIDOC7\n ASCIIDOC_EXTRA += -a asciidoc7compatible -a no-inline-literal\n endif\n ifdef DOCBOOK_XSL_172\n ASCIIDOC_EXTRA += -a git-asciidoc-no-roff\n MANPAGE_XSL = manpage-1.72.xsl\n else\n-\tifdef ASCIIDOC_NO_ROFF\n+\tifndef ASCIIDOC_ROFF\n \t# docbook-xsl after 1.72 needs the regular XSL, but will not\n \t# pass-thru raw roff codes from asciidoc.conf, so turn them off.\n \tASCIIDOC_EXTRA += -a git-asciidoc-no-roff\ndiff --git a/Documentation/RelNotes/1.7.4.txt b/Documentation/RelNotes/1.7.4.txt\nindex 05e8a43..87629c6 100644\n--- a/Documentation/RelNotes/1.7.4.txt\n+++ b/Documentation/RelNotes/1.7.4.txt\n@@ -32,6 +32,10 @@ Updates since v1.7.3\n    git-only login over ssh as login shell, with custom set of\n    commands.\n \n+ * The documentation Makefile now assumes by default asciidoc 8 and\n+   docbook-xsl >= 1.73. If you have older versions, you can set\n+   ASCIIDOC7 and ASCIIDOC_ROFF, respectively.\n+\n Also contains various documentation updates.\n \n \ndiff --git a/INSTALL b/INSTALL\nindex 10a1cba..16e45f1 100644\n--- a/INSTALL\n+++ b/INSTALL\n@@ -122,8 +122,9 @@ Issues of note:\n    Building and installing the pdf file additionally requires\n    dblatex.  Version 0.2.7 with asciidoc >= 8.2.7 is known to work.\n \n-   The documentation is written for AsciiDoc 7, but \"make\n-   ASCIIDOC8=YesPlease doc\" will let you format with AsciiDoc 8.\n+   The documentation is written for AsciiDoc 7, but by default\n+   uses some compatibility wrappers to work on AsciiDoc 8. If you have\n+   AsciiDoc 7, try \"make ASCIIDOC7=YesPlease\".\n \n    Alternatively, pre-formatted documentation is available in\n    \"html\" and \"man\" branches of the git repository itself.  For\ndiff --git a/Makefile b/Makefile\nindex 1f1ce04..9ddcae9 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -162,13 +162,13 @@ all::\n # Define NO_ST_BLOCKS_IN_STRUCT_STAT if your platform does not have st_blocks\n # field that counts the on-disk footprint in 512-byte blocks.\n #\n-# Define ASCIIDOC8 if you want to format documentation with AsciiDoc 8\n+# Define ASCIIDOC7 if you want to format documentation with AsciiDoc 7\n #\n # Define DOCBOOK_XSL_172 if you want to format man pages with DocBook XSL v1.72\n # (not v1.73 or v1.71).\n #\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+# Define ASCIIDOC_ROFF if your DocBook XSL does not escape raw roff directives\n+# (versions 1.68.1 through v1.72).\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@@ -1518,8 +1518,8 @@ ifndef V\n endif\n endif\n \n-ifdef ASCIIDOC8\n-\texport ASCIIDOC8\n+ifdef ASCIIDOC7\n+\texport ASCIIDOC7\n endif\n \n # Shell quote (do not use $(call) to accommodate ancient setups);\ndiff --git a/config.mak.in b/config.mak.in\nindex a0c34ee..55dcd30 100644\n--- a/config.mak.in\n+++ b/config.mak.in\n@@ -27,7 +27,7 @@ VPATH = @srcdir@\n export exec_prefix mandir\n export srcdir VPATH\n \n-ASCIIDOC8=@ASCIIDOC8@\n+ASCIIDOC7=@ASCIIDOC7@\n NEEDS_SSL_WITH_CRYPTO=@NEEDS_SSL_WITH_CRYPTO@\n NO_OPENSSL=@NO_OPENSSL@\n NO_CURL=@NO_CURL@\ndiff --git a/configure.ac b/configure.ac\nindex cc55b6d..e9ca117 100644\n--- a/configure.ac\n+++ b/configure.ac\n@@ -398,21 +398,21 @@ if test -n \"$ASCIIDOC\"; then\n \tAC_MSG_CHECKING([for asciidoc version])\n \tasciidoc_version=`$ASCIIDOC --version 2>/dev/null`\n \tcase \"${asciidoc_version}\" in\n-\tasciidoc' '8*)\n-\t\tASCIIDOC8=YesPlease\n+\tasciidoc' '7*)\n+\t\tASCIIDOC7=YesPlease\n \t\tAC_MSG_RESULT([${asciidoc_version} > 7])\n \t\t;;\n-\tasciidoc' '7*)\n-\t\tASCIIDOC8=\n+\tasciidoc' '8*)\n+\t\tASCIIDOC7=\n \t\tAC_MSG_RESULT([${asciidoc_version}])\n \t\t;;\n \t*)\n-\t\tASCIIDOC8=\n+\t\tASCIIDOC7=\n \t\tAC_MSG_RESULT([${asciidoc_version} (unknown)])\n \t\t;;\n \tesac\n fi\n-AC_SUBST(ASCIIDOC8)\n+AC_SUBST(ASCIIDOC7)\n \n \n ## Checks for libraries.\n-- \n1.7.3.2.510.g24900\n"},{"id":"156198","messageId":"20101119182230.GA26187@burratino","threadId":"25767","inReplyTo":"20101119175424.GA13276@sigill.intra.peff.net","subject":"Re: groff .ft command use in asciidoc","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-11-19T18:22:30Z","receivedAt":"2010-11-19T18:22:30Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Jeff King wrote:\n\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -63,35 +63,28 @@ endif\n[...]\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> +#\t-1.68.1,\tno extra settings are needed?\n> +#\t1.69.0,\t\tset ASCIIDOC_ROFF?\n>  #\t1.69.1-1.71.0,\tset DOCBOOK_SUPPRESS_SP?\n> -#\t1.71.1,\t\tno extra settings are needed?\n> +#\t1.71.1,\t\tset ASCIIDOC_ROFF?\n\nI would like to see these question marks go away.  I believe the\ninitial introduction of ASCIIDOC_NO_ROFF happened conservatively:\ni.e., do not change anything unless this particular toolset\nrequires the change.  Which is a shame, because it means it is not\nobvious what ASCIIDOC_ROFF is working around.\n\n*does some digging*\n\nThe story begins with v1.3.0-rc1~45^2 (Tweak asciidoc to work with\nbroken docbook-xsl, 2006-03-05).  The [listingblock] style, used\nfor listings like:\n\n--------------------\n$ ls\nfoo\nbar\nbaz\n--------------------\n\nis meant to be rendered with the <screen> tag, but apparently DocBook\nXSL 1.68.1 does not and 1.70.1 does treat <screen> as a\nverbatim environment as it should.  See <http://bugs.debian.org/375503>.\nThe patch swapped in another verbatim environment, <literallayout>.\n\nThe result is a regression in another aspect from <screen>: namely,\n<screen> uses monospace text.  v1.5.2.5~6 (Force listingblocks to be\nmonospaced in manpages, 2007-07-18) worked around that by introducing\nsome raw nroff, since this codepath is only used for manpages anyway.\n\nThe rest is history.  docbook-xsl 1.72 broke the traditional method\nfor passing raw roff through.  It had a hole that let you do it some\nother way.  Later versions of docbook-xsl forbid passing through raw\nroff escapes altogether.\n\nGiven all that, I suspect (but haven't checked) that the only knob we\nwould need to cover all historically supported versions of DocBook is\n\n\tDOCBOOK_MESSES_UP_SCREEN_TAG = YesUnfortunately\n\nto be set with docbook versions in the 1.68 series.  Everyone else\ncan use <screen>, with the <literallayout> fixup to add some space\nafter it.\n\n> However, I think it is worth it to avoid the hassle for the vast\n> majority of people on modern systems.\n\nYes!  Your patch takes care of that, so ack.\n\nThanks,\nJonathan\n"},{"id":"156199","messageId":"20101119183753.GA14189@sigill.intra.peff.net","threadId":"25767","inReplyTo":"20101119182230.GA26187@burratino","subject":"Re: groff .ft command use in asciidoc","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-11-19T18:37:53Z","receivedAt":"2010-11-19T18:37:53Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Nov 19, 2010 at 12:22:30PM -0600, Jonathan Nieder wrote:\n\n> Jeff King wrote:\n> \n> > --- a/Documentation/Makefile\n> > +++ b/Documentation/Makefile\n> > @@ -63,35 +63,28 @@ endif\n> [...]\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> > +#\t-1.68.1,\tno extra settings are needed?\n> > +#\t1.69.0,\t\tset ASCIIDOC_ROFF?\n> >  #\t1.69.1-1.71.0,\tset DOCBOOK_SUPPRESS_SP?\n> > -#\t1.71.1,\t\tno extra settings are needed?\n> > +#\t1.71.1,\t\tset ASCIIDOC_ROFF?\n> \n> I would like to see these question marks go away.\n\nI would, too, but not enough to put work into building and testing\nvarious combinations of software that hopefully nobody is using anymore.\n\n> I believe the\n> initial introduction of ASCIIDOC_NO_ROFF happened conservatively:\n> i.e., do not change anything unless this particular toolset\n> requires the change.  Which is a shame, because it means it is not\n> obvious what ASCIIDOC_ROFF is working around.\n\nYeah, the name ASCIIDOC_ROFF is kind of awful. I tried to make this\npatch as dirt-simple as possible: just switch the defaults around (it\nwould be nice if we could simply set ASCIIDOC8=Yes, but because we use\n\"ifdef\" and not \"if\" in the makefile, it has to be a separate variable).\n\nI suspect there could really be some cleanup in this area, and you seem\nto, too...\n\n> Given all that, I suspect (but haven't checked) that the only knob we\n> would need to cover all historically supported versions of DocBook is\n> \n> \tDOCBOOK_MESSES_UP_SCREEN_TAG = YesUnfortunately\n> \n> to be set with docbook versions in the 1.68 series.  Everyone else\n> can use <screen>, with the <literallayout> fixup to add some space\n> after it.\n\nYeah, that would be great and much simpler if it works. I encourage you\nto test it. :)\n\n> > However, I think it is worth it to avoid the hassle for the vast\n> > majority of people on modern systems.\n> \n> Yes!  Your patch takes care of that, so ack.\n\nThanks.\n\n-Peff\n"},{"id":"156206","messageId":"1290198893.13785.68.camel@drew-northup.unet.maine.edu","threadId":"25767","inReplyTo":"20101119175424.GA13276@sigill.intra.peff.net","subject":"Re: groff .ft command use in asciidoc","fromName":"Drew Northup","fromEmail":"drew.northup@maine.edu","sentAt":"2010-11-19T20:34:53Z","receivedAt":"2010-11-19T20:34:53Z","isPatch":false,"sender":{"key":"drew.northup@maine.edu","avatar":"https://avatars.githubusercontent.com/u/18331571?v=4"},"body":"\nOn Fri, 2010-11-19 at 12:54 -0500, Jeff King wrote:\n> On Wed, Nov 17, 2010 at 04:48:29PM +0100, Andi Kleen wrote:\n> \n> > On Wed, Nov 17, 2010 at 09:38:55AM -0500, Jeff King wrote:\n> > > On Wed, Nov 17, 2010 at 04:15:16AM -0600, Jonathan Nieder wrote:\n> > > Andi, I would be curious to hear which asciidoc and docbook-xsl versions\n> > > you are using.\n> > \n> > I see this with the git rpms in opensuse 11.3 which I didn't build.\n> > But presumably it's built with asciidoc 8.4.5-5.1 and 1.75.2-7.1\n> \n> Thanks. I think technically that is a bug in opensuse's packaging, as\n> they are not setting the right knobs for their version. However, I think\n> these days we can make it easier for them. Perhaps it is time to apply\n> this:\n> \n> -- >8 --\n> Subject: [PATCH] docs: default to more modern toolset\n> \n> When the ASCIIDOC8 and ASCIIDOC_NO_ROFF knobs were built,\n> many people were still on asciidoc 7 and using older\n> versions of docbook-xsl. These days, even the almost\n> 2-year-old Debian stable needs these knobs turned.\n> \n> So let's turn them by default. The new knobs ASCIIDOC7 and\n> ASCIIDOC_ROFF can be used to get the old behavior if people\n> are on older systems.\n> \n> Signed-off-by: Jeff King <peff@peff.net>\n> ---\n> These defaults work on Debian stable and further. It sounds like\n> opensuse 11.3, too. I don't know about Fedora, but I suspect they are at\n> least as far along as Debian stable.\n> \n> RHEL5 has asciidoc8, but docbook-xsl 1.69, which means it still needs\n> ASCIIDOC_ROFF enabled. RHEL6 is just out last week. So we are\n> technically breaking at least RHEL5 people (along with anybody with\n> ancient systems) until they tweak their knobs.\n\nOnce I imported the DocBook XML XSL 4.5 files into my local cache it\nseemed to make the man pages just fine on my RHEL5 machine even with the\nposted patch applied.\n\n[root@host ~]# rpm -qi asciidoc\nName        : asciidoc                     Relocations: (not relocatable)\nVersion     : 8.6.3                             Vendor: Dag Apt Repository, http://dag.wieers.com/apt/\nRelease     : 1.el5.rf                      Build Date: Thu 18 Nov 2010 08:35:22 AM EST\n...\n[root@host ~]# rpm -qi docbook-utils\nName        : docbook-utils                Relocations: (not relocatable)\nVersion     : 0.6.14                            Vendor: Red Hat, Inc.\nRelease     : 5.1                           Build Date: Wed 12 Jul 2006 03:55:00 AM EDT\n\nI didn't inspect each and every one for errors, but I didn't see any\nproblems in the ones I did look at.\n\n\n-- \n-Drew Northup N1XIM\n   AKA RvnPhnx on OPN\n________________________________________________\n\"As opposed to vegetable or mineral error?\"\n-John Pescatore, SANS NewsBites Vol. 12 Num. 59\n"},{"id":"156207","messageId":"20101119204010.GA18342@sigill.intra.peff.net","threadId":"25767","inReplyTo":"1290198893.13785.68.camel@drew-northup.unet.maine.edu","subject":"Re: groff .ft command use in asciidoc","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-11-19T20:40:10Z","receivedAt":"2010-11-19T20:40:10Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Nov 19, 2010 at 03:34:53PM -0500, Drew Northup wrote:\n\n> > RHEL5 has asciidoc8, but docbook-xsl 1.69, which means it still needs\n> > ASCIIDOC_ROFF enabled. RHEL6 is just out last week. So we are\n> > technically breaking at least RHEL5 people (along with anybody with\n> > ancient systems) until they tweak their knobs.\n> \n> Once I imported the DocBook XML XSL 4.5 files into my local cache it\n> seemed to make the man pages just fine on my RHEL5 machine even with the\n> posted patch applied.\n> \n> [root@host ~]# rpm -qi asciidoc\n> Name        : asciidoc                     Relocations: (not relocatable)\n> Version     : 8.6.3                             Vendor: Dag Apt Repository, http://dag.wieers.com/apt/\n> Release     : 1.el5.rf                      Build Date: Thu 18 Nov 2010 08:35:22 AM EST\n> ...\n> [root@host ~]# rpm -qi docbook-utils\n> Name        : docbook-utils                Relocations: (not relocatable)\n> Version     : 0.6.14                            Vendor: Red Hat, Inc.\n> Release     : 5.1                           Build Date: Wed 12 Jul 2006 03:55:00 AM EDT\n> \n> I didn't inspect each and every one for errors, but I didn't see any\n> problems in the ones I did look at.\n\nI think the updated XSL files are what's making it work. The stock\ndocbook xsl files are:\n\n  $ yum list | grep docbook-style-xsl\n  docbook-style-xsl.noarch   1.69.1-5.1 rhel-x86_64-server-5\n\nand I don't know that we can assume anyone has updated them. However, I\ndon't actually build git on my RHEL machines, so I could might be wrong.\n\nAll that being said, I am willing to accept RHEL5 as collateral damage\nif the new defaults Just Work for the majority of other platforms.\n\n-Peff\n"},{"id":"156210","messageId":"1290200009.13785.80.camel@drew-northup.unet.maine.edu","threadId":"25767","inReplyTo":"20101119204010.GA18342@sigill.intra.peff.net","subject":"Re: groff .ft command use in asciidoc","fromName":"Drew Northup","fromEmail":"drew.northup@maine.edu","sentAt":"2010-11-19T20:53:29Z","receivedAt":"2010-11-19T20:53:29Z","isPatch":false,"sender":{"key":"drew.northup@maine.edu","avatar":"https://avatars.githubusercontent.com/u/18331571?v=4"},"body":"\nOn Fri, 2010-11-19 at 15:40 -0500, Jeff King wrote:\n> On Fri, Nov 19, 2010 at 03:34:53PM -0500, Drew Northup wrote:\n> \n> > > RHEL5 has asciidoc8, but docbook-xsl 1.69, which means it still needs\n> > > ASCIIDOC_ROFF enabled. RHEL6 is just out last week. So we are\n> > > technically breaking at least RHEL5 people (along with anybody with\n> > > ancient systems) until they tweak their knobs.\n> > \n> > Once I imported the DocBook XML XSL 4.5 files into my local cache it\n> > seemed to make the man pages just fine on my RHEL5 machine even with the\n> > posted patch applied.\n> > \n> > [root@host ~]# rpm -qi asciidoc\n> > Name        : asciidoc                     Relocations: (not relocatable)\n> > Version     : 8.6.3                             Vendor: Dag Apt Repository, http://dag.wieers.com/apt/\n> > Release     : 1.el5.rf                      Build Date: Thu 18 Nov 2010 08:35:22 AM EST\n> > ...\n> > [root@host ~]# rpm -qi docbook-utils\n> > Name        : docbook-utils                Relocations: (not relocatable)\n> > Version     : 0.6.14                            Vendor: Red Hat, Inc.\n> > Release     : 5.1                           Build Date: Wed 12 Jul 2006 03:55:00 AM EDT\n> > \n> > I didn't inspect each and every one for errors, but I didn't see any\n> > problems in the ones I did look at.\n> \n> I think the updated XSL files are what's making it work. The stock\n> docbook xsl files are:\n> \n>   $ yum list | grep docbook-style-xsl\n>   docbook-style-xsl.noarch   1.69.1-5.1 rhel-x86_64-server-5\n\nInterestingly enough, without the updated XSL files it seemed to be\nworking ok, it was just ungodly slow and kicking up a ton of warnings\n(it was trying to fetch them off of the hosting web server at such a\nhigh rate it was being limited out).\n\n> and I don't know that we can assume anyone has updated them. However, I\n> don't actually build git on my RHEL machines, so I could might be wrong.\n> \n> All that being said, I am willing to accept RHEL5 as collateral damage\n> if the new defaults Just Work for the majority of other platforms.\n> \n> -Peff\n\nI don't personally see this as a stopper. After all, asciidoc wasn't a\ndefault install either.\n\n-- \n-Drew Northup N1XIM\n   AKA RvnPhnx on OPN\n________________________________________________\n\"As opposed to vegetable or mineral error?\"\n-John Pescatore, SANS NewsBites Vol. 12 Num. 59\n"},{"id":"156221","messageId":"7v62vsc45d.fsf@alter.siamese.dyndns.org","threadId":"25767","inReplyTo":"20101119204010.GA18342@sigill.intra.peff.net","subject":"Re: groff .ft command use in asciidoc","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-11-19T22:58:06Z","receivedAt":"2010-11-19T22:58:06Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King <peff@peff.net> writes:\n\n> I think the updated XSL files are what's making it work. The stock\n> docbook xsl files are:\n>\n>   $ yum list | grep docbook-style-xsl\n>   docbook-style-xsl.noarch   1.69.1-5.1 rhel-x86_64-server-5\n>\n> and I don't know that we can assume anyone has updated them. However, I\n> don't actually build git on my RHEL machines, so I could might be wrong.\n>\n> All that being said, I am willing to accept RHEL5 as collateral damage\n> if the new defaults Just Work for the majority of other platforms.\n\nThanks.  I usually am fairly cautious when changing the default, but I\nthink this particular one is not such a big deal.  I agree that the end of\nthe year release would probably be a good time to switch.\n\nI think people on RHEL5 would also be ok; they have paid support for this\nkind of thing, no ;-)?\n"},{"id":"156242","messageId":"20101120014808.GZ16929@inocybe.localdomain","threadId":"25767","inReplyTo":"7v62vsc45d.fsf@alter.siamese.dyndns.org","subject":"Re: groff .ft command use in asciidoc","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2010-11-20T01:48:09Z","receivedAt":"2010-11-20T01:48:09Z","isPatch":false,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Junio C Hamano wrote:\n> Thanks.  I usually am fairly cautious when changing the default, but\n> I think this particular one is not such a big deal.  I agree that\n> the end of the year release would probably be a good time to switch.\n>\n> I think people on RHEL5 would also be ok; they have paid support for\n> this kind of thing, no ;-)?\n\nSadly, git isn't in RHEL5 officially.  We package it in EPEL though.\nCurrently, it's at the ancient 1.5.5.6 mile marker.  I have taken care\nto ensure that the Fedora rpm's build cleanly for EPEL-5 (and 4 last I\nchecked), albeit with the lack of emacs support¹.\n\nI haven't tested this patch, but I am confident that removing the\nASCIIDOC knobs where appropriate won't cause us any grief in Fedora,\nEPEL, or RHEL (where git-1.7.x is now officially supported, finally!).  \n\n¹ Incidentally, if anyone here is a strong user of emacs vcs mode and\ncould help work out what we need to do to make git-1.7.x work with the\nemacs-21.4 shipped in RHEL, please let me know.  That's the only\nimpediment (that I know of) keeping us from moving EPEL to a more\nmodern git, with all the fabulous advantages the fine folks here have\nmade since 1.5.x.\n\n-- \nTodd        OpenPGP -> KeyID: 0xBEAF0CE3 | URL: www.pobox.com/~tmz/pgp\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nHappiness, n.: An agreeable sensation arising from contemplating the\nmisery of another.\n    -- Ambrose Bierce, \"The Devil's Dictionary\"\n\n"}]}