[BUG] Problem compiling documentation

[BUG] Problem compiling documentation

[Gustaf Hendeby]

Hi!

Trying to compile the documentation from next has failed for me for a
while and now I got to the point where I tracked down the offending
commit: 70a3f89733a (git-merge documentation: describe how conflict is
presented).

I don't have time to dig much deeper into this until later today, but it
seems to be that the conflict markers are interpreted to indicate a
section heading, that is then not correctly formated.  The error i get
is listed below.  Feel free to try to beat me to finding a nice solution. :)

I am using xmlto 0.0.21 and Asciidoc 8.2.7.

/Gustaf

xmlto -m callouts.xsl man git-merge.xml
xmlto: input does not validate (status 1)
/scratch/src/git/git/Documentation/git-merge.xml:551: parser error :
attributes construct error
"&lt;&lt;&lt;&lt;<link
linkend=""">"======="</link>&gt;&gt;&gt;&gt;&gt;".  The p
                                 ^
/scratch/src/git/git/Documentation/git-merge.xml:551: parser error :
Couldn't find end of Start Tag link line 551
"&lt;&lt;&lt;&lt;<link
linkend=""">"======="</link>&gt;&gt;&gt;&gt;&gt;".  The p
                                 ^
/scratch/src/git/git/Documentation/git-merge.xml:551: parser error :
Opening and ending tag mismatch: simpara line 550 and link
"&lt;&lt;&lt;&lt;<link
linkend=""">"======="</link>&gt;&gt;&gt;&gt;&gt;".  The p
                                                   ^
/scratch/src/git/git/Documentation/git-merge.xml:552: parser error :
Opening and ending tag mismatch: refsect1 line 526 and simpara
typically your side, and the part after it is typically their
side.</simpara>

     ^
/scratch/src/git/git/Documentation/git-merge.xml:577: parser error :
attributes construct error
<simpara>In addition to the "&lt;&lt;&lt;&lt;<link
linkend=""">"======="</link>&
                                                             ^
/scratch/src/git/git/Documentation/git-merge.xml:577: parser error :
Couldn't find end of Start Tag link line 577
<simpara>In addition to the "&lt;&lt;&lt;&lt;<link
linkend=""">"======="</link>&
                                                             ^
/scratch/src/git/git/Documentation/git-merge.xml:577: parser error :
Opening and ending tag mismatch: simpara line 577 and link
<simpara>In addition to the "&lt;&lt;&lt;&lt;<link
linkend=""">"======="</link>&

       ^
/scratch/src/git/git/Documentation/git-merge.xml:582: parser error :
Opening and ending tag mismatch: refentry line 3 and simpara
viewing the original.</simpara>
                               ^
/scratch/src/git/git/Documentation/git-merge.xml:584: parser error :
Extra content at the end of the document
</refsect1>
^

[PATCH] Fix AsciiDoc errors in merge documentation

[Johan Herland]

In the section on conflict markers, the "<<<<<<<" sequence is compiled by
AsciiDoc into invalid XML. A way to resolve this is by inserting something
between the last two characters in that sequence (i.e. between '<' and '"').

This patch encloses the conflict markers in backticks, which renders them
in a monospace font (in the HTML version; the manual page is unaffected),
and with the pleasant side-effect that it also fixes the AsciiDoc compile
problem.

Signed-off-by: Johan Herland <johan@herland.net>
---

On Thursday 04 September 2008, Gustaf Hendeby wrote:
> Trying to compile the documentation from next has failed for me for a
> while and now I got to the point where I tracked down the offending
> commit: 70a3f89733a (git-merge documentation: describe how conflict is
> presented).

This fixes the problem for me.


Have fun! :)

...Johan


 Documentation/git-merge.txt |    8 ++++----
 1 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 69dd872..1f30830 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -146,8 +146,8 @@ And here is another line that is cleanly resolved or unmodified.
 ------------
 
 The area a pair of conflicting changes happened is marked with markers
