"brian m. carlson" <sandals@xxxxxxxxxxxxxxxxxxxx> 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.