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(-)
--
Chris
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
