Front page | perl.perl5.porters |
Postings from March 2009
Michael G Schwern <schwern@pobox.com> writes: > 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. I can try to tackle a perlpodstyle documentation page, which I can either ship with podlators or hand off to the Perl core team as makes the most sense. I'm somewhat handicapped by not having time to read perl5-porters, although I do read pod-people. > 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. Okay, I can live with that (and modify Pod::Man to strip B<> and I<> markup in NAME as well). As long as we don't go farther down that path and allow verbatim paragraphs, subheadings, or move away from the Name - Description syntax, you're certainly correct that formatters can cope. -- Russ Allbery (rra@stanford.edu) <http://www.eyrie.org/~eagle/>Thread Previous | Thread Next