{"thread":{"id":"8456","subject":"[PATCH] Documentation typo.","startedAt":"2007-06-05T22:25:56Z","lastAt":"2007-06-16T21:05:11Z","messageCount":9,"participants":["Pierre Habouzit","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"44107","messageId":"11810823561507-git-send-email-madcoder@debian.org","threadId":"8456","inReplyTo":null,"subject":"[PATCH] Documentation typo.","fromName":"Pierre Habouzit","fromEmail":"madcoder@debian.org","sentAt":"2007-06-05T22:25:56Z","receivedAt":"2007-06-05T22:25:56Z","isPatch":true,"sender":{"key":"madcoder@debian.org","avatar":"https://avatars.githubusercontent.com/u/44708?v=4"},"body":"From: Pierre Habouzit \n\nSigned-off-by: Pierre Habouzit \n---\n Documentation/pull-fetch-param.txt | 2 +-\n 1 files changed, 1 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt\nindex 8d4e950..5bcdbc8 100644\n--- a/Documentation/pull-fetch-param.txt\n+++ b/Documentation/pull-fetch-param.txt\n@@ -4,7 +4,7 @@\n \n ::\n \tThe canonical format of a parameter is\n-\t`+?:`; that is, an optional plus `+`, followed\n+\t`\\+?:`; that is, an optional plus `+`, followed\n \tby the source ref, followed by a colon `:`, followed by\n \tthe destination ref.\n +\n-- \n1.5.2.1\n"},{"id":"44190","messageId":"7v4plkzsuj.fsf@assigned-by-dhcp.cox.net","threadId":"8456","inReplyTo":"11810823561507-git-send-email-madcoder@debian.org","subject":"Re: [PATCH] Documentation typo.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-06-06T21:16:36Z","receivedAt":"2007-06-06T21:16:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Pierre Habouzit writes:\n\n> From: Pierre Habouzit \n>\n> Signed-off-by: Pierre Habouzit \n> ---\n> Documentation/pull-fetch-param.txt | 2 +-\n> 1 files changed, 1 insertions(+), 1 deletions(-)\n>\n> diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt\n> index 8d4e950..5bcdbc8 100644\n> --- a/Documentation/pull-fetch-param.txt\n> +++ b/Documentation/pull-fetch-param.txt\n> @@ -4,7 +4,7 @@\n> \n> ::\n> \tThe canonical format of a parameter is\n> -\t`+?:`; that is, an optional plus `+`, followed\n> +\t`\\+?:`; that is, an optional plus `+`, followed\n> \tby the source ref, followed by a colon `:`, followed by\n> \tthe destination ref.\n> +\n\nNot really. I suspect you are using AsciiDoc 8?\n\nYour patch does make AsciiDoc 8 keep '+' in the HTML output, but\nmanual page output gets an extra backslash, so it is not really\nan improvement.\n\nUnfortunately our documentation pages were written with AsciiDoc\n7, and are not AsciiDoc 8 compatible.\n\nWith -aasciidoc7compatible, AsciiDoc 8 is _supposed_ to behave\ncompatibly, but in reality it does not format our documentation\ncorrectly. It certainly is possible that AsciiDoc 7 \"happens to\nwork\" with our documentation pages, and maybe the way we abuse\nmark-ups can be argued the bug in _our_ documentation, but\nnobody on our end worked on finding a satisfactory solution to\nmake our documentation format correctly with _both_ versions of\nAsciiDoc yet.\n\nI wrote about the differences between AsciiDoc 7, and AsciiDoc 8\nwith the \"compatiblity\" I found a few weeks ago on this list;\nthe most problematic was that 'asciidoc -aasciidoc7compatible'\nloses carets in our description where they matter X-<. The list\narchive may know more about the details,\n"},{"id":"44202","messageId":"20070606221806.GA23830@artemis","threadId":"8456","inReplyTo":"7v4plkzsuj.fsf@assigned-by-dhcp.cox.net","subject":"Re: [PATCH] Documentation typo.","fromName":"Pierre Habouzit","fromEmail":"madcoder@debian.org","sentAt":"2007-06-06T22:18:06Z","receivedAt":"2007-06-06T22:18:06Z","isPatch":true,"sender":{"key":"madcoder@debian.org","avatar":"https://avatars.githubusercontent.com/u/44708?v=4"},"body":"On Wed, Jun 06, 2007 at 02:16:36PM -0700, Junio C Hamano wrote:\n> Pierre Habouzit writes:\n> \n> > From: Pierre Habouzit \n> >\n> > Signed-off-by: Pierre Habouzit \n> > ---\n> > Documentation/pull-fetch-param.txt | 2 +-\n> > 1 files changed, 1 insertions(+), 1 deletions(-)\n> >\n> > diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt\n> > index 8d4e950..5bcdbc8 100644\n> > --- a/Documentation/pull-fetch-param.txt\n> > +++ b/Documentation/pull-fetch-param.txt\n> > @@ -4,7 +4,7 @@\n> > \n> > ::\n> > \tThe canonical format of a parameter is\n> > -\t`+?:`; that is, an optional plus `+`, followed\n> > +\t`\\+?:`; that is, an optional plus `+`, followed\n> > \tby the source ref, followed by a colon `:`, followed by\n> > \tthe destination ref.\n> > +\n> \n> Not really. I suspect you are using AsciiDoc 8?\n\n indeed ...\n\n> Your patch does make AsciiDoc 8 keep '+' in the HTML output, but\n> manual page output gets an extra backslash, so it is not really\n> an improvement.\n\n Not for me, using asciidoc 8.2.1 on debian. It was because the manpage\nwas missing a '+' that I actually wrote this patch, as it was really\nakward.\n\n> Unfortunately our documentation pages were written with AsciiDoc\n> 7, and are not AsciiDoc 8 compatible.\n> \n> With -aasciidoc7compatible, AsciiDoc 8 is _supposed_ to behave\n> compatibly, but in reality it does not format our documentation\n> correctly. It certainly is possible that AsciiDoc 7 \"happens to\n> work\" with our documentation pages, and maybe the way we abuse\n> mark-ups can be argued the bug in _our_ documentation, but\n> nobody on our end worked on finding a satisfactory solution to\n> make our documentation format correctly with _both_ versions of\n> AsciiDoc yet.\n> \n> I wrote about the differences between AsciiDoc 7, and AsciiDoc 8\n> with the \"compatiblity\" I found a few weeks ago on this list;\n> the most problematic was that 'asciidoc -aasciidoc7compatible'\n> loses carets in our description where they matter X-<. The list\n> archive may know more about the details,\n\n Okay, I see, sorry for the noise then.\n\n-- \n·O· Pierre Habouzit\n··O madcoder@debian.org\nOOO http://www.madism.org\n"},{"id":"44215","messageId":"7vzm3csegw.fsf@assigned-by-dhcp.cox.net","threadId":"8456","inReplyTo":"20070606221806.GA23830@artemis","subject":"Re: [PATCH] Documentation typo.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-06-07T02:09:03Z","receivedAt":"2007-06-07T02:09:03Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Pierre Habouzit writes:\n\n>> Unfortunately our documentation pages were written with AsciiDoc\n>> 7, and are not AsciiDoc 8 compatible.\n>> \n>> With -aasciidoc7compatible, AsciiDoc 8 is _supposed_ to behave\n>> compatibly, but in reality it does not format our documentation\n>> correctly. It certainly is possible that AsciiDoc 7 \"happens to\n>> work\" with our documentation pages, and maybe the way we abuse\n>> mark-ups can be argued the bug in _our_ documentation, but\n>> nobody on our end worked on finding a satisfactory solution to\n>> make our documentation format correctly with _both_ versions of\n>> AsciiDoc yet.\n>> ...\n>\n> Okay, I see, sorry for the noise then.\n\nWell, it was NOT a noise. Making the docs usable with both 7\nand 8 is a task waiting for a volunteer ;-).\n"},{"id":"45119","messageId":"7vfy4t915f.fsf@assigned-by-dhcp.pobox.com","threadId":"8456","inReplyTo":"11810823561507-git-send-email-madcoder@debian.org","subject":"[RFT] Format our Documentation/ with both AsciiDoc 7 & 8","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-06-15T06:34:20Z","receivedAt":"2007-06-15T06:34:20Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"It turns out that the attribute definition we have had for a\nlong time to hide \"^\" character from AsciiDoc 7 was not honored\nby AsciiDoc 8 even under \"-a asciidoc7compatible\" mode.\n\nAlso the double colon at the end of definition list term needs\nto be attached to the term, without a whitespace. After this\nminimum fixups, AsciiDoc 8 (I used 8.2.1 on Debian) with\ncompatibility mode seems to produce reasonably good results.\n\nSigned-off-by: Junio C Hamano \n---\n\n * This is \"Request for Test\" to people who reported problems\n formatting our documentation with asciidoc 8. To format with\n Asciidoc 8, you would need to say something like:\n\n\t$ make ASCIIDOC8=YesPlease doc\n\n I've compared the output generated with AsciiDoc 7.1.2\n without this patch, and generated with AscooDoc 7.1.2 and\n AsciiDoc 8.2.1 with this patch. Aside from the expected\n obvious differences in:\n\n - embedded Git version string in manpage output\n - generation datestamp in HTML output\n - autogenerated anchor href=\"#id\" and name=\"id\" in HTML output\n\n the only differences I saw are:\n\n - _word_ is rendered in HTML as word in AsciiDoc 8,\n while it used to come out verbatim under AsciiDoc 7. Nice.\n\n - HTML stylesheet is a bit different from AsciiDoc 8.\n Presumably an improvement.\n\n Documentation/Makefile | 3 +++\n Documentation/asciidoc.conf | 2 +-\n Documentation/git-cvsexportcommit.txt | 2 +-\n Makefile | 6 ++++++\n 4 files changed, 11 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 9cef480..4edf788 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -37,6 +37,9 @@ man7dir=$(mandir)/man7\n \n ASCIIDOC=asciidoc\n ASCIIDOC_EXTRA =\n+ifdef ASCIIDOC8\n+ASCIIDOC_EXTRA += -a asciidoc7compatible\n+endif\n INSTALL?=install\n DOC_REF = origin/man\n \ndiff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf\nindex 99302c5..c135b6e 100644\n--- a/Documentation/asciidoc.conf\n+++ b/Documentation/asciidoc.conf\n@@ -8,7 +8,7 @@\n # the command.\n \n [attributes]\n-caret=^\n+caret=^\n startsb=[\n endsb=]\n tilde=~\ndiff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt\nindex 827711c..6c423e3 100644\n--- a/Documentation/git-cvsexportcommit.txt\n+++ b/Documentation/git-cvsexportcommit.txt\n@@ -76,7 +76,7 @@ $ git-cvsexportcommit -v \n $ cvs commit -F .mgs \n ------------\n \n-Merge pending patches into CVS automatically -- only if you really know what you are doing ::\n+Merge pending patches into CVS automatically -- only if you really know what you are doing::\n +\n ------------\n $ export GIT_DIR=~/project/.git\ndiff --git a/Makefile b/Makefile\nindex a70277b..d3b70d2 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -107,6 +107,8 @@ all::\n # Define USE_STDEV below if you want git to care about the underlying device\n # change being considered an inode change from the update-cache perspective.\n #\n+# Define ASCIIDOC8 if you want to format documentation with AsciiDoc 8\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@@ -684,6 +686,10 @@ ifndef V\n endif\n endif\n \n+ifdef ASCIIDOC8\n+\texport ASCIIDOC8\n+endif\n+\n # Shell quote (do not use $(call) to accommodate ancient setups);\n \n SHA1_HEADER_SQ = $(subst ','\\'',$(SHA1_HEADER))\n-- \n1.5.2.1.280.g38570\n"},{"id":"45124","messageId":"20070615080935.GB28554@artemis.intersec.eu","threadId":"8456","inReplyTo":"7vfy4t915f.fsf@assigned-by-dhcp.pobox.com","subject":"Re: [RFT] Format our Documentation/ with both AsciiDoc 7 & 8","fromName":"Pierre Habouzit","fromEmail":"madcoder@debian.org","sentAt":"2007-06-15T08:09:35Z","receivedAt":"2007-06-15T08:09:35Z","isPatch":false,"sender":{"key":"madcoder@debian.org","avatar":"https://avatars.githubusercontent.com/u/44708?v=4"},"body":"On Thu, Jun 14, 2007 at 11:34:20PM -0700, Junio C Hamano wrote:\n> It turns out that the attribute definition we have had for a\n> long time to hide \"^\" character from AsciiDoc 7 was not honored\n> by AsciiDoc 8 even under \"-a asciidoc7compatible\" mode.\n> \n> Also the double colon at the end of definition list term needs\n> to be attached to the term, without a whitespace. After this\n> minimum fixups, AsciiDoc 8 (I used 8.2.1 on Debian) with\n> compatibility mode seems to produce reasonably good results.\n> \n> Signed-off-by: Junio C Hamano \n> ---\n> \n> * This is \"Request for Test\" to people who reported problems\n> formatting our documentation with asciidoc 8. To format with\n> Asciidoc 8, you would need to say something like:\n> \n> \t$ make ASCIIDOC8=YesPlease doc\n\n sadly, it does not fixes the issue I reported with git-pull.1 (e.g.)\nthat reads:\n\n \n The canonical format of a parameter is ?:; that\n\nwhereas it should be:\n\n \n The canonical format of a parameter is +?:; that\n\n\nBut I've not seen any serious or even noticeable regression here.\n-- \n·O· Pierre Habouzit\n··O madcoder@debian.org\nOOO http://www.madism.org\n"},{"id":"45153","messageId":"7vy7ik7rvq.fsf@assigned-by-dhcp.pobox.com","threadId":"8456","inReplyTo":"20070615080935.GB28554@artemis.intersec.eu","subject":"Re: [RFT] Format our Documentation/ with both AsciiDoc 7 & 8","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-06-15T22:52:09Z","receivedAt":"2007-06-15T22:52:09Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Pierre Habouzit writes:\n\n> sadly, it does not fixes the issue I reported with git-pull.1 (e.g.)\n> that reads:\n>\n> \n> The canonical format of a parameter is ?:; that\n>\n> whereas it should be:\n>\n> \n> The canonical format of a parameter is +?:; that\n\nThat is very unexpected, especially as your e-mail address is in\ndebian.org.\n\n * My local test and build usually is done with AsciiDoc 7.1.2\n that is shipped with Debian, without any local modifications.\n The part you quoted is formatted like this (I indented for\n e-mail inclusion and line-wrapped below):\n\n .PP\n \n .RS 3n\n\n The canonical format of a parameter is +?:;\n that is, an optional plus +, followed by the source ref,\n followed by a colon :, followed by the destination ref.\n\n This is the same with or without the patch we are\n discussing.\n\n * I updated my notebook that runs Debian with AsciiDoc 8.2.1\n and tested with the patch. The formatted result matches the\n above.\n\n * I tried the above with a hand-installed AsciiDoc 8.2.1 from\n the tarball distribution. Again, the formatted result of the\n quoted part matches.\n\n * The preformatted manual pages on man branch in git.git are\n generated on a k.org machine that runs AsciiDoc 7.0.2 on\n FC5. The version before the patch is formatted like this:\n\n .TP\n \n The canonical format of a parameter is +?:;\n that is, an optional plus +, followed by the source ref,\n followed by a colon :, followed by the destination ref.\n\n I haven't had a chance to test how it comes out with the\n patch, but because the only difference under AsciiDoc 7 is\n the definition of {caret} macro, I do not expect any change\n in the quoted area.\n\nIn other words, there is no breakage like you are observing in\nthe original (nor updated) version with any of the platforms and\nAsciiDoc versions I had handy to test. There is something\ndifferent with the version of AsciiDoc you are using, but I\ncannot tell what that is.\n"},{"id":"45160","messageId":"20070616084939.GA9118@artemis","threadId":"8456","inReplyTo":"7vy7ik7rvq.fsf@assigned-by-dhcp.pobox.com","subject":"Re: [RFT] Format our Documentation/ with both AsciiDoc 7 & 8","fromName":"Pierre Habouzit","fromEmail":"madcoder@debian.org","sentAt":"2007-06-16T08:49:39Z","receivedAt":"2007-06-16T08:49:39Z","isPatch":false,"sender":{"key":"madcoder@debian.org","avatar":"https://avatars.githubusercontent.com/u/44708?v=4"},"body":"On Fri, Jun 15, 2007 at 03:52:09PM -0700, Junio C Hamano wrote:\n> Pierre Habouzit writes:\n> \n> > sadly, it does not fixes the issue I reported with git-pull.1 (e.g.)\n> > that reads:\n> >\n> > \n> > The canonical format of a parameter is ?:; that\n> >\n> > whereas it should be:\n> >\n> > \n> > The canonical format of a parameter is +?:; that\n> \n> That is very unexpected, especially as your e-mail address is in\n> debian.org.\n\n Well I'm running unstable, with asciidoc 8.2.1.\n\n> * I updated my notebook that runs Debian with AsciiDoc 8.2.1\n> and tested with the patch. The formatted result matches the\n> above.\n\n AAAAND I'M AN IDIOT. I tested it in the wrong branch, without the\npatch. do'h.\n\n I confirm that it works perfectly. Now, does someone knows a hole\nwhere I can hide into ?\n\n-- \n·O· Pierre Habouzit\n··O madcoder@debian.org\nOOO http://www.madism.org\n"},{"id":"45181","messageId":"7vabuz3914.fsf@assigned-by-dhcp.pobox.com","threadId":"8456","inReplyTo":"20070616084939.GA9118@artemis","subject":"Re: [RFT] Format our Documentation/ with both AsciiDoc 7 & 8","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2007-06-16T21:05:11Z","receivedAt":"2007-06-16T21:05:11Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Pierre Habouzit writes:\n\n> AAAAND I'M AN IDIOT. I tested it in the wrong branch, without the\n> patch. do'h.\n>\n> I confirm that it works perfectly. Now, does someone knows a hole\n> where I can hide into ?\n\nYou don't need a hole. Thanks for a timely confirmation.\n"}]}