| Message ID | cover.1585486103.git.martin.agren@gmail.com (mailing list archive) |
|---|---|
| Headers | show |
| Series | Doc: drop support for docbook-xsl before 1.74 | expand |
Martin Ågren <martin.agren@gmail.com> writes: > 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. It certainly is long overdue to write off these versions as too old to matter. Thanks. Will queue.
On Sun, Mar 29, 2020 at 03:18:04PM +0200, Martin Ågren wrote: > In the documentation Makefile and a few helper conf and xsl files, we > carry various workarounds to make the docs build at all or to look > better with older docbook-xsl versions. Let's see if we can't just drop > that support. All of this seems to have been useful at one point, but I > doubt that anyone needs this nowadays. This was also suggested in [1]. 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. Thanks for splitting each version bump into its own patch. That made it a lot easier to see what we we're gaining from each one. I double-checked that there's no difference with doc-diff when using a modern asciidoc/docbook combo, though I'm sure you did as well. > 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). The very first example block in section 1.1 has some funny indentation, but that's true before or after. 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. -Peff
On 2020-03-29 at 13:18:04, Martin Ågren wrote: > In the documentation Makefile and a few helper conf and xsl files, we > carry various workarounds to make the docs build at all or to look > better with older docbook-xsl versions. Let's see if we can't just drop > that support. All of this seems to have been useful at one point, but I > doubt that anyone needs this nowadays. This was also suggested in [1]. > > The final commit in this series bumps the minimum required version of > docbook-xsl to 1.74.0, which is from June 2008. The whole series should > be a no-op unless you're on an older release than that. That said, I've > only tested this with the version that comes with my OS, 1.79.1. > > 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. This seems sane to me and I'm all for dropping support for a twelve-year-old version of the DocBook XSL stylesheets. On the odd chance that someone did need to download a newer version, this is a dependency that's easy to set up and build.
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=~ [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[]
On Tue, Mar 31, 2020 at 09:26:00PM +0200, Martin Ågren wrote: > 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.) I don't find "info" useful, either. The big thing it offers over "man" is actual hyperlinks, but linkgit attributes (the only thing we actually bother annotating) don't seem to actually become links! These days I'd expect most people interested in hyperlinking to just use HTML. I wouldn't be surprised if there's some emacs integration with info, though, so maybe people use it there. I dunno. I'd be happy to see all of the info bits go away. I've add brian to the cc, since he was the last person to touch texi stuff (though he may have just been doing it out of a sense of cleanup/duty). The .texi generated for the user-manual is the same before and after your patch, so I think it's OK to do. There _is_ an older regression in the user-manual, though. After commit 03920ac69b (asciidoctor: fix user-manual to be built by `asciidoctor`, 2017-01-02), the whole front-matter is missing from the generated "git.info" file, and there's a funky ": idm4" node. Nobody seems to have noticed or complained since then (though perhaps people are more likely to look at the manpages than the user manual). > -- >8 -- > Subject: [PATCH 7/6?] user-manual.conf: don't specify [listingblock] Yeah, this looks good to me (and it looks like Junio already picked it up on top of your series). -Peff
Jeff King <peff@peff.net> writes: >> Subject: [PATCH 7/6?] user-manual.conf: don't specify [listingblock] > > Yeah, this looks good to me (and it looks like Junio already picked it > up on top of your series). Yup, thanks, both.
On 2020-04-01 at 10:17:16, Jeff King wrote: > On Tue, Mar 31, 2020 at 09:26:00PM +0200, Martin Ågren wrote: > > > 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.) > > I don't find "info" useful, either. The big thing it offers over "man" > is actual hyperlinks, but linkgit attributes (the only thing we actually > bother annotating) don't seem to actually become links! These days I'd > expect most people interested in hyperlinking to just use HTML. I > wouldn't be surprised if there's some emacs integration with info, > though, so maybe people use it there. I dunno. I'd be happy to see all > of the info bits go away. I believe Emacs does have good integration with the info format. I personally prefer documentation in almost any other format and would also be happy to see it go away, but Emacs users may find it convenient. Junio, I believe you use Emacs. Do you have an opinion on whether, on the whole, Emacs users are likely to make good use of the info documentation? > I've add brian to the cc, since he was the last person to touch texi > stuff (though he may have just been doing it out of a sense of > cleanup/duty). I clearly see the commit in the history with my name on it and the explanation seems like something I might have written, but I have no recollection of touching that code or writing the patch at all. I very likely only touched it because I felt compelled not to introduce a regression (although, as you mentioned, I failed). > The .texi generated for the user-manual is the same before and after > your patch, so I think it's OK to do. > > There _is_ an older regression in the user-manual, though. After commit > 03920ac69b (asciidoctor: fix user-manual to be built by `asciidoctor`, > 2017-01-02), the whole front-matter is missing from the generated > "git.info" file, and there's a funky ": idm4" node. Nobody seems to have > noticed or complained since then (though perhaps people are more likely > to look at the manpages than the user manual). If nobody seems to care very much for the info documentation, we could drop it. I've put a query out on Twitter to see if anyone I know is using it.
"brian m. carlson" <sandals@crustytoothpaste.net> writes: > I believe Emacs does have good integration with the info format. I > personally prefer documentation in almost any other format and would > also be happy to see it go away, but Emacs users may find it convenient. > > Junio, I believe you use Emacs. Do you have an opinion on whether, on > the whole, Emacs users are likely to make good use of the info > documentation? I probably am very atypical; I used to read even system manuals via info in Emacs, but for the last 10 years or more, I don't. Another reason that makes me a bad judge is because I do not use our doc in any formatted form---"git grep -e ... Documentation/" is easier and faster. So, no, I have no opinion. > If nobody seems to care very much for the info documentation, we could > drop it. I've put a query out on Twitter to see if anyone I know is > using it. Thanks.