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 -- 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