Re: groff .ft command use in asciidoc
- From
Jonathan Nieder <jrnieder@gmail.com>
- Date
- Nov 19, 2010, 18:22 UTC
- Message-ID
- <20101119182230.GA26187@burratino>
- In-Reply-To
- <20101119175424.GA13276@sigill.intra.peff.net>
Jeff King wrote:
> --- a/Documentation/Makefile > +++ b/Documentation/Makefile > @@ -63,35 +63,28 @@ endif
[...]
Show 7 quoted lines
> -# -1.68.1, set ASCIIDOC_NO_ROFF? (based on changelog from 1.73.0) > -# 1.69.0, no extra settings are needed? > +# -1.68.1, no extra settings are needed? > +# 1.69.0, set ASCIIDOC_ROFF? > # 1.69.1-1.71.0, set DOCBOOK_SUPPRESS_SP? > -# 1.71.1, no extra settings are needed? > +# 1.71.1, set ASCIIDOC_ROFF?
I would like to see these question marks go away. I believe the initial introduction of ASCIIDOC_NO_ROFF happened conservatively: i.e., do not change anything unless this particular toolset requires the change. Which is a shame, because it means it is not obvious what ASCIIDOC_ROFF is working around.
*does some digging*
The story begins with v1.3.0-rc1~45^2 (Tweak asciidoc to work with broken docbook-xsl, 2006-03-05). The [listingblock] style, used for listings like:
-------------------- $ ls foo bar baz --------------------
is meant to be rendered with the <screen> tag, but apparently DocBook XSL 1.68.1 does not and 1.70.1 does treat <screen> as a verbatim environment as it should. See <http://bugs.debian.org/375503>. The patch swapped in another verbatim environment, <literallayout>.
The result is a regression in another aspect from <screen>: namely, <screen> uses monospace text. v1.5.2.5~6 (Force listingblocks to be monospaced in manpages, 2007-07-18) worked around that by introducing some raw nroff, since this codepath is only used for manpages anyway.
The rest is history. docbook-xsl 1.72 broke the traditional method for passing raw roff through. It had a hole that let you do it some other way. Later versions of docbook-xsl forbid passing through raw roff escapes altogether.
Given all that, I suspect (but haven't checked) that the only knob we would need to cover all historically supported versions of DocBook is
DOCBOOK_MESSES_UP_SCREEN_TAG = YesUnfortunately
to be set with docbook versions in the 1.68 series. Everyone else can use <screen>, with the <literallayout> fixup to add some space after it.
> However, I think it is worth it to avoid the hassle for the vast > majority of people on modern systems.
Yes! Your patch takes care of that, so ack.
Thanks, Jonathan