On 2017-01-23 04:09:17, brian m. carlson wrote:
> On Mon, Jan 23, 2017 at 03:57:13AM +0100, Øyvind A. Holm wrote:
> > On 2017-01-22 02:41:56, brian m. carlson wrote:
> > > While Git has traditionally built its documentation using
> > > AsciiDoc, some people wish to use Asciidoctor for speed or other
> > > reasons. Add a Makefile knob, USE_ASCIIDOCTOR, that sets various
> > > options in order to produce acceptable output. For HTML output,
> > > XHTML5 was chosen, since the AsciiDoc options also produce XHTML,
> > > albeit XHTML 1.1.
> >
> > I applied and tested the patches on the current master, commit
> > 787f75f0567a ("Sixth batch for 2.12"), and "make doc" with
> > USE_ASCIIDOCTOR fails:
> >
> > [...]
> >
> > $ asciidoctor --version
> > Asciidoctor 0.1.4 [http://asciidoctor.org]
>
> I think you need a newer version of Asciidoctor. I fixed one or two
> issues upstream in 1.5.2, I think, that made it work properly.
I've tried on Linux Mint 18 with Asciidoctor 1.5.4 now, and it works
there, so the version is probably too old, yes.
> You could try to do the build with the "html5" target instead of
> "xhtml5" and see if that works. If so, we could switch to that
> instead if we want to support older Asciidoctor versions.
It went a little better, but after a while it died with
$ make doc USE_ASCIIDOCTOR=1
[Cut 249 lines]
GEN technical/api-index.txt
ASCIIDOC technical/api-index.html
ASCIIDOC git-init-db.xml
sed "s|@@MAN_BASE_URL@@|file:///home/sunny/share/doc/git-doc/|"
manpage-base-url.xsl.in > manpage-base-url.xsl
XMLTO git-init-db.1
xmlto:
/home/sunny/src/git/src-other/devel/git/git/Documentation/git-init-db.xml does
not validate (status 3)
xmlto: Fix document syntax or use --skip-validation option
/home/sunny/src/git/src-other/devel/git/git/Documentation/git-init-db.xml:5:
element article: validity error : root and DTD name do not match 'article' and
'manpage'
Document
/home/sunny/src/git/src-other/devel/git/git/Documentation/git-init-db.xml does
not validate
Makefile:343: recipe for target 'git-init-db.1' failed
make[1]: *** [git-init-db.1] Error 13
make[1]: Leaving directory
'/home/sunny/src/git/src-other/devel/git/git/Documentation'
Makefile:2091: recipe for target 'doc' failed
make: *** [doc] Error 2
$
and that's fair enough, since the generated html isn't well-formed.
Adding --skip-validation to XMLTO_EXTRA gave a slightly different
result:
GEN technical/api-index.txt
ASCIIDOC technical/api-index.html
ASCIIDOC git-init-db.xml
sed "s|@@MAN_BASE_URL@@|file:///home/sunny/share/doc/git-doc/|"
manpage-base-url.xsl.in > manpage-base-url.xsl
XMLTO git-init-db.1
Note: namesp. cut : stripped namespace before processing
git-init-db(1)
Note: namesp. cut : processing stripped document
git-init-db(1)
Erro: no refentry: No refentry elements found in "git-init-db(1)
git-init-db(1)
Makefile:343: recipe for target 'git-init-db.1' failed
make[1]: *** [git-init-db.1] Error 1
make[1]: Leaving directory
'/home/sunny/src/git/src-other/devel/git/git/Documentation'
Makefile:2091: recipe for target 'doc' failed
make: *** [doc] Error 2
$
But frankly, this probably isn't a showstopper. Even though this is the
newest stable version of Debian, Asciidoctor 0.1.4 was released
2013-09-05, 3y5m ago. USE_ASCIIDOCTOR isn't the default, so people can
build the docs with asciidoc, and that works in Debian 8.7.
Regards,
Øyvind
+-| Øyvind A. Holm <[email protected]> - N 60.37604° E 5.33339° |-+
| OpenPGP: 0xFB0CBEE894A506E5 - http://www.sunbase.org/pubkey.asc |
| Fingerprint: A006 05D6 E676 B319 55E2 E77E FB0C BEE8 94A5 06E5 |
+------------| 1698e7f6-e257-11e6-bfa0-db5caa6d21d3 |-------------+
signature.asc
Description: PGP signature
