Re: [PATCH v2 7/7] Makefile: add a knob to enable the use of Asciidoctor

From: Øyvind A. Holm <sunny@sunbase.org>
Date: Jan 25, 2017, 02:26 UTC
Message-ID: <20170125022628.dyqokkdfxasfxjrl@sunbase.org>
In-Reply-To: <20170123040917.lrd6ic6wb6nxulzf@genre.crustytoothpaste.net>

On 2017-01-23 04:09:17, brian m. carlson wrote:

Show 20 quoted lines

> 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 <sunny@sunbase.org> - 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 |-------------+