Front page | perl.perl5.porters |
Postings from March 2009
Re: [PATCH] Markup in the NAME section is not portable
Thread Previous
|
Thread Next
From:
Russ Allbery
Date:
March 5, 2009 01:42
Subject:
Re: [PATCH] Markup in the NAME section is not portable
Message ID:
87bpsg9ugk.fsf@windlord.stanford.edu
Sorry for any weirdness in this reply. I'm replying to a cut and paste
from the web archives since I'm not subscribed. Please cc me on any
replies, as I'm not subscribed.
Michael G Schwern <schwern@pobox.com> writes:
> Niko Tyni wrote:
>> As discussed in [rt.cpan.org #43078] and Debian bug #304143, markup in
>> the NAME section of manual pages is not portable.
>>
>> In particular, the whatis parser on Debian cannot handle C<> in whatis
>> entries, resulting in garbage like
>>
>> c2ph (1) - Dump C structures as generated from *(C`cc - g - S*(C' stabs
>>
>> My tests indicate Solaris 10 and Tru64 5.1 are affected too.
>>
>> http://rt.cpan.org/Public/Bug/Display.html?id=43078
>> http://bugs.debian.org/304143
> According to that bug, the problem is the bad formatting in the man page
> which suggests a bug or impoliteness in Pod::Man and an inadequacy in
> whatis' roff parsing. Stripping C<> from the docs is just treating the
> symptom.
>
> It seems the patch to make Pod::Man more polite about C<> in NAME in
> 43078 is sufficient.
I'll argue the situation is exactly opposite. Stripping the C<> rendering
in pod2man is addressing the symptom; the actual bug is using markup of
any kind in the NAME section.
This is the same if one is writing directly in *roff. In the NAME section
of a UNIX manual page, you cannot use markup. That portion of a manual
page is special and needs to be parsed by much dumber software than the
rest of the page. It is supposed to contain only a plain text list of
programs/topics, a single dash (\- in *roff), and a pure text short
description. For example, man(7) on Debian:
The only mandatory heading is NAME, which should be the first section
and be followed on the next line by a one line description of the
program:
.SH NAME
It is extremely important that this format is followed, and that there
is a backslash before the single dash which follows the command name.
and more explicitly man(5) on Solaris:
.SH NAME
The name, or list of names, by which the command is called,
followed by a dash and then a one-line summary of the action
performed. All in roman font, this section contains no troff(1)
commands or escapes, and no macro requests. It is used to
generate the windex database, which is used by the whatis(1)
command.
I'll make this explicit in the pod2man man page in the next release of
podlators. There are many other types of markup that could be used in the
NAME section right now that would equally confuse man. Adding special
cases for all of them is unappealing from a Pod::Man perspective. B<> and
I<> are also incorrect, verbatim text is wrong, there shouldn't be
multiple lines in this section, subheadings aren't allowed, hanging
paragraphs aren't allowed, etc. It's something that the man page author
needs to be responsible for, in my opinion, not something that the
converter can fix up.
--
Russ Allbery (rra@stanford.edu) <http://www.eyrie.org/~eagle/>
Thread Previous
|
Thread Next