patchDocumentation typo.

From: Pierre Habouzit <pierre.habouzit@m4x.org>

Signed-off-by: Pierre Habouzit <madcoder@debian.org>
---
 Documentation/pull-fetch-param.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

Pierre Habouzit <madcoder@debian.org> writes:

Not really.  I suspect you are using AsciiDoc 8?

Your patch does make AsciiDoc 8 keep '+' in the HTML output, but manual page output gets an extra backslash, so it is not really an improvement.

Unfortunately our documentation pages were written with AsciiDoc 7, and are not AsciiDoc 8 compatible.

With -aasciidoc7compatible, AsciiDoc 8 is _supposed_ to behave compatibly, but in reality it does not format our documentation correctly. It certainly is possible that AsciiDoc 7 "happens to work" with our documentation pages, and maybe the way we abuse mark-ups can be argued the bug in _our_ documentation, but nobody on our end worked on finding a satisfactory solution to make our documentation format correctly with _both_ versions of AsciiDoc yet.

I wrote about the differences between AsciiDoc 7, and AsciiDoc 8 with the "compatiblity" I found a few weeks ago on this list; the most problematic was that 'asciidoc -aasciidoc7compatible' loses carets in our description where they matter X-<. The list archive may know more about the details,

On Wed, Jun 06, 2007 at 02:16:36PM -0700, Junio C Hamano wrote:

  indeed ...

  Not for me, using asciidoc 8.2.1 on debian. It was because the manpage
was missing a '+' that I actually wrote this patch, as it was really
akward.

  Okay, I see, sorry for the noise then.

Pierre Habouzit <madcoder@debian.org> writes:

Well, it was NOT a noise. Making the docs usable with both 7 and 8 is a task waiting for a volunteer ;-).

It turns out that the attribute definition we have had for a long time to hide "^" character from AsciiDoc 7 was not honored by AsciiDoc 8 even under "-a asciidoc7compatible" mode.

Also the double colon at the end of definition list term needs to be attached to the term, without a whitespace. After this minimum fixups, AsciiDoc 8 (I used 8.2.1 on Debian) with compatibility mode seems to produce reasonably good results.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---

 * This is "Request for Test" to people who reported problems
   formatting our documentation with asciidoc 8.  To format with
   Asciidoc 8, you would need to say something like:

	$ make ASCIIDOC8=YesPlease doc

   I've compared the output generated with AsciiDoc 7.1.2
   without this patch, and generated with AscooDoc 7.1.2 and
   AsciiDoc 8.2.1 with this patch.  Aside from the expected
   obvious differences in:

   - embedded Git version string in manpage output
   - generation datestamp in HTML output
   - autogenerated anchor href="#id" and name="id" in HTML output

   the only differences I saw are:

   - _word_ is rendered in HTML as <em>word<em> in AsciiDoc 8,
     while it used to come out verbatim under AsciiDoc 7.  Nice.

   - HTML stylesheet is a bit different from AsciiDoc 8.
     Presumably an improvement.

 Documentation/Makefile                |    3 +++
 Documentation/asciidoc.conf           |    2 +-
 Documentation/git-cvsexportcommit.txt |    2 +-
 Makefile                              |    6 ++++++
 4 files changed, 11 insertions(+), 2 deletions(-)

On Thu, Jun 14, 2007 at 11:34:20PM -0700, Junio C Hamano wrote:

  sadly, it does not fixes the issue I reported with git-pull.1 (e.g.)
that reads:

   <refspec>
       The canonical format of a <refspec> parameter is ?<src>:<dst>; that

whereas it should be:

   <refspec>
       The canonical format of a <refspec> parameter is +?<src>:<dst>; that

But I've not seen any serious or even noticeable regression here.

Pierre Habouzit <madcoder@debian.org> writes:

That is very unexpected, especially as your e-mail address is in debian.org.

 * My local test and build usually is done with AsciiDoc 7.1.2
   that is shipped with Debian, without any local modifications.
   The part you quoted is formatted like this (I indented for
   e-mail inclusion and line-wrapped below):

    .PP
    <refspec>
    .RS 3n

    The canonical format of a <refspec> parameter is +?<src>:<dst>;
    that is, an optional plus +, followed by the source ref,
    followed by a colon :, followed by the destination ref.

   This is the same with or without the patch we are
   discussing.

 * I updated my notebook that runs Debian with AsciiDoc 8.2.1
   and tested with the patch.  The formatted result matches the
   above.

 * I tried the above with a hand-installed AsciiDoc 8.2.1 from
   the tarball distribution.  Again, the formatted result of the
   quoted part matches.

 * The preformatted manual pages on man branch in git.git are
   generated on a k.org machine that runs AsciiDoc 7.0.2 on
   FC5.  The version before the patch is formatted like this:

    .TP
    <refspec>
    The canonical format of a <refspec> parameter is +?<src>:<dst>;
    that is, an optional plus +, followed by the source ref,
    followed by a colon :, followed by the destination ref.

   I haven't had a chance to test how it comes out with the
   patch, but because the only difference under AsciiDoc 7 is
   the definition of {caret} macro, I do not expect any change
   in the quoted area.

In other words, there is no breakage like you are observing in the original (nor updated) version with any of the platforms and AsciiDoc versions I had handy to test. There is something different with the version of AsciiDoc you are using, but I cannot tell what that is.

On Fri, Jun 15, 2007 at 03:52:09PM -0700, Junio C Hamano wrote:

  Well I'm running unstable, with asciidoc 8.2.1.

  AAAAND I'M AN IDIOT. I tested it in the wrong branch, without the
patch. do'h.

  I confirm that it works perfectly. Now, does someone knows a hole
where I can hide into ?

Pierre Habouzit <madcoder@debian.org> writes:

You don't need a hole.  Thanks for a timely confirmation.