Subject: Re: [PATCH] asciidoctor-extensions: provide `<refmiscinfo/>`

From: Todd Zullinger <[email-masked]>
Date: Sun, 24 Mar 2019 12:21:31 -0400

Hi,

Jeff King wrote:
> On Sat, Mar 23, 2019 at 03:27:56PM -0400, Todd Zullinger wrote:
> 
>> I updated my system to asciidoctor-2.0.0 last night and now
>> I can't even generate the man pages properly, because the
>> docbook45 converter was removed.  I'll have to see if I
>> missed some other required update. :/
> 
> I ran into that, too. Using ASCIIDOC_DOCBOOK=docbook5 worked. The output
> looked OK to me, but I only eyeballed it briefly. It's possible there
> are subtle problems.

Interesting.  I did that last night as well, but it only led
to more errors.  I'm curious why manpage builds work for you
and not for me.

On my fedora 29 test system, ASCIIDOC_DOCBOOK=docbook5 leads
to a validation failure from xmlto, since docbook5 doesn't
use a DTD¹.  I added XMLTO_EXTRA = --skip-validation to the
USE_ASCIIDOCTOR block, which can build many of the man
pages, but fails when it gets to git-blame due to use of
literal < > characters in the xml:

    git-blame.xml:423: parser error : StartTag: invalid element name
    <literallayout class="monospaced"><40-byte hex sha1> <sourceline> <resultline> <
                                       ^

While this may be a real issue in the formatting of
git-blame.txt which we should fix, I'm suspicious of that
due to the number of other files similarly affected:

    git-blame.txt
    git-diff-files.txt
    git-diff-index.txt
    git-diff-tree.txt
    git-diff.txt
    git-format-patch.txt
    git-http-fetch.txt
    git-log.txt
    git-rebase.txt
    git-rev-list.txt
    git-show.txt
    git-svn.txt

¹ Here's the failure I get without --skip-validation:
[tmz@f29 Documentation]$ make USE_ASCIIDOCTOR=1 git.1
    SUBDIR ../
make[1]: 'GIT-VERSION-FILE' is up to date.
    ASCIIDOC git.xml
    XMLTO git.1
xmlto: /home/tmz/src/git/Documentation/git.xml does not validate (status 3)
xmlto: Fix document syntax or use --skip-validation option
validity error : no DTD found!
Document /home/tmz/src/git/Documentation/git.xml does not validate
make: *** [Makefile:359: git.1] Error 13

Thanks,

-- 
Todd