-"<<<<<<", "=======", and ">>>>>>>".  The part before the "=======" is
-typically your side, and the part after it is typically their side.
+"`<<<<<<<`", "`=======`", and "`>>>>>>>`".  The part before the "`=======`"
+is typically your side, and the part after it is typically their side.
 
 The default format does not show what the original said in the conflicted
 area.  You cannot tell how many lines are deleted and replaced with the
@@ -173,8 +173,8 @@ Git makes conflict resolution easy.
 And here is another line that is cleanly resolved or unmodified.
 ------------
 
-In addition to the "<<<<<<", "=======", and ">>>>>>>" markers, it uses
-another "|||||||" marker that is followed by the original text.  You can
+In addition to the "`<<<<<<<`", "`=======`", and "`>>>>>>>`" markers, it uses
+another "`|||||||`" marker that is followed by the original text.  You can
 tell that the original just stated a fact, and your side simply gave in to
 that statement and gave up, while the other side tried to have a more
 positive attitude.  You can sometimes come up with a better resolution by
-- 
1.6.0.96.g2fad1

Re: [PATCH] Fix AsciiDoc errors in merge documentation

[Gustaf Hendeby]

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

Johan Herland wrote:
> On Thursday 04 September 2008, Gustaf Hendeby wrote:
>> Trying to compile the documentation from next has failed for me for a
>> while and now I got to the point where I tracked down the offending
>> commit: 70a3f89733a (git-merge documentation: describe how conflict is
>> presented).
> 
> This fixes the problem for me.

Nice, solves my problems too. Thanks!

Tested-by: Gustaf Hendeby <hendeby@isy.liu.se>

/Gustaf

[-- Attachment #2: hendeby.vcf --]
[-- Type: text/x-vcard, Size: 386 bytes --]

begin:vcard
fn:Gustaf Hendeby
n:Hendeby;Gustaf
org;quoted-printable:Link=C3=B6pings universitet;Department of Electrical Enginering
adr;quoted-printable:;;;Link=C3=B6ping;;SE-581 83;Sweden
email;internet:hendeby@isy.liu.se
title:Research Associate
tel;work:+46 14 28 22 26
tel;cell:+46 730 64 64 89
x-mozilla-html:FALSE
url:http://www.control.isy.liu.se/~hendeby
version:2.1
end:vcard

Re: [PATCH] Fix AsciiDoc errors in merge documentation

[Junio C Hamano]

Johan Herland <johan@herland.net> writes:

> In the section on conflict markers, the "<<<<<<<" sequence is compiled by
> AsciiDoc into invalid XML. A way to resolve this is by inserting something
> between the last two characters in that sequence (i.e. between '<' and '"').
>
> This patch encloses the conflict markers in backticks, which renders them
> in a monospace font (in the HTML version; the manual page is unaffected),
> and with the pleasant side-effect that it also fixes the AsciiDoc compile
> problem.
>
> Signed-off-by: Johan Herland <johan@herland.net>
> ---
>
> On Thursday 04 September 2008, Gustaf Hendeby wrote:
>> Trying to compile the documentation from next has failed for me for a
>> while and now I got to the point where I tracked down the offending
>> commit: 70a3f89733a (git-merge documentation: describe how conflict is
>> presented).
>
> This fixes the problem for me.

Thanks.  It's good to see issues with new changes are resolved while they
are still in 'next'.

Have you tried this patch without double quotes around the teletype text,
by the way?

Re: [PATCH] Fix AsciiDoc errors in merge documentation

[Johan Herland]

On Friday 05 September 2008, Junio C Hamano wrote:
> Johan Herland <johan@herland.net> writes:
> > [...]
>
> Thanks.  It's good to see issues with new changes are resolved while they
> are still in 'next'.

Hey, that's what next is for, isn't it? ;)

> Have you tried this patch without double quotes around the teletype text,
> by the way?

Seems to work fine, as well.


...Johan

-- 
Johan Herland, <johan@herland.net>
www.herland.net