Re: [PATCH 0/6] Doc: drop support for docbook-xsl before 1.74
- From
- Martin Ågren <martin.agren@gmail.com>
- Date
- Mar 31, 2020, 19:26 UTC
- Message-ID
- <20200331192600.588-1-martin.agren@gmail.com>
- In-Reply-To
- <20200330094513.GB1735224@coredump.intra.peff.net>
On Mon, 30 Mar 2020 at 11:45, Jeff King <peff@peff.net> wrote:
Show 6 quoted lines
> > 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.
Show 13 quoted lines
> > 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=~ [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[]