On 8 August 2016 at 17:42, Philip Oakley <[email protected]> wrote: > From: "Lex Trotman" <[email protected]> : Monday, August 08, 2016 1:00 AM > >> On 8 August 2016 at 09:29, <[email protected]> wrote: >>> >>> 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 e.g. >>> >>> 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" >> >> >> I very much suspect its the docbook-xsl thats the problem, but just >> check that the docbook from asciidoc is correct first. >> > The HTML version looks fine (which is the one I normaly see on > Git-for-Windows)
It would appear that the docbook-XSL http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl that converts the docbook to manpages has a bug. > >>> >>> 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 >>> >>> >>> -- >>> You received this message because you are subscribed to the Google Groups >>> "asciidoc" group. >>> To unsubscribe from this group and stop receiving emails from it, send an >>> email to [email protected]. >>> To post to this group, send email to [email protected]. >>> Visit this group at https://groups.google.com/group/asciidoc. >>> For more options, visit https://groups.google.com/d/optout. >> >> >> -- >> You received this message because you are subscribed to a topic in the >> Google Groups "asciidoc" group. >> To unsubscribe from this topic, visit >> https://groups.google.com/d/topic/asciidoc/lKamxEvmBzo/unsubscribe. >> To unsubscribe from this group and all its topics, send an email to >> [email protected]. >> To post to this group, send email to [email protected]. >> Visit this group at https://groups.google.com/group/asciidoc. >> For more options, visit https://groups.google.com/d/optout. >> > > -- > You received this message because you are subscribed to the Google Groups > "asciidoc" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > To post to this group, send email to [email protected]. > Visit this group at https://groups.google.com/group/asciidoc. > For more options, visit https://groups.google.com/d/optout. -- You received this message because you are subscribed to the Google Groups "asciidoc" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at https://groups.google.com/group/asciidoc. For more options, visit https://groups.google.com/d/optout.
