On Wed, 30 Oct 2019 at 22:24, Jeff King <peff@xxxxxxxx> wrote:
>
> On Wed, Oct 30, 2019 at 09:41:04PM +0100, Martin Ågren wrote:
>
> > 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.
> > 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.
> 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!
> > 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
