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:
quoted
On 2017-01-22 02:41:56, brian m. carlson wrote:
quoted
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 [off-list ref] - 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 |-------------+