Re: groff .ft command use in asciidoc

[Jonathan Nieder <jrnieder@gmail.com>]

Jeff King wrote:

> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -63,35 +63,28 @@ endif
[...]
> -#	-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