Front page | perl.perl5.porters |
Postings from March 2009
Russ Allbery wrote:
>> 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:
Ok, I trust that you know the man format well and give that it's wrong to put
formatting in the NAME section.
> 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.
> It's something that the man page author
> needs to be responsible for, in my opinion, not something that the
> converter can fix up.
Therein lies the problem. As a module author I write in POD, not man. I
don't have to or want to know any of this. I want some expert to figure out
how it should be translated into a man page or HTML or XML or a Windows help
file or spelled out in skywriting.
And I'm sure there's a line of Windows authors who would like to have words
about the idea that they're writing man pages.
And then what happens when another format decides it has its own set of
special cases it doesn't want to display?
The restrictions, details and worries of an individual format, even one as
important as man pages, should not bubble up to the POD author. Instead the
pod2x translator should take care of it. As the author of a glue module your
job is to make yourself miserable fussing over details like this to allow the
POD author to be ignorant, lazy and happy.
At minimum, Pod::Man can simply strip the offending formatting out.
[1] Just to make sure this is taken correctly, I mean this honestly.
--
170. Not allowed to "defect" to OPFOR during training missions.
-- The 213 Things Skippy Is No Longer Allowed To Do In The U.S. Army
http://skippyslist.com/list/
Thread Previous
|
Thread Next