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

[Johannes Schindelin <johannes.schindelin@gmx.de>]

[-- Attachment #1: Type: text/plain, Size: 2856 bytes --]

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

-- 
2.11.0.rc3.windows.1