Re: [PATCH v2 0/7] Macros for Asciidoctor support

"brian m. carlson" [off-list ref] writes:

There are two major processors of AsciiDoc: AsciiDoc itself, and Asciidoctor.
Both have advantages and disadvantages, but traditionally the documentation has
been built with AsciiDoc, leading to some surprising breakage when building with
Asciidoctor.  Partially, this is due to the need to specify a significant number
of macros on the command line when building with Asciidoctor.

This series cleans up some issues building the documentation with Asciidoctor
and provides two knobs, USE_ASCIIDOCTOR, which controls building with
Asciidoctor, and ASCIIDOCTOR_EXTENSIONS_LAB, which controls the location of the
Asciidoctor Extensions Lab, which is necessary to expand the linkgit macro.

The need for the extensions could be replaced with a small amount of Ruby code,
if that's considered desirable.  Previous opinions on doing so were negative,
however.

In the process, I found several issues with cat-texi.perl, which have been
fixed.  It has also been modernized to use strict, warnings, and lexical file
handles.  I also made an attempt to produce more diffable texi files; I may
follow up with additional series along this line to make the documentation build
reproducibly.

Thanks.  We'd probably want INSTALL to talk about Asciidoctor once
this matures, as it is very simple requirement for the builder to
have to just set USE_ASCIIDOCTOR, but the version requirement and
stuff might be still confusing.