git doc build failure on OS X 10.5.6 (Leopard) during xmlto phase

Hello,

On OS X 10.5.6 (Leopard), the command ...

   xmlto -m callouts.xsl man git-filter-branch.xml

... terminates with these errors:

xmlto: input does not validate (status 1)
/git-1.6.2/Documentation/git-filter-branch.xml:431: parser error :
PCDATA invalid Char value 7
Clone it with <literal>git clone +++0+++</literal>.  The clone
                                    ^
/git-1.6.2/Documentation/git-filter-branch.xml:431: parser error :
PCDATA invalid Char value 7
Clone it with <literal>git clone +++0+++</literal>.  The clone
                                      ^
make[1]: *** [git-filter-branch.1] Error 1
make: *** [doc] Error 2

What issue-tracker, if any, would be appropriate for this?

-- Tom Holaday

Tom Holaday venit, vidit, dixit 11.03.2009 15:21:

That means that the xml file is incorrect already, which means it's an asciidoc problem. What's your asciidoc version?

You should send a note to the mailing list ;)

Michael

On Wed, Mar 11, 2009 at 10:21 AM, Tom Holaday <tlholaday@gmail.com> wrote:

Assuming you're using the MacPorts asciidoc, to build on OS X you need:

  export ASCIIDOC8=YesPlease
  export DOCBOOK_XSL_172=YesPlease

And your man pages still won't be perfect. Preformatted text will look like this:

  .ft C
          ...
  .ft

I haven't had a chance to track down what is causing this. If you build and install the html pages and use "help -w" those are formatted fine. You may just want to install the prebuilt man-pages (quick-install-doc or quick-install-man).

j.

On Wed, Mar 11, 2009 at 11:12 AM, Jay Soffian <jaysoffian@gmail.com> wrote:

Hmm. git-help.txt has this text:

---snip---
------------------------------------------------
	[man]
		viewer = konqueror
		viewer = woman
------------------------------------------------
---snap---

Which gets translated to:

---snip---
<literallayout>
&#10;.ft C&#10;        [man]
                viewer = konqueror
                viewer = woman&#10;.ft&#10;
</literallayout>
---snap---

While git-push has this text:

---snip--- + -------------------------- git push public #1 git push --repo=public #2 -------------------------- + ---snap---

Which gets translated to:

---snip--- <screen>git push public #1 git push --repo=public #2</screen> ---snap---

Both appear to render identically after being transformed into html, but the transformation to man pages leaves the ".ft C" and ".ft" macros literally in the resultant text. This is using asciidoc 8.3.1 and docbook-xsl 1.74.0. Further investigation is in order, but the transformation from asciidoc to man pages is currently deep magic to me.

j.

On Wed, Mar 11, 2009 at 11:39 AM, Jay Soffian <jaysoffian@gmail.com> wrote:

