how should manpage 2nd level headings include quoted code?

["Philip Oakley" <philipoakley@iee.org>]

Hi,

While preparing a Git documentation update it has been brought to my
attention that the manpage output for a second level heading isn't
propagating the bold to the end of the line when the heading contains a
coded code segment. Example below.

I've raised the issue on the asciidoc list
(https://groups.google.com/forum/#!topic/asciidoc/lKamxEvmBzo), who
confirmed the issue is one level down in the docbook XSL, hence asking here
(is this the right docbook list for this?)

If it's a confirmed bug, how best to report it, as I'm a little out of my
depth at this point.
Philip
--

Example-

Other '<rev>{caret}' Shorthand Notations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This was analysed by one of the devs who said
(https://www.mail-archive.com/git%40vger.kernel.org/msg98190.html):-


On Tue, Jul 12, 2016 at 10:41:35PM +0100, Philip Oakley wrote:

> > > +The '{caret}' (caret) notation
> > > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > >   To exclude commits reachable from a commit, a prefix '{caret}'
> > >   notation is used.  E.g. '{caret}r1 r2' means commits reachable
> > >   from 'r2' but exclude the ones reachable from 'r1'.
> >
> > All of these headings render poorly in the manpage, at least for me
> > (Ubuntu 16.04).  Only the first word appears in bold; the '-quoted text
> > is not bold but underlined, and the rest of the header is plain.
>
> Which doc package is that with? It had formatted OK for the html web
> pages.

I get the same with:

 make gitrevisions.7
 man -l gitrevisions.7

Asciidoc 8.6.9, docbook-xsl 4.5 if it matters.

Rendering single-quotes as underline is normal in this case (though it's
not great for punctuation like this, as it kind of blends with the dots;
I know we use it elsewhere in this document, though).  The failure to
continue the bold through the end of line looks like a bug, though.

The generated XML (from asciidoc) looks reasonable:

 <title>The <emphasis>..</emphasis> (two-dot) range notation</title>

The roff looks like:

 .SS "The \fI\&.\&.\fR (two\-dot) range notation"

The "\fR" switches us back to "Roman" from italics, which is presumably
the problem. We really want to say "switch back what we were using
before \fI".

Switching it to "\fP" fixes it, but it's not clear to me if that's
actually portable, or a groff-ism. I don't know roff very well and
documentation seems to be quite hard to find. So it's either a bug in
docbook, or an intentional decision they've made because roff can't
portably do better. I'm not sure which.


Should the formatting work for manpages? if not, what to do?
--
Philip