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

From: brian m. carlson <sandals@crustytoothpaste.net>
Date: Jan 23, 2017, 04:09 UTC
Message-ID: <20170123040917.lrd6ic6wb6nxulzf@genre.crustytoothpaste.net>
In-Reply-To: <20170123025712.o52hgkdu26h6lrm2@sunbase.org>

On Mon, Jan 23, 2017 at 03:57:13AM +0100, Øyvind A. Holm wrote:

Show 61 quoted lines

> 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:
> 
>   $ git clean -fxd && make doc USE_ASCIIDOCTOR=1
>   Removing Documentation/cmd-list.made
>   Removing Documentation/cmds-ancillaryinterrogators.txt
>   Removing Documentation/cmds-ancillarymanipulators.txt
>   Removing Documentation/cmds-foreignscminterface.txt
>   Removing Documentation/cmds-mainporcelain.txt
>   Removing Documentation/cmds-plumbinginterrogators.txt
>   Removing Documentation/cmds-plumbingmanipulators.txt
>   Removing Documentation/cmds-purehelpers.txt
>   Removing Documentation/cmds-synchelpers.txt
>   Removing Documentation/cmds-synchingrepositories.txt
>   Removing Documentation/doc.dep
>   Removing Documentation/mergetools-diff.txt
>   Removing Documentation/mergetools-list.made
>   Removing Documentation/mergetools-merge.txt
>   Removing GIT-VERSION-FILE
>   GIT_VERSION = 2.11.0.460.g218feb5a0e89
>   make -C Documentation all
>   make[1]: Entering directory '/home/sunny/src/git/src-other/devel/git/git/Documentation'
>       GEN mergetools-list.made
>       GEN cmd-list.made
>       GEN doc.dep
>   make[2]: Entering directory '/home/sunny/src/git/src-other/devel/git/git'
>   make[2]: 'GIT-VERSION-FILE' is up to date.
>   make[2]: Leaving directory '/home/sunny/src/git/src-other/devel/git/git'
>   make[2]: Entering directory '/home/sunny/src/git/src-other/devel/git/git'
>   make[2]: 'GIT-VERSION-FILE' is up to date.
>   make[2]: Leaving directory '/home/sunny/src/git/src-other/devel/git/git'
>       ASCIIDOC git-init-db.html
>   Couldn't find a view in @views for document
>     Use --trace for backtrace
>   Makefile:330: recipe for target 'git-init-db.html' failed
>   make[1]: *** [git-init-db.html] 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
>   2017-01-23 03:50:05 sunny@sunbase:~/src/git/src-other/devel/git/git (tp-bmc-asciidoctor)
> 
>   $ lsb_release -d
>   Description:    Debian GNU/Linux 8.7 (jessie)
> 
>   $ asciidoctor --version
>   Asciidoctor 0.1.4 [http://asciidoctor.org]
> 
> I installed Asciidoctor with a standard "apt-get install asciidoctor", 
> do I need to install more packages?
> 
> The build is broken by patch #7 ("Makefile: add a knob to enable the use 
> of Asciidoctor"), the other commits seems to work, though I haven't 
> tested them all individually yet. Standard "make doc" works.

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.

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.

-- 
brian m. carlson / brian with sandals: Houston, Texas, US
+1 832 623 2791 | https://www.crustytoothpaste.net/~bmc | My opinion only
OpenPGP: https://keybase.io/bk2204