Re: [PATCH] manpage-bold-literal.xsl: provide namespaced template for "d:literal"

["Martin Ågren" <martin.agren@gmail.com>]

On Wed, 30 Oct 2019 at 22:24, Jeff King <peff@peff.net> 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