{"thread":{"id":"30645","subject":"\"docs: stop using asciidoc no-inline-literal\" breaks asciidoc 8.2.5","startedAt":"2012-05-29T10:19:56Z","lastAt":"2012-05-30T10:22:58Z","messageCount":15,"participants":["Ævar Arnfjörð Bjarmason","Thomas Rast","Junio C Hamano","Jeff King","Dennis Kaarsemaker","Matthieu Moy"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"192410","messageId":"CACBZZX7Y-NTzRP1KYy=eEHTsLHTrzxGms61anXSHVbyCSPgurw@mail.gmail.com","threadId":"30645","inReplyTo":null,"subject":"\"docs: stop using asciidoc no-inline-literal\" breaks asciidoc 8.2.5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2012-05-29T10:19:56Z","receivedAt":"2012-05-29T10:19:56Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Jeff King's 6cf378f0cbe7c7f944637892caeb9058c90a185a broke my Git\nbuild on CentOS 5.5. The patch suggests that it only breaks\ncompatibility with asciidoc 7 but that isn't actually the case.\n\nThe problem is that by using literals we seem to be triggering some\nold bug in asciidoc related to how it balances XML tags, so e.g. for\nthis bit in user-manual.txt:\n\n    - the variable `sha1` in the function signature of `get_sha1()` is `unsigned\n      char *`, but is actually expected to be a pointer to `unsigned\n      char[20]`.  This variable will contain the 160-bit SHA-1 of the given\n      commit.  Note that whenever a SHA-1 is passed as `unsigned char *`, it\n      is the binary representation, as opposed to the ASCII representation in\n      hex characters, which is passed as `char *`.\n\nWe'll produce this XML:\n\n    <simpara>\n    the variable <literal>sha1</literal> in the function signature of\n<literal>get_sha1()</literal> is <literal>unsigned\n      char <emphasis role=\"strong\"></literal>, but is actually\nexpected to be a pointer to <literal>unsigned\n      char[20]</literal>.  This variable will contain the 160-bit\nSHA-1 of the given\n      commit.  Note that whenever a SHA-1 is passed as\n<literal>unsigned char </emphasis></literal>, it\n      is the binary representation, as opposed to the ASCII representation in\n      hex characters, which is passed as <literal>char *</literal>.\n    </simpara>\n\nWhich results in this error:\n\n    user-manual.xml:3743: parser error : Opening and ending tag\nmismatch: emphasis line 3743 and literal\n      char <emphasis role=\"strong\"></literal>, but is actually\nexpected to be a poin\n                                             ^\n    user-manual.xml:3745: parser error : Opening and ending tag\nmismatch: literal line 3745 and emphasis\n    mit.  Note that whenever a SHA-1 is passed as <literal>unsigned\nchar </emphasis>\n\nA patch like this will hack around that:\n\n    diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\n    index 1b94207..0fc8829 100644\n    --- a/Documentation/user-manual.txt\n    +++ b/Documentation/user-manual.txt\n    @@ -4270,9 +4270,9 @@ Two things are interesting here:\n       negative numbers in case of different errors--and 0 on success.\n\n     - the variable `sha1` in the function signature of `get_sha1()`\nis `unsigned\n    -  char *`, but is actually expected to be a pointer to `unsigned\n    +  char {asterisk}`, but is actually expected t\n       char[20]`.  This variable will contain the 160-bit SHA-1 of the given\n    -  commit.  Note that whenever a SHA-1 is passed as `unsigned char *`, it\n    +  commit.  Note that whenever a SHA-1 is passed as `unsigned char\n{asterisk}`, it\n       is the binary representation, as opposed to the ASCII representation in\n       hex characters, which is passed as `char *`.\n\nSo the issue appears to be mostly related to older asciidoc in the 8.*\nline incorrectly handling markup that would generate nested XML tags,\nhere's as far as I got with fixing it:\n\n    $ git --no-pager diff -U0 @{u}..\n    diff --git a/Documentation/config.txt b/Documentation/config.txt\n    index 915cb5a..fd2f939 100644\n    --- a/Documentation/config.txt\n    +++ b/Documentation/config.txt\n    @@ -904 +904 @@ commit.template::\n    -       \"`~/`\" is expanded to the value of `$HOME` and \"`~user/`\" to the\n    +       \"`{tilde}/`\" is expanded to the value of `$HOME` and\n\"`{tilde}user/`\" to the\n    @@ -1664 +1664 @@ pack.indexVersion::\n    -If you have an old git that does not understand the version 2 `*.idx` file,\n    +If you have an old git that does not understand the version 2\n`{asterisk}.idx` file,\n    @@ -1666 +1666 @@ cloning or fetching over a non native protocol\n(e.g. \"http\" and \"rsync\")\n    -that will copy both `*.pack` file and corresponding `*.idx` file from the\n    +that will copy both `{asterisk}.pack` file and corresponding\n`{asterisk}.idx` file from the\n    @@ -1668 +1668 @@ other side may give you a repository that cannot\nbe accessed with your\n    -older version of git. If the `*.pack` file is smaller than 2 GB, however,\n    +older version of git. If the `{asterisk}.pack` file is smaller\nthan 2 GB, however,\n    @@ -1670 +1670 @@ you can use linkgit:git-index-pack[1] on the\n*.pack file to regenerate\n    -the `*.idx` file.\n    +the `{asterisk}.idx` file.\n    @@ -1694 +1694 @@ pretty.<name>::\n    -       running `git config pretty.changelog \"format:* %H %s\"`\n    +       running `git config pretty.changelog \"format:{asterisk} %H %s\"`\n    @@ -1696 +1696 @@ pretty.<name>::\n    -       to be equivalent to running `git log \"--pretty=format:* %H %s\"`.\n    +       to be equivalent to running `git log\n\"--pretty=format:{asterisk} %H %s\"`.\n    diff --git a/Documentation/git-check-ref-format.txt\nb/Documentation/git-check-ref-format.txt\n    index 98009d1..3370565 100644\n    --- a/Documentation/git-check-ref-format.txt\n    +++ b/Documentation/git-check-ref-format.txt\n    @@ -95 +95 @@ OPTIONS\n    -       enabled, <refname> is allowed to contain a single `*`\n    +       enabled, <refname> is allowed to contain a single `{asterisk}`\n    @@ -97 +97 @@ OPTIONS\n    -       `foo/*/bar` but not `foo/bar*`).\n    +       `foo/{asterisk}/bar` but not `foo/bar{asterisk}`).\n    diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\n    index 3bec036..5ae82f3 100644\n    --- a/Documentation/git-grep.txt\n    +++ b/Documentation/git-grep.txt\n    @@ -252 +252 @@ Examples\n    -`git grep 'time_t' -- '*.[ch]'`::\n    +`git grep {apostrophe}time_t{apostrophe} \\--\n{apostrophe}*.[ch]{apostrophe}`::\n    diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\n    index 1b94207..fe86e53 100644\n    --- a/Documentation/user-manual.txt\n    +++ b/Documentation/user-manual.txt\n    @@ -4273 +4273 @@ Two things are interesting here:\n    -  char *`, but is actually expected to be a pointer to `unsigned\n    +  char {asterisk}`, but is actually expected to be a pointer to `unsigned\n    @@ -4275 +4275 @@ Two things are interesting here:\n    -  commit.  Note that whenever a SHA-1 is passed as `unsigned char *`, it\n    +  commit.  Note that whenever a SHA-1 is passed as `unsigned char\n{asterisk}`, it\n    @@ -4277 +4277 @@ Two things are interesting here:\n    -  hex characters, which is passed as `char *`.\n    +  hex characters, which is passed as `char {asterisk}`.\n\nI suggest just ejecting this patch and trying again, these RedHat\nsystems are still used in a lot of environments, especially by various\ncompanies.\n"},{"id":"192413","messageId":"87ehq3mbxg.fsf@thomas.inf.ethz.ch","threadId":"30645","inReplyTo":"CACBZZX7Y-NTzRP1KYy=eEHTsLHTrzxGms61anXSHVbyCSPgurw@mail.gmail.com","subject":"Re: \"docs: stop using asciidoc no-inline-literal\" breaks asciidoc 8.2.5","fromName":"Thomas Rast","fromEmail":"trast@inf.ethz.ch","sentAt":"2012-05-29T12:03:39Z","receivedAt":"2012-05-29T12:03:39Z","isPatch":false,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:\n\n> Jeff King's 6cf378f0cbe7c7f944637892caeb9058c90a185a broke my Git\n> build on CentOS 5.5. The patch suggests that it only breaks\n> compatibility with asciidoc 7 but that isn't actually the case.\n\nThe commit message of 6cf378f0 is not correct in that respect.  My\nancient 71c020c5 has the right numbers: asciidoc 8.4.1 is the one that\nintroduced the new inline-literal behavior.  Based on my little survey\nin\n\n  http://thread.gmane.org/gmane.comp.version-control.git/191738/focus=191790\n\nwe decided that \"nobody\" really uses such an old asciidoc any more.\nEvidently you are a counterexample.\n\n> I suggest just ejecting this patch and trying again, these RedHat\n> systems are still used in a lot of environments, especially by various\n> companies.\n\nDo you/they have to *build* the docs, as opposed to using the prebuilt\nones coming from Junio?  Perhaps we can make it so 'make man' refuses to\nrun if asciidoc is too old, and give a message to the effect that you\nshould 'make quick-install-man' instead.\n\nOtherwise we'll be working around the f{asterisk}{asterisk}{asterisk}ing\nquoting rules for years to come.\n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"},{"id":"192415","messageId":"CACBZZX5iOB5PCZUCX5ksR4hpw+DTLTaP4jOnyHAJ8hZVe9xo5w@mail.gmail.com","threadId":"30645","inReplyTo":"87ehq3mbxg.fsf@thomas.inf.ethz.ch","subject":"Re: \"docs: stop using asciidoc no-inline-literal\" breaks asciidoc 8.2.5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2012-05-29T12:31:38Z","receivedAt":"2012-05-29T12:31:38Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Tue, May 29, 2012 at 2:03 PM, Thomas Rast <trast@inf.ethz.ch> wrote:\n> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:\n>\n>> Jeff King's 6cf378f0cbe7c7f944637892caeb9058c90a185a broke my Git\n>> build on CentOS 5.5. The patch suggests that it only breaks\n>> compatibility with asciidoc 7 but that isn't actually the case.\n>\n> The commit message of 6cf378f0 is not correct in that respect.  My\n> ancient 71c020c5 has the right numbers: asciidoc 8.4.1 is the one that\n> introduced the new inline-literal behavior.  Based on my little survey\n> in\n>\n>  http://thread.gmane.org/gmane.comp.version-control.git/191738/focus=191790\n>\n> we decided that \"nobody\" really uses such an old asciidoc any more.\n> Evidently you are a counterexample.\n\nWell, me and and others using current production RHEL releases:\n\n    $ cat /etc/redhat-release && yum info asciidoc.noarch|grep Version\n    CentOS release 5.5 (Final)\n    Version    : 8.1.0\n    $ cat /etc/redhat-release && yum info asciidoc.noarch|grep Version\n    CentOS release 5.5 (Final)\n    Version    : 8.2.5\n\nI can't quite recall how I ended up with 8.2.5 on one of the boxes,\nbut it seems 8.1.0 may actually be the stock version.\n\n>> I suggest just ejecting this patch and trying again, these RedHat\n>> systems are still used in a lot of environments, especially by various\n>> companies.\n>\n> Do you/they have to *build* the docs, as opposed to using the prebuilt\n> ones coming from Junio?  Perhaps we can make it so 'make man' refuses to\n> run if asciidoc is too old, and give a message to the effect that you\n> should 'make quick-install-man' instead.\n>\n> Otherwise we'll be working around the f{asterisk}{asterisk}{asterisk}ing\n> quoting rules for years to come.\n\nI could personally change my build process to do something else, but\nthe reason I'm running \"all doc\" occasionally on this older toolchain\nis to smoke out issues like these for other users on slightly older\ntoolchains as well.\n\nI think it's too soon to break the stock toolchain on systems as\nrecent as RHEL 5.5 in the name of slightly nicer asciidoc syntax.\n\nWe could also keep the nice syntax and have some simple sed-based\npre-processor that converts the syntax to the older and more widely\nsupported version.\n\nOr we could just decide to break RHEL 5 and systems released at a\nsimilar time, but that isn't what the patch suggested it was doing, so\nwe should probably step back and ponder whether that's something we\nwant to do.\n\nPersonally I think having a hard dependency on a version of a software\npackage released more recently than 2007 (8.2.5 came out on\n2007-11-18) is way too soon, it would be similar to breaking on a GCC\nolder than 4.2.0 which came out around the same time.\n"},{"id":"192431","messageId":"7vzk8q3h5c.fsf@alter.siamese.dyndns.org","threadId":"30645","inReplyTo":"CACBZZX5iOB5PCZUCX5ksR4hpw+DTLTaP4jOnyHAJ8hZVe9xo5w@mail.gmail.com","subject":"Re: \"docs: stop using asciidoc no-inline-literal\" breaks asciidoc 8.2.5","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-05-29T19:45:51Z","receivedAt":"2012-05-29T19:45:51Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:\n\n> I think it's too soon to break the stock toolchain on systems as\n> recent as RHEL 5.5 in the name of slightly nicer asciidoc syntax.\n\nIt is debatable if any version of distribution can be called\n\"recent\" if they ship 5 year old version of software that is updated\nfairly often, though.\n\n> We could also keep the nice syntax and have some simple sed-based\n> pre-processor that converts the syntax to the older and more widely\n> supported version.\n\nNo, let's not go there.  I do not see any reason to believe that\nsuch a sed script would do an equally good or better job as native\nAsciiDoc implementation to deal with inline-literals.  That means we\nwould end up writing our documentation with a subset of newer\nAsciiDoc that the custom sed script can grok---which defeats the\npurpose of the whole exercise.\n\n> Or we could just decide to break RHEL 5 and systems released at a\n> similar time, but that isn't what the patch suggested it was doing, so\n> we should probably step back and ponder whether that's something we\n> want to do.\n\nVery true.  Jeff, how do we want to proceed?  For the upcoming\nrelease, I am inclined to say that we would revert 6cf378f (docs:\nstop using asciidoc no-inline-literal, 2012-04-26).  We would still\nneed to double check the result, though. Documentation updates that\ncame after it are written assuming \"inline-literal\" behaviour, and\nparts we may have \"fixed\" with the commit will format to their old\nrendition.\n"},{"id":"192444","messageId":"20120529215613.GB17598@sigill.intra.peff.net","threadId":"30645","inReplyTo":"CACBZZX5iOB5PCZUCX5ksR4hpw+DTLTaP4jOnyHAJ8hZVe9xo5w@mail.gmail.com","subject":"Re: \"docs: stop using asciidoc no-inline-literal\" breaks asciidoc 8.2.5","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-05-29T21:56:13Z","receivedAt":"2012-05-29T21:56:13Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, May 29, 2012 at 02:31:38PM +0200, Ævar Arnfjörð Bjarmason wrote:\n\n> On Tue, May 29, 2012 at 2:03 PM, Thomas Rast <trast@inf.ethz.ch> wrote:\n> > Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:\n> >\n> >> Jeff King's 6cf378f0cbe7c7f944637892caeb9058c90a185a broke my Git\n> >> build on CentOS 5.5. The patch suggests that it only breaks\n> >> compatibility with asciidoc 7 but that isn't actually the case.\n> >\n> > The commit message of 6cf378f0 is not correct in that respect.  My\n> > ancient 71c020c5 has the right numbers: asciidoc 8.4.1 is the one that\n> > introduced the new inline-literal behavior.  Based on my little survey\n> > in\n\nYeah, sorry, this is my fault. It came up in discussion but I never\namended the commit message. The magic number is definitely 8.4.1.\n\n> Well, me and and others using current production RHEL releases:\n> \n>     $ cat /etc/redhat-release && yum info asciidoc.noarch|grep Version\n>     CentOS release 5.5 (Final)\n>     Version    : 8.1.0\n>     $ cat /etc/redhat-release && yum info asciidoc.noarch|grep Version\n>     CentOS release 5.5 (Final)\n>     Version    : 8.2.5\n> \n> I can't quite recall how I ended up with 8.2.5 on one of the boxes,\n> but it seems 8.1.0 may actually be the stock version.\n\nFrom my searches, there is no stock version in RHEL5 or CentOS 5. They\ndid not start shipping asciidoc until RHEL6, which includes 8.4.5. It's\nvery easy to find 3rd-party RPMs for asciidoc, which is presumably why\nyou have multiple versions. And these days it's easy to find 8.4.5\npackaged for el5.\n\nCan you check your yum sources? I may be wrong that asciidoc was never\npart of the base system, but I can't find it in the RHEL or CentOS\npackage lists, and google searching turns up only 3rd-party versions.\nOf course, it may also have been installed as a one-off, outside of yum,\nor the yum sources changed after it was installed, so your check may\nyield nothing interesting.\n\n> Or we could just decide to break RHEL 5 and systems released at a\n> similar time, but that isn't what the patch suggested it was doing, so\n> we should probably step back and ponder whether that's something we\n> want to do.\n\nIt was not intentional to break RHEL5 in particular, but it was\ndefinitely intentional to stop working with older versions of asciidoc.\nAs I wrote above, I'm not sure that there _is_ an official version of\nasciidoc for RHEL 5.\n\n> Personally I think having a hard dependency on a version of a software\n> package released more recently than 2007 (8.2.5 came out on\n> 2007-11-18) is way too soon, it would be similar to breaking on a GCC\n> older than 4.2.0 which came out around the same time.\n\nI think that's over-simplifying. We can use old versions of gcc (or even\nantique proprietary compilers) because they all accept C89 or some\nreasonable variant, a standard which was mature at the time of their\nwriting. Asciidoc is much less mature, and the no-inline-literal syntax\nsucks, and was the source of a very large number of recurring bugs. We\nhave to balance the pain of supporting the old versions with the pain of\nleaving behind people with no other option.\n\nSo it is not just \"well, this modern syntax is a little nicer\". It is\nfixing real documentation formatting bugs that affect all users (on old\nand modern asciidoc), and closing the hole so that they don't happen\nagain.\n\nAnd unlike compilers, it is relatively easy to work around; because the\nbuild result is architecture independent, Junio can (and does) produce\nbuilt versions which plug into the Makefile.\n\nI'm very sympathetic to having platform support dropped. It's annoying\nfor the user. But given that it's a 3rd-party install anyway (and you\ncan install a newer 3rd-party RPM), and that you can additionally use\n\"make quick-install-man\" to avoid needing asciidoc entirely, and given\nthe sheer number of bugs this patch fixes (and prevents), to me the\nbalance still argues for keeping the patch.\n\nOne thing we could do better at is not silently producing crappy results\n(e.g., by detecting a too-old asciidoc version during the build process,\nand advising the user to upgrade or user quick-install). Or even having\na deprecation period with warning, though I feel that's less important\nfor a build breakage than a run-time change of behavior.\n\n-Peff\n"},{"id":"192445","messageId":"20120529220113.GC17598@sigill.intra.peff.net","threadId":"30645","inReplyTo":"7vzk8q3h5c.fsf@alter.siamese.dyndns.org","subject":"Re: \"docs: stop using asciidoc no-inline-literal\" breaks asciidoc 8.2.5","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-05-29T22:01:13Z","receivedAt":"2012-05-29T22:01:13Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, May 29, 2012 at 12:45:51PM -0700, Junio C Hamano wrote:\n\n> > We could also keep the nice syntax and have some simple sed-based\n> > pre-processor that converts the syntax to the older and more widely\n> > supported version.\n> \n> No, let's not go there.  I do not see any reason to believe that\n> such a sed script would do an equally good or better job as native\n> AsciiDoc implementation to deal with inline-literals.  That means we\n> would end up writing our documentation with a subset of newer\n> AsciiDoc that the custom sed script can grok---which defeats the\n> purpose of the whole exercise.\n\nVery much agreed; that way lies madness.\n\n> > Or we could just decide to break RHEL 5 and systems released at a\n> > similar time, but that isn't what the patch suggested it was doing, so\n> > we should probably step back and ponder whether that's something we\n> > want to do.\n> \n> Very true.  Jeff, how do we want to proceed?  For the upcoming\n> release, I am inclined to say that we would revert 6cf378f (docs:\n> stop using asciidoc no-inline-literal, 2012-04-26).  We would still\n> need to double check the result, though. Documentation updates that\n> came after it are written assuming \"inline-literal\" behaviour, and\n> parts we may have \"fixed\" with the commit will format to their old\n> rendition.\n\nI'd really rather keep it; I won't repeat my arguments here, but I made\nseveral in a reply to Ævar elsewhere in the thread. However, if we do\nrevert it, then it would be really great if somebody comes up with\nalternate solutions to fix the long list of bugs that were fixed by\n6cf378f (they are all documented in the commit message). And it would be\neven greater if that somebody isn't me.\n\nI think it would also be worth figuring out when a switch would be\nappropriate.  Moving to inline literals is obviously the way forward\n(it's way less error-prone, and eventually asciidoc may deprecate or\ndrop the backwards compatibility feature themselves). So it is simply a\nmatter of time in deciding when. If not now, then when?\n\n-Peff\n"},{"id":"192446","messageId":"1338329100.2621.3.camel@localhost","threadId":"30645","inReplyTo":"20120529215613.GB17598@sigill.intra.peff.net","subject":"Re: \"docs: stop using asciidoc no-inline-literal\" breaks asciidoc 8.2.5","fromName":"Dennis Kaarsemaker","fromEmail":"dennis@kaarsemaker.net","sentAt":"2012-05-29T22:05:00Z","receivedAt":"2012-05-29T22:05:00Z","isPatch":false,"sender":{"key":"dennis@kaarsemaker.net","avatar":"https://avatars.githubusercontent.com/u/200649?v=4"},"body":"On di, 2012-05-29 at 17:56 -0400, Jeff King wrote:\n> \n> From my searches, there is no stock version in RHEL5 or CentOS 5. They\n> did not start shipping asciidoc until RHEL6, which includes 8.4.5. It's\n> very easy to find 3rd-party RPMs for asciidoc, which is presumably why\n> you have multiple versions. And these days it's easy to find 8.4.5\n> packaged for el5. \n\nepel (pretty much the default 2½th party repo, maintained by the fedora\npeople) ships asciidoc for rhel5/centos5, but not anything newer than\n8.1.x \n\n-- \nDennis K.\n\nLife is what happens to you while you're busy making other plans \n  - John Lennon\n"},{"id":"192447","messageId":"CACBZZX6a2BQVhe8-X5o+WnfbsrqPKa_Cn93GZ1bbq1TLezB97Q@mail.gmail.com","threadId":"30645","inReplyTo":"20120529215613.GB17598@sigill.intra.peff.net","subject":"Re: \"docs: stop using asciidoc no-inline-literal\" breaks asciidoc 8.2.5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2012-05-29T22:42:32Z","receivedAt":"2012-05-29T22:42:32Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Tue, May 29, 2012 at 11:56 PM, Jeff King <peff@peff.net> wrote:\n\n> I'm very sympathetic to having platform support dropped. It's annoying\n> for the user. But given that it's a 3rd-party install anyway (and you\n> can install a newer 3rd-party RPM), and that you can additionally use\n> \"make quick-install-man\" to avoid needing asciidoc entirely, and given\n> the sheer number of bugs this patch fixes (and prevents), to me the\n> balance still argues for keeping the patch.\n\nTo be clear I like the patch, I was just suggesting that we might want\nto hold it off for a bit.\n\nAnyway, I've tested dropping asciidoc.py from the source distribution\ninto compat/asciidoc.py and doing \"make doc\nASCIIDOC=../compat/asciidoc.py\", it seems to work.\n\nI wonder if the easiest solution is to change the default asciidoc\ninvocation from \"asciidoc\" to a small Documentation/asciidoc.sh script\nthat we supply, it would check if there's an asciidoc present on the\nsystem, whether it's sufficiently new, and if not fall back on a copy\nwe have in compat/.\n"},{"id":"192448","messageId":"CACBZZX7qg50su6Yhbk1HEY9wJgzr=vM_NZfDDMDGQ3sRkLqyAQ@mail.gmail.com","threadId":"30645","inReplyTo":"CACBZZX6a2BQVhe8-X5o+WnfbsrqPKa_Cn93GZ1bbq1TLezB97Q@mail.gmail.com","subject":"Re: \"docs: stop using asciidoc no-inline-literal\" breaks asciidoc 8.2.5","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2012-05-29T22:51:08Z","receivedAt":"2012-05-29T22:51:08Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Wed, May 30, 2012 at 12:42 AM, Ævar Arnfjörð Bjarmason\n<avarab@gmail.com> wrote:\n> On Tue, May 29, 2012 at 11:56 PM, Jeff King <peff@peff.net> wrote:\n>\n>> I'm very sympathetic to having platform support dropped. It's annoying\n>> for the user. But given that it's a 3rd-party install anyway (and you\n>> can install a newer 3rd-party RPM), and that you can additionally use\n>> \"make quick-install-man\" to avoid needing asciidoc entirely, and given\n>> the sheer number of bugs this patch fixes (and prevents), to me the\n>> balance still argues for keeping the patch.\n>\n> To be clear I like the patch, I was just suggesting that we might want\n> to hold it off for a bit.\n>\n> Anyway, I've tested dropping asciidoc.py from the source distribution\n> into compat/asciidoc.py and doing \"make doc\n> ASCIIDOC=../compat/asciidoc.py\", it seems to work.\n>\n> I wonder if the easiest solution is to change the default asciidoc\n> invocation from \"asciidoc\" to a small Documentation/asciidoc.sh script\n> that we supply, it would check if there's an asciidoc present on the\n> system, whether it's sufficiently new, and if not fall back on a copy\n> we have in compat/.\n\nSomething like this silly patch, which seems to work, but needs cleanup:\n\n    https://github.com/avar/git/compare/git:master...avar/asciidoc-fallback\n"},{"id":"192460","messageId":"20120530085111.GA9917@sigill.intra.peff.net","threadId":"30645","inReplyTo":"CACBZZX6a2BQVhe8-X5o+WnfbsrqPKa_Cn93GZ1bbq1TLezB97Q@mail.gmail.com","subject":"Re: \"docs: stop using asciidoc no-inline-literal\" breaks asciidoc 8.2.5","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-05-30T08:51:12Z","receivedAt":"2012-05-30T08:51:12Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, May 30, 2012 at 12:42:32AM +0200, Ævar Arnfjörð Bjarmason wrote:\n\n> Anyway, I've tested dropping asciidoc.py from the source distribution\n> into compat/asciidoc.py and doing \"make doc\n> ASCIIDOC=../compat/asciidoc.py\", it seems to work.\n> \n> I wonder if the easiest solution is to change the default asciidoc\n> invocation from \"asciidoc\" to a small Documentation/asciidoc.sh script\n> that we supply, it would check if there's an asciidoc present on the\n> system, whether it's sufficiently new, and if not fall back on a copy\n> we have in compat/.\n\nThat makes me somewhat nervous. The asciidoc package on my system\ncontains 311 files. It seems probable that at least one of those files\nbeyond asciidoc.py is necessary for the system to work, and that it may\neven depend on matching versions.\n\nIf we are going to go the route of providing an asciidoc for people\nwhose asciidoc is buggy, we might as well go all out and provide a\ncomplete standalone asciidoc (or at least some subset) for those who\ndon't have it at all. Part of me finds that utterly gross, but part of\nme likes the fact that we would be able to move our documentation and\nour asciidoc interpreter in lockstep, which avoids some other bugs we\nhave seen in the past.  Of course, that doesn't help the rest of the\ndocumentation toolchain (differing docbook versions have created\nproblems in the past, too).\n\nI suppose the grossness would depend on how small a minimal asciidoc\ndistribution could be made (of those 311 files, many are documentation\nand examples).\n\n-Peff\n"},{"id":"192461","messageId":"vpqipfeujmz.fsf@bauges.imag.fr","threadId":"30645","inReplyTo":"20120530085111.GA9917@sigill.intra.peff.net","subject":"Re: \"docs: stop using asciidoc no-inline-literal\" breaks asciidoc 8.2.5","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2012-05-30T09:02:12Z","receivedAt":"2012-05-30T09:02:12Z","isPatch":false,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Jeff King <peff@peff.net> writes:\n\n> If we are going to go the route of providing an asciidoc for people\n> whose asciidoc is buggy, we might as well go all out and provide a\n> complete standalone asciidoc (or at least some subset) for those who\n> don't have it at all.\n\nPerhaps a \"make install-asciidoc\" target that does the\nwget && make && make DESTDIR=contrib/ install\n(or whatever asciidoc needs to be installed)?\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"192464","messageId":"20120530101758.GA13285@sigill.intra.peff.net","threadId":"30645","inReplyTo":"20120529215613.GB17598@sigill.intra.peff.net","subject":"[PATCH 0/3] docs: asciidoc version tweaks","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-05-30T10:17:58Z","receivedAt":"2012-05-30T10:17:58Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, May 29, 2012 at 05:56:13PM -0400, Jeff King wrote:\n\n> > > The commit message of 6cf378f0 is not correct in that respect.  My\n> > > ancient 71c020c5 has the right numbers: asciidoc 8.4.1 is the one that\n> > > introduced the new inline-literal behavior.  Based on my little survey\n> > > in\n> \n> Yeah, sorry, this is my fault. It came up in discussion but I never\n> amended the commit message. The magic number is definitely 8.4.1.\n\nI think 6cf378f0 left a few other loose ends, too. Fixes to follow.\n\n  [1/3]: INSTALL: update asciidoc recommendation\n  [2/3]: docs: drop asciidoc7compatible flag\n  [3/3]: docs: drop antique comment from Makefile\n\n-Peff\n"},{"id":"192465","messageId":"20120530101829.GA13341@sigill.intra.peff.net","threadId":"30645","inReplyTo":"20120530101758.GA13285@sigill.intra.peff.net","subject":"[PATCH 1/3] INSTALL: update asciidoc recommendation","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-05-30T10:18:29Z","receivedAt":"2012-05-30T10:18:29Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"Since commit 6cf378f (docs: stop using asciidoc no-inline-literal),\nwe no longer support asciidoc versions less than 8.4.1,\nwhich introduced inline literals. Note this in the INSTALL\ndocument.\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\n INSTALL | 6 ++----\n 1 file changed, 2 insertions(+), 4 deletions(-)\n\ndiff --git a/INSTALL b/INSTALL\nindex 87e03bb..28f34bd 100644\n--- a/INSTALL\n+++ b/INSTALL\n@@ -161,11 +161,9 @@ Issues of note:\n    makeinfo and docbook2X.  Version 0.8.3 is known to work.\n \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+   dblatex.  Version >= 0.2.7 is known to work.\n \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+   All formats require at least asciidoc 8.4.1.\n \n    There are also \"make quick-install-doc\", \"make quick-install-man\"\n    and \"make quick-install-html\" which install preformatted man pages\n-- \n1.7.11.rc0.12.g6048c92\n"},{"id":"192466","messageId":"20120530102242.GB13341@sigill.intra.peff.net","threadId":"30645","inReplyTo":"20120530101758.GA13285@sigill.intra.peff.net","subject":"[PATCH 2/3] docs: drop asciidoc7compatible flag","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-05-30T10:22:42Z","receivedAt":"2012-05-30T10:22:42Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"When we made the switch to supporting asciidoc 8 in 4c7100a\n(Documentation: adjust to AsciiDoc 8, 2007-06-14), we were\nable to leave most of the documentation intact by defining\nasciidoc7compatible.\n\nSince commit 6cf378f (docs: stop using asciidoc no-inline-literal,\n2012-04-26), we don't support versions of asciidoc older\nthan 8.4.1, which is when inline literals were introduced.\nTherefore there is not much point in keeping our\ndocumentation compatible with asciidoc 7.\n\nSo we are now free to drop the asciidoc7compatible flag and\nupdate the documentation itself to assume asciidoc8.\nFortunately, doing the latter is very easy; we weren't using\nany of the constructs impacted by asciidoc7compatible, so\nthere are no changes to make.\n\nThe reason is somewhat subtle. The asciidoc7compatible\naffects only super/sub-scripts (\"^\" and \"~\") and index\nterms. We don't use the latter at all. Nor we do we use the\nformer, but we did have to protect them from accidental\nexpansion in constructs like \"rev^1\". However, all of our\nuses of \"~\" and \"^\" are either in code blocks (which are\nrendered literally), or inside backticks. Prior to 6cf378f,\nbackticks were not inline literals, and needed proper\nquoting. But post-6cf378f, we don't have to worry whether we\nare using the old or new rules, as those characters are not\ninterpreted at all in either case.\n\nI verified that the result of \"make install-html\ninstall-man\" is identical before and after this patch on\nasciidoc 8.6.7.\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\nIt's possible that other recent versions of asciidoc might not generate\nidentical output, or that asciidoc7compatible might change in the future\nto include some as-yet-undiscovered incompatibility (though I find that\nunlikely, as it has been several years now). But in that case, I think\nthis is still the right thing to do, and we should update to the proper\nasciidoc8 syntax.\n\nI tweaked the configure.ac to stop setting ASCIIDOC7, since it no longer\ndoes anything. I believe this makes the whole version check a no-op,\nexcept for the message that is printed. It might be worth actually\nchecking for asciidoc >= 8.4.1 in the configure script, but I will leave\nthat to the folks who care about autoconf (apparently there is a\ndotted-version comparison function, but it was only in autoconf 2.53 or\nhigher, and I have no idea what we consider recent enough autoconf).\n\n Documentation/Makefile | 9 ---------\n Makefile               | 6 ------\n config.mak.in          | 1 -\n configure.ac           | 7 -------\n 4 files changed, 23 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 14286cb..030e2c8 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -66,12 +66,6 @@ endif\n -include ../config.mak\n \n #\n-# For asciidoc ...\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,\tno extra settings are needed?\n #\t1.69.0,\t\tset ASCIIDOC_ROFF?\n@@ -81,9 +75,6 @@ endif\n #\t1.73.0-,\tno extra settings are needed\n #\n \n-ifndef ASCIIDOC7\n-ASCIIDOC_EXTRA += -a asciidoc7compatible\n-endif\n ifdef DOCBOOK_XSL_172\n ASCIIDOC_EXTRA += -a git-asciidoc-no-roff\n MANPAGE_XSL = manpage-1.72.xsl\ndiff --git a/Makefile b/Makefile\nindex 96ebcf9..55943a9 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -203,8 +203,6 @@ 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 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@@ -1834,10 +1832,6 @@ ifndef V\n endif\n endif\n \n-ifdef ASCIIDOC7\n-\texport ASCIIDOC7\n-endif\n-\n ifdef NO_INSTALL_HARDLINKS\n \texport NO_INSTALL_HARDLINKS\n endif\ndiff --git a/config.mak.in b/config.mak.in\nindex b2ba710..802d342 100644\n--- a/config.mak.in\n+++ b/config.mak.in\n@@ -28,7 +28,6 @@ VPATH = @srcdir@\n export exec_prefix mandir\n export srcdir VPATH\n \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 e125550..4e9012f 100644\n--- a/configure.ac\n+++ b/configure.ac\n@@ -437,21 +437,14 @@ 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' '7*)\n-\t\tASCIIDOC7=YesPlease\n-\t\tAC_MSG_RESULT([${asciidoc_version} > 7])\n-\t\t;;\n \tasciidoc' '8*)\n-\t\tASCIIDOC7=\n \t\tAC_MSG_RESULT([${asciidoc_version}])\n \t\t;;\n \t*)\n-\t\tASCIIDOC7=\n \t\tAC_MSG_RESULT([${asciidoc_version} (unknown)])\n \t\t;;\n \tesac\n fi\n-AC_SUBST(ASCIIDOC7)\n \n \n ## Checks for libraries.\n-- \n1.7.11.rc0.12.g6048c92\n"},{"id":"192467","messageId":"20120530102258.GC13341@sigill.intra.peff.net","threadId":"30645","inReplyTo":"20120530101758.GA13285@sigill.intra.peff.net","subject":"[PATCH 3/3] docs: drop antique comment from Makefile","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-05-30T10:22:58Z","receivedAt":"2012-05-30T10:22:58Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"This comment warns about a bug in asciidoc 6, and points to\na patch from 2005. Since we don't even support versions of\nasciidoc that old, we can safely get rid of the warning.\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\n Documentation/Makefile | 9 ---------\n 1 file changed, 9 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 030e2c8..eb1b6ad 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -125,15 +125,6 @@ DEFAULT_EDITOR_SQ = $(subst ','\\'',$(DEFAULT_EDITOR))\n ASCIIDOC_EXTRA += -a 'git-default-editor=$(DEFAULT_EDITOR_SQ)'\n endif\n \n-#\n-# Please note that there is a minor bug in asciidoc.\n-# The version after 6.0.3 _will_ include the patch found here:\n-#   http://marc.theaimsgroup.com/?l=git&m=111558757202243&w=2\n-#\n-# Until that version is released you may have to apply the patch\n-# yourself - yes, all 6 characters of it!\n-#\n-\n QUIET_SUBDIR0  = +$(MAKE) -C # space to separate -C and subdir\n QUIET_SUBDIR1  =\n \n-- \n1.7.11.rc0.12.g6048c92\n"}]}