develooper Front page | perl.perl5.porters | Postings from December 2004

perlpodtut II

Thread Next
From:
Juerd
Date:
December 27, 2004 03:37
Subject:
perlpodtut II
Message ID:
20041226210135.GW9912@c4.convolution.nl
Attached is the revised version of perlpodtut, based on your well
appreciated feedback. The second attachment is the diff with the
previous version.

I removed the derivation of SYNOPSIS. Not because I agree that it has no
place here, but because consistency would demand that more words are
explained, like abstract (abstractus), and caveat (cavere), but also
every day words like description (de-scriptus) and credit (creditum),
and I think that would go too far.

Even though I agree that =head3 is nice for method lists, perlpodtut
still uses =over/=item/=back, for two reasons: =head3 is not (yet)
common use, and using =head3 for this would greatly increase
perlpodtut's length and weight. I have, however, added a short paragraph
about =head3.

COPYRIGHT and LICENSE are now mentioned separately. The example LICENSE
section is now the popular "same terms as Perl itself" statement. I
think we should debate whether releasing something with a vague license
like that (unless it is part of the Perl distribution) is smart, but
because it is used so much and advised by pod2man, for now, perlpodtut
will use this in its example.

The example AUTHOR is now A. U. Thor, inspired by h2xs. h2xs uses a
comma between "A. U. Thor" and "<author@a.galaxy.far.away>", but I think
that's ugly.

A reference to pod2man's documentation was added, because it documents
more than just the formatter.

I changed the POD file, not the MetaMarkup file. As a result,
http://juerd.nl/site.plp/perlpodtut (http://juerd.nl/perlpodtut) is no
longer up to date. Attached is the most recent version, but those who
find a HTML-ified version easier to read can use
http://juerd.nl/perlpodtut.html (don't forget ".html").


Juerd

Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About