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

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:

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:

  $ 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