Re: [PATCH 0/6] Doc: drop support for docbook-xsl before 1.74

["Martin Ågren" <martin.agren@gmail.com>]

On Mon, 30 Mar 2020 at 11:45, Jeff King <peff@peff.net> wrote:
>
> On Sun, Mar 29, 2020 at 03:18:04PM +0200, Martin Ågren wrote:
>
> Yay, I'm very happy to see this series. I'd be happy to go even further
> if there's some benefit, but I think this removes the last of the
> Makefile knobs.

Yes, I should have been clear about that: This does remove the last
Makefile knob. At least I couldn't find any more with some browsing and
grepping.

> > After this series, user-manual.conf still refers to older docbook-xsl
> > versions. The proper fix there might be to actually be a bit more
> > aggressive and drop that hunk, making the rendered docs prettier.
> > There's some history there, including mentions of texinfo, which is
> > outside my comfort zone. I've got work in progress there, but I'd rather
> > submit that separately from these "expected no-op" patches.
>
> Yeah, dropping that bit from user-manual.conf seems reasonable. That
> shouldn't show anything in doc-diff because it's not installed with the
> manpages. And the HTML build wouldn't use docbook. I installed the
> zillion packages needed to build user-manual.pdf. The behavior without
> that block looks significantly nicer (the example blocks are actually
> shaded).

This matches what I've seen.

> Anyway, that was just for my own curiosity. If you've got further work
> in that area and prefer to do it as a separate series, that's fine by
> me.

Not sure about "further work" really. I'm pretty sure you tried out the
exact same diff that I have, and I'm glad you agree it looks prettier /
"significantly nicer". A small part of why I didn't submit it is that
it's user manual vs man pages. Another part is that it's an intentional
change as opposed to an intended no-op.

But most importantly: When I looked into the history, I came upon
c2a7f5d438 ("docs: monospace listings in docbook output", 2012-08-07),
which made me worry about breaking "make info". On second thought, I
might have broken it many times already over the past few years, since
I've never built the info. So maybe worrying about that all of a sudden
is a bit unfounded in a way. :-/

(I tried to build "info" while working on this. It works in the sense
that it doesn't error out, but I don't get anything that looks remotely
useful. I've never used info at all though, to be honest, so could be
missing something fundamental.)

Here's what I have. I suppose it could be framed as a patch 1/7 instead.

Martin

-- >8 --
Subject: [PATCH 7/6?] user-manual.conf: don't specify [listingblock]

This is the config file we use when we build the user manual with
AsciiDoc. The comment at the top of this chunk that we're removing says
the following:

  "unbreak" docbook-xsl v1.68 for manpages (sic!). v1.69 works with or
  without this.

This comes from d19fbc3c17 ("Documentation: add git user's manual",
2007-01-07), where it looks like this conf file in general and this
snippet in particular was copy-pasted from asciidoc.conf.

This chunk is very similar to something we just got rid of for the
manpages, and because this appears to be aimed at v1.68 -- which we no
longer support for the manpages as of a few commits ago --, it's
tempting to get rid of this. That reveals an interesting aspect of
"works with or without this": it turns out it actually works /better/
without!

Dropping this makes us render code snippets and shell listings using
<screen> rather than <literallayout>, just like Asciidoctor does. In
user-manual.pdf, this puts the contents into dimmed-background,
easy-to-distinguish-from-the-surrounding-text boxes, as opposed to
white-background (transparent) boxes.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/user-manual.conf | 10 ----------
 1 file changed, 10 deletions(-)

diff --git a/Documentation/user-manual.conf b/Documentation/user-manual.conf
index d87294de2f..0148f126dc 100644
--- a/Documentation/user-manual.conf
+++ b/Documentation/user-manual.conf
@@ -9,13 +9,3 @@ tilde=&#126;
 
 [linkgit-inlinemacro]
 <ulink url="{target}.html">{target}{0?({0})}</ulink>
-
-ifdef::backend-docbook[]
-# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this.
-[listingblock]
-<example><title>{title}</title>
-<literallayout class="monospaced">
-|
-</literallayout>
-{title#}</example>
-endif::backend-docbook[]