Use asciidoctor to compile the git-doc-* packages

[dscho]

@sschuberth pointed out that Git's documentation was recently adjusted to support being compiled using asciidoctor. It might speed up the generation substantial for us. Alternatively, we should look into using MinGW Python (as opposed to MSys2 Python) to run asciidoc.

[nalla]

I was able to build the documentation using asciidoctor by following the steps outlined below. By the way.

$ pacman -S mingw-w64-$arch-ruby
$ gem install asciidoctor
$ cd /usr/src
$ git clone https://github.com/asciidoctor/asciidoctor-extensions-lab
$ vi asciidoctor-extensions-lab/lib/man-inline-macro.rb
# uncomment the linkgit part in and the other out.
cd /usr/src/git
make html ASCIIDOC=asciidoctor ASCIIDOC_HTML=html5 ASCIIDOC_DOCBOOK=docbook45 ASCIIDOC_EXTRA="'-alitdd=--'" ASCIIDOC_CONF='-I/usr/src/asciidoctor-extensions-lab/lib -rman-inline-macro'

This should be a start. The only error I'm getting is with the user-manual.xml a couple of asciidoctor: ERROR: user-manual.txt: line 44: only book doctypes can contain level 0 sections errors are printed.

The part with ASCIIDOC_EXTRA="'-alitdd=--'" is from the patch announcement here

[dscho]

Thanks so much! I had briefly looked into this but did not go further.

Maybe we should bundle mingw-w64-$ARCH-asciidoctor-extensions as a Pacman package, with mingw-w64-$ARCH-ruby as dependency and gem install asciidoctor as a pre_install step in the .install script?

[nalla]

That sounds like a plan. I'll look into it.

BTW: I squashed some of the usermanual errors by setting the doctype to book.

[dscho]

As of git-for-windows/MINGW-packages@27504f7, this ticket is addressed! Thanks @nalla!

[linquize]

git-for-windows 2.4.1 used Asciidoctor to generate doc html pages.
but git-for-windows 2.4.6 use the old asciidoc.
Why?

[PhilipOakley]

git-for-windows 2.4.1 used Asciidoctor to generate doc html pages.
but git-for-windows 2.4.6 use the old asciidoc.
Why?

I know from the main git list that there were some formatting variations noticed between the two. I'm not sure of the specific decision to use the prior 'standard' converter.

[linquize]

But it is strange! In git-for-windows 1.x, old asciidoc is used. git-for-windows 2.4.1 used Asciidoctor.
But git-for-windows 2.4.6 goes back?

[PhilipOakley]

But it is strange! In git-for-windows 1.x, old asciidoc is used. git-for-windows > 2.4.1 used Asciidoctor.
But git-for-windows 2.4.6 goes back?

I think it happened in the main Git repo. They thought they could 'upgrade', but something don't work right, so they back tracked.

Would need to look at the change history/blame of the relevant code line.

Philip

[dscho]

I guess I got the GIT_SKIP_DOCS logic wrong..

[dscho]

I am now certain that I got the logic wrong. Thanks, @linquize, for pointing that out! git-for-windows/MINGW-packages@9625274 should fix it.