[PATCH 0/8] Documentation: XSLT/asciidoc.conf cleanup; tty literals

I had a go at wrangling with the documentation generation tools to fix a couple of issues that I had noticed.

First, I could never get reasonable output for generated manpages. I have asciidoc 8.3.1 and docbook-xsl 1.74.0 on my system. They chew through the documentation OK, but I was never sure which flags I should use with them.

ASCIIDOC8 never seemed to do much (I was probably not looking in the right places), but I decided to leave it enabled since it is entirely outside the scope of the git code/configuration.

The other variable was DOCBOOK_XSL_172, and no matter which way I turned it, I always got flawed output. If I set it, I would get funky characters in the callout sections. If I unset it, I would get ".ft C" and ".ft" bracketing literal blocks.

Second, the inline literal text of both the official and my generated manpages was indistinguishable from the surrounding text when viewing manpages in a terminal. It turns out the official manpages end up with no markup for inline literal text. The ones I generated did have some markup, but it was flagged as monospace text, which is not all that distinguishable from the normal, roman text when viewing through a terminal.

So I set about trying to solve these problems along with the meta-problem of code duplication between callouts.xsl and manpage-1.72.xsl.

The following series is my attempt to

  eliminate the XSLT code duplication,

  tease apart the uses of the "1.72" label that apply only to
    docbook-xsl 1.72 and those that also apply to some other
    versions of docbook-xsl,

  unify some of the items that look like they were applied to
    only one side of various "1.72" configurations but still
    seemed applicable to the other,

  fix a mostly unrelated, small, latent bug in asciidoc.conf,

  and provide an option to differentiate inline literal text when
    viewed on a terminal.

  Documentation/Makefile                 |   37 ++++++++++++++++++++++--
  Documentation/asciidoc.conf            |   15 +++++----
  Documentation/callouts.xsl             |   30 --------------------
  Documentation/manpage-1.72.xsl         |   28 ++++++------------
  Documentation/manpage-base.xsl         |   48 ++++++++++++++++++++++++++++++++
  Documentation/manpage-bold-literal.xsl |   17 +++++++++++
  Documentation/manpage-normal.xsl       |   12 ++++++++
  7 files changed, 129 insertions(+), 58 deletions(-)