git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: "Martin Ågren" <martin.agren@gmail.com>
To: Jeff King <peff@peff.net>
Cc: git@vger.kernel.org
Subject: Re: [PATCH 0/6] Doc: drop support for docbook-xsl before 1.74
Date: Tue, 31 Mar 2020 21:26:00 +0200	[thread overview]
Message-ID: <20200331192600.588-1-martin.agren@gmail.com> (raw)
In-Reply-To: <20200330094513.GB1735224@coredump.intra.peff.net>

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


  reply	other threads:[~2020-03-31 19:26 UTC|newest]

Thread overview: 16+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-03-29 13:18 Martin Ågren
2020-03-29 13:18 ` [PATCH 1/6] Doc: drop support for docbook-xsl before 1.71.1 Martin Ågren
2020-03-29 13:18 ` [PATCH 2/6] Doc: drop support for docbook-xsl before 1.72.0 Martin Ågren
2020-03-29 13:18 ` [PATCH 3/6] Doc: drop support for docbook-xsl before 1.73.0 Martin Ågren
2020-03-29 13:18 ` [PATCH 4/6] manpage-bold-literal.xsl: stop using git.docbook.backslash Martin Ågren
2020-03-29 13:18 ` [PATCH 5/6] manpage-normal.xsl: fold in manpage-base.xsl Martin Ågren
2020-03-29 13:18 ` [PATCH 6/6] INSTALL: drop support for docbook-xsl before 1.74 Martin Ågren
2020-03-30  9:26   ` Jeff King
2020-03-29 16:27 ` [PATCH 0/6] Doc: " Junio C Hamano
2020-03-30  9:45 ` Jeff King
2020-03-31 19:26   ` Martin Ågren [this message]
2020-04-01 10:17     ` Jeff King
2020-04-01 16:59       ` Junio C Hamano
2020-04-02  0:45       ` brian m. carlson
2020-04-02 16:48         ` Junio C Hamano
2020-03-30 10:46 ` brian m. carlson

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200331192600.588-1-martin.agren@gmail.com \
    --to=martin.agren@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=peff@peff.net \
    --subject='Re: [PATCH 0/6] Doc: drop support for docbook-xsl before 1.74' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).