asciidoc problem, and a possible fix

asciidoc problem, and a possible fix

[hachi]

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

Hello folks,

I had an issue building git on some centos 5 machines today, and in trying to interpret the error message I formed the attached patch.

The errors were:
xmlto: input does not validate (status 1)
/home/hachi/rpm/BUILD/git-1.7.0.3/Documentation/git-filter-branch.xml:463: parser error : PCDATA invalid Char value 7
Clone it with <literal>git clone +++0+++</literal>.  The clone
                                    ^
/home/hachi/rpm/BUILD/git-1.7.0.3/Documentation/git-filter-branch.xml:463: parser error : PCDATA invalid Char value 7
Clone it with <literal>git clone +++0+++</literal>.  The clone


I will happily admit that I don't know asciidoc, or the use of asciidoc in git.... but the +++ marker surrounding the url seems to not be used anywhere else in the documents directory, and I seem to be getting the appropriate output because of the `` surrounding the command.

I'm not subscribed to the list, but I'll try to watch for replies. Would anyone like to either tell me I did this wrong, or apply my fix?

Thanks much,

hachi


[-- Attachment #2: asciidoc-problem.patch --]
[-- Type: application/octet-stream, Size: 656 bytes --]

diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
index 020028c..4f71c17 100644
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.txt
@@ -386,7 +386,7 @@ objects until you tell it to.  First make sure that:
 Then there are two ways to get a smaller repository.  A safer way is
 to clone, that keeps your original intact.
 
-* Clone it with `git clone +++file:///path/to/repo+++`.  The clone
+* Clone it with `git clone file:///path/to/repo`.  The clone
   will not have the removed objects.  See linkgit:git-clone[1].  (Note
   that cloning with a plain path just hardlinks everything!)
 

Re: asciidoc problem, and a possible fix

[Junio C Hamano]

hachi <hachi@kuiki.net> writes:

> I had an issue building git on some centos 5 machines today, and in trying to interpret the error message I formed the attached patch.
>
> The errors were:
> xmlto: input does not validate (status 1)
> /home/hachi/rpm/BUILD/git-1.7.0.3/Documentation/git-filter-branch.xml:463: parser error : PCDATA invalid Char value 7
> Clone it with <literal>git clone +++0+++</literal>.  The clone
>                                     ^

A shot in the dark without sufficient information I could try to make is
that you are trying to use an ancient AsciiDoc, perhaps pre-7.1.2?

I am guessing that the following entry from their ChangeLog:

    Version 7.1.2 (2006-03-07)
    --------------------------
    .Additions and changes
     ...
    - An 'inline passthrough' mechanism has been implemented.

refers to this "triple-plus" passthrough, documented in:

    http://www.methods.co.nz/asciidoc/userguide.html#X77

As the use of feature is isolated to only the documentation for filter-branch,
I am personally Ok with replacing that passthru with a simpler formatting
element that is supported by an ancient version of AsciiDoc (but I didn't
look at your patch in the attachment).

Re: asciidoc problem, and a possible fix

[hachi]

Junio,

The short version:

>From asciidoc 8.4.1 to 8.5.0 nested inline passthrough (like +++ inside ``) cannot be used because the internal markers (\x07, BEL) will be emitted in the output.

asciidoc >= 8.4.2 will warn, and >= 8.5.0 will warn and do the right thing.

The +++ inside the `` that I'm getting rid of appear to be extraneous (I tested on an old 8.2.7 asciidoc).

I suggest applying my patch because it seems to be the right thing overall. More gory details follow.


The long version:

Thanks for telling me what this feature was called, now the changelog makes sense about this.

I'm running asciidoc 8.4.1, and in that version:

* Backtick quoting for monospaced text is now implemented as an inline literal passthrough. This makes more sense since monospace text is usually intended to be rendered literally.

which means that the line I'm on has a nested inline passthrough, of which a warning was added in asciidoc 8.4.2 (a quick test on a more modern distro shows):

asciidoc: WARNING: git-filter-branch.txt: line 391: nested inline passthrough

And then nested inline was fixed, in addition to the warning, in 8.5.0:

* FIXED: Only the first occurrence of passthrough macro was substituted. Patch submitted by Peter Johnson. See http://groups.google.com/group/asciidoc/browse_frm/thread/1269dc2feb1a482c


End conclusion:

* Option 1

My patch is correct because nested inline passthrough doesn't do anything other than confuse the asciidoc parser. However, this means that prior to asciidoc 8.4.1 the inside of backtick strings are not inline passthrough. I have no idea if this is a bad thing, but it seems to not actually matter in my test using asciidoc 8.2.6.

I do suggest applying my patch, actually. Let me know if I need to submit it a different way.

* Option 2

Consider enabling the asciidoc -a no-inline-literal option. This seems like it's a way to go back to the pre 8.4.1 behavior, but I can't tell if that's even right, and this seems to be a bad thing overall.

Thanks for reading, but I did tell you this was the long version down here ;)

--hachi

On Mar 24, 2010, at 5:51 PM, Junio C Hamano wrote:

> hachi <hachi@kuiki.net> writes:
> 
>> I had an issue building git on some centos 5 machines today, and in trying to interpret the error message I formed the attached patch.
>> 
>> The errors were:
>> xmlto: input does not validate (status 1)
>> /home/hachi/rpm/BUILD/git-1.7.0.3/Documentation/git-filter-branch.xml:463: parser error : PCDATA invalid Char value 7
>> Clone it with <literal>git clone +++0+++</literal>.  The clone
>>                                    ^
> 
> A shot in the dark without sufficient information I could try to make is
> that you are trying to use an ancient AsciiDoc, perhaps pre-7.1.2?
> 
> I am guessing that the following entry from their ChangeLog:
> 
>    Version 7.1.2 (2006-03-07)
>    --------------------------
>    .Additions and changes
>     ...
>    - An 'inline passthrough' mechanism has been implemented.
> 
> refers to this "triple-plus" passthrough, documented in:
> 
>    http://www.methods.co.nz/asciidoc/userguide.html#X77
> 
> As the use of feature is isolated to only the documentation for filter-branch,
> I am personally Ok with replacing that passthru with a simpler formatting
> element that is supported by an ancient version of AsciiDoc (but I didn't
> look at your patch in the attachment).
> 
> 

Re: asciidoc problem, and a possible fix

[Junio C Hamano]

hachi <hachi@kuiki.net> writes:

> The long version:
> ...
> End conclusion:

Thanks.  The above analysis would be a good foundation for you to write a
proper commit message when you submit a patch for application.  Please see
Documentation/SubmittingPatches.

> * Option 1
>
> My patch is correct because nested inline passthrough doesn't do
> anything other than confuse the asciidoc parser. However, this means
> that prior to asciidoc 8.4.1 the inside of backtick strings are not
> inline passthrough. I have no idea if this is a bad thing, but it seems
> to not actually matter in my test using asciidoc 8.2.6.

I'd really want to avoid anything that does not work with AsciiDoc 8.2.5,
as that is what is used to format the html/man branches at k.org.