develooper Front page | perl.perl5.porters | Postings from March 2009

Re: [PATCH] Markup in the NAME section is not portable

Thread Previous | Thread Next
Michael G Schwern
March 5, 2009 15:14
Re: [PATCH] Markup in the NAME section is not portable
Message ID:
Russ Allbery wrote:
> Well, this is the key to this: when you write this documentation for Perl,
> are you writing man pages but using POD to write them instead of *roff, or
> are you writing some other type of documentation which we're converting
> into a man page?


> Maybe the best approach here would be to write a style guide specifically
> for POD documentation, laying out the expected sections and formatting
> requirements, that we could agree on as the recommended documentation
> style for Perl?  Then, people could rely on that without needing to worry
> too much about whether it matched some other external convention.
> (Obviously, for various reasons, I think it would be worthwhile if that
> style matched the UNIX man page style fairly closely, particularly since
> that's already the style that we're largely following, but it wouldn't
> need to match exactly and we could investigate places where the formatter
> should be able to correct, such as C<> markup in the NAME section.)

To answer your question at the top, I write Perl documentation.  I use perldoc
instead of man.  Guarantees I get the right version of the page and I know its
always going to work.

I agree there's no doubt that Perl module style is heavily derived from man
page standards.  It would be very nice to write those down.  pod2man is the
only place I believe anyone has tried.

It's important to distinguish between semantic information and formatting
information.  POD is mostly semantic (with exceptions like I<> and B<>) but it
doesn't have much.  We derive interesting semantics from conventions mostly
centered around =head.  Those are important to keep in line because they
provide more semantic information than POD alone.  The details of the
formatting, I still hold, is up to the formatters.  They provide little
semantic information and can easily be rendered or stripped out entirely by
the formatters.

Formatters can not add semantics but they can convert formats.  This is why
it's important to have a well defined NAME section but not necessary to
restrict what formatting (ie. B<> and C<> and all) can go in it.  The "Name -
Description" layout is important because it gives the formatter semantic
information.  Once the formatter decides "this bit is the name, this bit is
the description" it can render them however it likes doing whatever it needs
with the formatting tags.

So while discussing and nailing down the total layout of Perl documentation is
good, it's unnecessary to deciding about formats in NAME.  It's still up to
the formatter to decide.

Whip me, beat me, make my code compatible with VMS!

Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About