Re: [docbook-apps] manpage stylesheets generating bad font commands (\F)

[Michael Smith <smith@xml-doc.org>]

Paul DuBois <paul@kitebird.com> writes:

[...]
>   <refsection>
>     <title>Description of <command>some-program</command></title>
[...]
> .SH "DESCRIPTION OF \\FBSOME\-PROGRAM\\FR"
[...]
> Note that the .SH DESCRIPTION line contains \F rather than \f for the
> font commands. (That is, \f has gotten capitalized along with the rest of
> the section header text.)

Thanks for reporting it. I have fixed it. Please try the latest
snapshot:

  http://docbook.sourceforge.net/snapshots/

I fixed it by adding a new match to the man.string.subst.map param -

  http://docbook.sourceforge.net/snapshots/xsl/doc/manpages/man.string.subst.map.html

That fix is a sort of a hack. But then the whole
man.string.subst.map param is a sort of a hack. I use it for doing
cleanup of stuff it otherwise would take a lot more work to try to
get output correctly.

> I suppose this might be insignificant, given that .SH generates
> boldface anyway. Older manpage stylesheets appear to strip the
> font commands, which at least doesn't result in warnings when
> the manpage is formatted:

I can see some value in just stripping out the font requests. But
I also can imagine that there might be some intances where
somebody wants them preserved.

I personally tend to avoid the problem altogether by only putting
text content in my Title's in my DocBook source[1]. I find that
having Titles that contain element content that causes character
formatting can result in undesirable effects in HTML and PDF
output as well.

> % groff -man some-program.1 >/dev/null
> some-program.1:15: warning: can't find font `BB'
> some-program.1:15: warning: can't find font `RB'

If possible, please always test with the man command directly
in addition to (or instead of) doing "groff -man". That is:

  man ./some-program.1

Make sure you put the "./" in front of the filename. That tells
the (modern) man command to look in a local directory instead of
looking in its default search path.

The reason is, I have run into several cases where output from
"groff -man" differs from output of the man command. Running with
the man command directly is the only way to tell what your users
are actually going to see.

  --Mike

[1] In your example file, I can see why you might want to mark up
    a command as a Command even when it appears in a title. But I
    tend to think of the content of a Title as a single string
    literal, without much value in it containing any element content.

-- 
Michael Smith
http://sideshowbarker.net/

smime.p7s