Re: [PATCH] manpage-bold-literal.xsl: provide namespaced template for "d:literal"
From: Martin Ågren <hidden>
Date: 2019-10-31 06:19:45
On Wed, 30 Oct 2019 at 22:24, Jeff King [off-list ref] wrote:
On Wed, Oct 30, 2019 at 09:41:04PM +0100, Martin Ågren wrote:quoted
We recently regressed our rendering of "literal" elements in our manpages, i.e, stuff we have placed within `backticks` in order to render as monospace. In particular, we lost the bold rendering of such literal text.This is just when rendering with asciidoctor, right? AFAICT the bolding is still fine in pages built with asciidoc.
Right. Sorry for being unclear. Fixed in v2.
quoted
One reason this was not caught in review is that our doc-diff tool diffs without any boldness, i.e., it "only" compares text.I don't think this was intentional, but just a consequence of redirecting man's stdout to a non-terminal. Doing: MAN_KEEP_FORMATTING=1 ./doc-diff --asciidoctor HEAD^ HEAD on your patch shows the improvement, though note that the diffed version is kind of ugly. It looks like the bolding is done with ^H characters, and it interacts in a funny way with our diff coloring, as well as with diff-highlight if you use it. Piping the above through "less" looks decent, but it gives me pause on whether we should be setting that variable inside the script.
Very interesting! Thanks for this trick.
quoted hunk ↗ jump to hunk
Speaking of annoyances, is it just me, or does the rendering stage of doc-diff not actually proceed in parallel? Doing this seems to help, but I'm not sure why:diff --git a/Documentation/doc-diff b/Documentation/doc-diff index 88a9b20168..1694300e50 100755 --- a/Documentation/doc-diff +++ b/Documentation/doc-diff@@ -127,7 +127,7 @@ generate_render_makefile () { while read src do dst=$2/${src#$1/} - printf 'all:: %s\n' "$dst" + printf 'all: %s\n' "$dst" printf '%s: %s\n' "$dst" "$src" printf '\t@echo >&2 " RENDER $(notdir $@)" && \\\n' printf '\tmkdir -p $(dir $@) && \\\n'
Hm, didn't look into this. Will try to find the time.
I also confirmed with the MAN_KEEP_FORMATTING trick above that "doc-diff --asciidoctor" fixes the problem as advertised, and "--asciidoc" has no change at all.
Thanks!
quoted
There are more manpage-*.xsl -- manpage-suppress-sp.xsl looks like it would have the exact same problem. But before diving in too deep, I'd rather submit this one to see if it's in the right direction at all.It looks like a lot of them don't actually match on the namespaced tagnames, and so are OK. Some of them require special options to enable, so we wouldn't necessarily notice problems via doc-diff. From my brief look, I think suppress-sp is the only one that needs attention. I kind of wonder if we can just drop it. According to the Makefile comment, it's needed only for docbook 1.69.1-1.71.0. But 1.71.1 came out in 2006. Surely even RHEL7 or whatever ancient system people use is past that, right? :)
I also only had a brief look and realized I wouldn't know how to test with such a broken version, so I didn't feel comfortable mucking around with that file.
Or alternatively, as I've argued elsewhere, we could simply be a little more aggressive about deprecating old doc build tools. According to the Makefile, no extra settings are needed with docbook >1.73.0. That came out in 2007. I'd be willing to just call that the cutoff point, and anybody without it can install the pre-formatted pages.
Yeah, that makes sense. Martin