threads / bug / 15373

[BUG] Problem compiling documentation

Subject: [BUG] Problem compiling documentation

## tl;dr

5 messages between Sep 4, 2008 and Sep 5, 2008.

replies: 4people: 3as markdown or json

Gustaf Hendeby· Sep 4, 2008, 10:43 UTC · lore

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

Johan Herland· Sep 4, 2008, 21:48 UTC · re: Gustaf Hendeby · lore

[PATCH] Fix AsciiDoc errors in merge documentation

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

Gustaf Hendeby· Sep 4, 2008, 22:26 UTC · re: Johan Herland · lore

Re: [PATCH] Fix AsciiDoc errors in merge documentation

Johan Herland wrote:

Show 7 quoted lines

> 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

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

Junio C Hamano· Sep 4, 2008, 23:19 UTC · re: Johan Herland · lore

Re: [PATCH] Fix AsciiDoc errors in merge documentation

Johan Herland <johan@herland.net> writes:

Show 19 quoted lines

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

Johan Herland· Sep 5, 2008, 06:09 UTC · re: Junio C Hamano · lore

Re: [PATCH] Fix AsciiDoc errors in merge documentation

On Friday 05 September 2008, Junio C Hamano wrote:

Show 5 quoted lines

> 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