Re: [docbook-apps] how should manpage 2nd level headings include quoted code?
Thanks Bob (and Mike),
So essentially it's one of those 'can't fix' bugs which uses the least worst
solution.
Are ou aware of any other construct that could be used instead (though it
does need to come down via asciidoc) that might be suitable? Using the
customisation route for the Git doc probably won't be accepted, as this
would be just one special case in the middle of all the other 'working'
docs.
One thought I just had for my case is simply to move the quoted text to the
end of the heading, so at least the boldness isn't split.
e.g.
Other Parent Shorthand Notations '{caret}'
~~
or even "just don't quote it".
Thanks
Philip
From: "Bob Stayton" Monday, August 08, 2016 9:32 PM
Hi Philip,
This is the right place to report this issue. Reaching way, way back in
my memory, I seem to recall that while \fP will work in simple cases to
restore the previous font, it does not work when inline font changes are
nested. For example:
the sequence ‘‘\fB...\fR...\fI...\fP...\fP’’
will result in italics afterward instead of bold. That's because the font
changes are not a true stack, just a single "previous" font. The first fP
(reading left to right) restores fR, but also places fI in the memory slot
as the previous font. So the second fP uses that when it restores from
fR, resulting in text after the string being in italic instead of the
intended bold.
Without a true stack, there is no complete solution using XSL 1.0. Because
DocBook allows many combinations of nested inline elements, I think that
using fR created fewer problems than fP.
That said, you can experiment with a DocBook customization layer for your
output to see if fP works better for you. In the DocBook stylesheet
module manpages/utility.xsl, there is a template named "italic" that use
fR:
\fI
\fR
If you copy that to your customization layer and change fR to fP, it
should work for the instance you describe. But then you need to look for
any side effects from nested inline elements. The symptom would be
similar: leaving the rest of the block in the wrong font.
Creating a DocBook customization layer is described here:
http://www.sagehill.net/docbookxsl/CustomMethods.html#CustomizationLayer
Bob Stayton
Sagehill Enterprises
b...@sagehill.net
On 8/8/2016 12:28 PM, Philip Oakley wrote:
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 '{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:
The .. (two-dot) range notation
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
Re: [docbook-apps] how should manpage 2nd level headings include quoted code?
On 2016-08-08 16:32, Bob Stayton wrote: ...I seem to recall that while \fP will work in simple cases to restore the previous font, it does not work when inline font changes are nested. For example: the sequence ‘‘\fB...\fR...\fI...\fP...\fP’’ will result in italics afterward instead of bold. That's because the font changes are not a true stack, just a single "previous" font. IIUC, this is the reason that LaTeX (an entirely different typesetting system, of course) now discourages the use of the old commands \it and \bf, in favor of \textit, textbf etc. Mike Maxwell - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] how should manpage 2nd level headings include quoted code?
Hi Philip,
This is the right place to report this issue. Reaching way, way back in
my memory, I seem to recall that while \fP will work in simple cases to
restore the previous font, it does not work when inline font changes are
nested. For example:
the sequence ‘‘\fB...\fR...\fI...\fP...\fP’’
will result in italics afterward instead of bold. That's because the
font changes are not a true stack, just a single "previous" font. The
first fP (reading left to right) restores fR, but also places fI in the
memory slot as the previous font. So the second fP uses that when it
restores from fR, resulting in text after the string being in italic
instead of the intended bold.
Without a true stack, there is no complete solution using XSL 1.0.
Because DocBook allows many combinations of nested inline elements, I
think that using fR created fewer problems than fP.
That said, you can experiment with a DocBook customization layer for
your output to see if fP works better for you. In the DocBook
stylesheet module manpages/utility.xsl, there is a template named
"italic" that use fR:
\fI
\fR
If you copy that to your customization layer and change fR to fP, it
should work for the instance you describe. But then you need to look
for any side effects from nested inline elements. The symptom would be
similar: leaving the rest of the block in the wrong font.
Creating a DocBook customization layer is described here:
http://www.sagehill.net/docbookxsl/CustomMethods.html#CustomizationLayer
Bob Stayton
Sagehill Enterprises
b...@sagehill.net
On 8/8/2016 12:28 PM, Philip Oakley wrote:
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 '{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:
The .. (two-dot) range notation
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
-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
[docbook-apps] how should manpage 2nd level headings include quoted code?
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 '{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:
The .. (two-dot) range notation
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
-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