I must be losing my mind. This is suddenly working, though I can't track it down to any change in git. I just rebuilt my man pages and this no longer is occurring, even though I still have a terminal window open with the output of "git help help" _showing this problem_ and that's from man pages I built/installed just a few days ago. (And I haven't upgraded MacPorts lately.)

Oh well.

j.

Jay Soffian venit, vidit, dixit 11.03.2009 16:49:

FWIW: The effect you describe (which is different from the OP) occurs on
Fedora 10 as well, and not only for git man pages, also for others. I've
been meaning to look into this, just like I've been meaning to look into
so much stuff...

Michael

El Wed, 11 Mar 2009 17:27:28 +0100, Michael J Gruber escribió:

 "Me too" from a Ubuntu 8.10 Box

Alejandro Riveira venit, vidit, dixit 11.03.2009 21:12:

Following up on this: On Fedora 10, I have asciidoc 8.2.5 and docbook 1.7.4 xsl's. For proper man and html doc, I have to set DOCBOOK_XSL_172=Yes but leave ASCIIDOC8 unset! I always forget, though (just like the packagers).

Setting DOCBOOK_XSL_172 shuts off a certain hack which would otherwise introduce the notorious .ft in man output.

Setting ASCIIDOC8 would keep _emphasis_ from being transformed into <emphasis>emphasis</emphasis>, which means it would end up as literal _emphasis_ in man as well as html.

Michael

BTW: Alejandro, please don't cull cc here.

El Thu, 12 Mar 2009 12:17:18 +0100 Michael J Gruber <git@drmicha.warpmail.net> escribió:

 I'm sorry :[
 In my defense that was using gmane new service via Pan 
 
 Thanks for the explanation on how to workaround the issue

Michael J Gruber wrote:

Check the fedora git packages in rawhide, we don't set ASCIIDOC8. :)

I experimented with that and found it did not improve things. We are only setting DOCBOOK_XSL_172. Without that, we get the '.ft C' droppings. With it, we get non-ascii characters in various places (where bold should be used to make the (1) notations stand out, for example). This was filed as:

https://bugzilla.redhat.com/show_bug.cgi?id=485161

I didn't add DOCBOOK_XSL_172 to the F-10 packages yet, because I know that it fixes one problem and causes another. Either way, we'd be shipping packages with known brokeness. I chose to stick with keeping the currently broken '.ft C' behavior. Pick your poison. ;)

One of the fedora/red hat folks that works on the xmlto and docbook packages was going to take a look, as I very much don't understand the documentation stack. :/

Anyone who does is very welcome to help find the culprit(s) and help get fixes to the proper places.

Todd Zullinger venit, vidit, dixit 12.03.2009 18:09:

I was unclear, but I meant forgetting to set DOCB... But:

I hadn't noticed that yet (neither the effect nor the report). So, you kept it unset intentionally and for a good reason. Please accept my apology!

So the easy solution is out again, quite a pitty. The problem occurs on F10 as well as F11/rawhide, right?

On a related issue: Does anybody know which asciidoc versions need asciidoc7compatible to be set? 8.2.5 and above certainly don't, so we should not advise using it. asciidoc's hg repo doesn't go back much more (the initial revision does not need it either), and I haven't dug for their earlier history yet.

Michael J Gruber

On Fri, Mar 13, 2009 at 6:29 AM, Michael J Gruber <git@drmicha.warpmail.net> wrote:

I'm using 8.3.1 and set asciidoc7compatible. I don't recall why I set it, but I'm sure I had a good reason for it. :-)

j.

Jay Soffian venit, vidit, dixit 13.03.2009 17:18:

And you don't have any issues with _emphasis_? E.g. in git help filter-branch, "positive" in the second paragraph should be emphasized, possibly underlined.

OK, I just checked myself. At least 8.2.7 still had problems, but 8.3.0 is fine, even 8.4.1 is. asciidoc needs to be convinced forcibly to look for its config in its own location (rather than /etc), which is what tripped off my first tests...

So, asciidoc version 8.3.0 and above is fine with asciidoc7compatible (at least regarding emphasis), 8.2.4~23 through 8.2.7 is not. Below their hg history ends.

Oh well, the doc tool chain. Dig into it and feel chained to a stool, in need to see a doc. Lame pun, time to go home :|

Michael

Hi,

I am attempting to build git-1.6.2-1 on CentOS5.3 and running into this problem:

  parser error : PCDATA invalid Char value 7

I am using asciidoc-8.4.1 and yesterday, when I first built git from the src rpm, the process completed without error.  The only thing that has happened to the build system since then is an update of perl packages from epel.  I do not see how that would affect anything, but I include the information for completeness nonetheless.  

In any case, I can live without the documentation if that will get the application built. I have tried the suggestions with respect to setting ENV variables without success: $ set ASCIIDOC8=YesPlease ... DOCBOOK_XSL_172=YesPlease

So, have I misunderstood the instructions given here?  Is there something else I should do?  Is there a way to simply skip the documentation part of the build?

Is there a way to simply skip the documentation part of the build?

$ rpmbuild -bb --without docs git.spec # this gets me the application at least.

Is there a fix or workaroung to get past the asciidoc error?