[PATCH 0/2] Fix the documentation to build with asciidoctor

The first patch in this series has been with Git for Windows for well over a year already, the second one is a replacement for such an old patch.

The reason why we use asciidoctor in Git for Windows is easy to see: when building new Git for Windows packages, rendering the documentation dominates the time by far. It takes roughly 75 seconds to compile all the executables from scratch on my main work machine, but it takes roughly 125 seconds to build the documentation from scratch.

Out of those 125 seconds, 45 are taken by the HTML documentation.

In the Git for Windows project, we realized a long time ago that we could reduce the time dramatically by using asciidoctor: it takes only 15 seconds to build the HTML documentation.

Those savings come at a cost, though: asciidoctor was designed to be much less flexible than asciidoc, in favor for maximum speed and minimal size of the code base. And to accomodate those shortcomings, it is unfortunately necessary to change Git's documentation sources.

So what is the big deal with those timings? It's only half a minute!

This is on a very beefy machine. Internally, I use quite a bit of Continuous Integration to build intermediate Git for Windows versions for testing, and those builds are backed by reasonably-sized VMs. That makes it worth shaving that extra time off.

Side note for the curious who wonder why asciidoctor is *so much* faster than asciidoc: my gut feeling is that the primary reason for this is, once again, the POSIX emulation layer: asciidoc runs as a Python script, using a Python interpreter that uses the MSYS2 runtime for path translation and fork emulation (among other things), while asciidoctor runs as a Ruby script, using a pure Windows Ruby interpreter (for those remembering the nomenclature: the Python interpreter is an MSYS2 program while the Ruby interpreter is a MINGW program). But even after that I suspect that asciidoc was just not designed for speed, on a very fundamental level.

Now back to the patch series: I *hope* the patches are not too disruptive. I am very open to changing them however needed, I only care about one result in the end: that the documentation builds correctly (and fast) with asciidoctor.

Johannes Schindelin (1):
  giteveryday: unbreak rendering with AsciiDoctor

마누엘 (1):
  asciidoctor: fix user-manual to be built by `asciidoctor`

 Documentation/Makefile        |  2 +-
 Documentation/giteveryday.txt | 17 +++++++++--------
 Documentation/user-manual.txt |  8 ++++++++
 3 files changed, 18 insertions(+), 9 deletions(-)

base-commit: e05806da9ec4aff8adfed142ab2a2b3b02e33c8c
Published-As: https://github.com/dscho/git/releases/tag/asciidoctor-fixes-v1
Fetch-It-Via: git fetch https://github.com/dscho/git asciidoctor-fixes-v1