Front page | perl.perl5.porters |
Postings from March 2009
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