[PATCH] Documentation typo.

[PATCH] Documentation typo.

[Pierre Habouzit]

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(-)

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

Re: [PATCH] Documentation typo.

[Junio C Hamano]

Pierre Habouzit <madcoder@debian.org> writes:

> 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(-)
>
> 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?

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,

Re: [PATCH] Documentation typo.

[Pierre Habouzit]

[-- Attachment #1: Type: text/plain, Size: 2416 bytes --]

On Wed, Jun 06, 2007 at 02:16:36PM -0700, Junio C Hamano wrote:
> Pierre Habouzit <madcoder@debian.org> writes:
> 
> > 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(-)
> >
> > 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

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [PATCH] Documentation typo.

[Junio C Hamano]

Pierre Habouzit <madcoder@debian.org> writes:

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

[RFT] Format our Documentation/ with both AsciiDoc 7 & 8

[Junio C Hamano]

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(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 9cef480..4edf788 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -37,6 +37,9 @@ man7dir=$(mandir)/man7
 
 ASCIIDOC=asciidoc
 ASCIIDOC_EXTRA =
+ifdef ASCIIDOC8
+ASCIIDOC_EXTRA += -a asciidoc7compatible
+endif
 INSTALL?=install
 DOC_REF = origin/man
 
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 99302c5..c135b6e 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -8,7 +8,7 @@
 # the command.
 
 [attributes]
-caret=^
+caret=&#94;
 startsb=&#91;
 endsb=&#93;
 tilde=&#126;
diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt
index 827711c..6c423e3 100644
--- a/Documentation/git-cvsexportcommit.txt
+++ b/Documentation/git-cvsexportcommit.txt
@@ -76,7 +76,7 @@ $ git-cvsexportcommit -v <commit-sha1>
 $ cvs commit -F .mgs <files>
 ------------
 
-Merge pending patches into CVS automatically -- only if you really know what you are doing ::
+Merge pending patches into CVS automatically -- only if you really know what you are doing::
 +
 ------------
 $ export GIT_DIR=~/project/.git
diff --git a/Makefile b/Makefile
index a70277b..d3b70d2 100644
--- a/Makefile
+++ b/Makefile
@@ -107,6 +107,8 @@ all::
 # Define USE_STDEV below if you want git to care about the underlying device
 # change being considered an inode change from the update-cache perspective.
 #
+# Define ASCIIDOC8 if you want to format documentation with AsciiDoc 8
+#
 # Define NO_PERL_MAKEMAKER if you cannot use Makefiles generated by perl's
 # MakeMaker (e.g. using ActiveState under Cygwin).
 #
@@ -684,6 +686,10 @@ ifndef V
 endif
 endif
 
+ifdef ASCIIDOC8
+	export ASCIIDOC8
+endif
+
 # Shell quote (do not use $(call) to accommodate ancient setups);
 
 SHA1_HEADER_SQ = $(subst ','\'',$(SHA1_HEADER))
-- 
1.5.2.1.280.g38570

Re: [RFT] Format our Documentation/ with both AsciiDoc 7 & 8

[Pierre Habouzit]

[-- Attachment #1: Type: text/plain, Size: 1355 bytes --]

On Thu, Jun 14, 2007 at 11:34:20PM -0700, Junio C Hamano wrote:
> 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

  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.
-- 
·O·  Pierre Habouzit
··O                                                madcoder@debian.org
OOO                                                http://www.madism.org

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [RFT] Format our Documentation/ with both AsciiDoc 7 & 8

[Junio C Hamano]

Pierre Habouzit <madcoder@debian.org> writes:

>   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

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.

Re: [RFT] Format our Documentation/ with both AsciiDoc 7 & 8

[Pierre Habouzit]

[-- Attachment #1: Type: text/plain, Size: 1097 bytes --]

On Fri, Jun 15, 2007 at 03:52:09PM -0700, Junio C Hamano wrote:
> Pierre Habouzit <madcoder@debian.org> writes:
> 
> >   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
> 
> That is very unexpected, especially as your e-mail address is in
> debian.org.

  Well I'm running unstable, with asciidoc 8.2.1.

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

  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 ?

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

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [RFT] Format our Documentation/ with both AsciiDoc 7 & 8

[Junio C Hamano]

Pierre Habouzit <madcoder@debian.org> writes:

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

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