Re: [PATCH] Documentation typo.

Pierre Habouzit [off-list ref] 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:

Pierre Habouzit [off-list ref] writes:

quoted

From: Pierre Habouzit <redacted>

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

diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
index 8d4e950..5bcdbc8 100644
--- a/Documentation/pull-fetch-param.txt
+++ b/Documentation/pull-fetch-param.txt

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

Not really.  I suspect you are using AsciiDoc 8?

  indeed ...

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.

  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.

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,

  Okay, I see, sorry for the noise then.

-- 
·O·  Pierre Habouzit
··O                                                madcoder@debian.org
OOO                                                http://www.madism.org

Pierre Habouzit [off-list ref] writes:

quoted

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.
 ...

  Okay, I see, sorry for the noise then.

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