Front page | perl.perl5.porters |
Postings from December 2004
From: Michael G Schwern
December 24, 2004 11:11
Message ID: 20041224191154.GB17356@windhund.schwern.org
On Fri, Dec 24, 2004 at 11:12:05AM +0100, Juerd wrote:
> =head2 Code examples
> Indented paragraphs render as code, with indenting intact. It's that easy!
What does it mean for something to render as code? I think a reader will
better understand "with no extra formatting" or "as plain text".
> =head1 SYNOPSIS
> use My::Module;
> my $object = My::Module->new();
> print $object->as_string;
> This is called a I<verbatim paragraph>.
I would use a different example here for the code paragraph. Something
less likely to be confused by the reader and more like what they'll
actually use code paragraphs for. Perhaps some code? :)
However, it is worth pointing out that POD markup is not rendered in code
> =head2 Markup
> POD supports a small set of markup elements. To keep my time promise, I'll just
> list them:
> B<bold text here>
> I<italic text here>
> U<underlined text here>
> C<code text here>
> B<and you can I<nest> them>
> And there are F, S, X and Z, but they're rarely used so not worth explaining in
> a simple tutorial.
F<> is, I think, what you're supposed to use for URLs and email addresses
and the like (in addition to filenames).
> If you ever need to include a C<< > >> character within a I<formatting code>,
> you have two options. If you want to render C<< $foo->bar >> in a code font,
> this is what you can do:
> C<< $foo->bar >> (inner whitespace is required!)
> C<<< $foo->bar >>> (inner whitespace is required!)
This should go below Entities since E<gt> hasn't been mentioned yet.
> =head2 Entities
> You saw how E can be used for entities. These are like HTML entities, with the
> addition of I<verbar> for a vertical bar and I<sol> for a slash (solidus).
I don't know if verbar and sol are worth bringing up. I've never even
realized they existed. If you're going to mention any entities, mention
the two most common. E<gt> and E<lt>
> Numeric entities are decimal, octal (prefixed with 0) or hexadecimal (prefixed
> with 0x).
This might need a example. Do they come out as numbers or are they ASCII
representations of characters? Not clear.
> =head2 Lists
> An example is much clearer than an explanation here.
> =head2 Methods
> =over 12
Without getting into a style war, I'd suggest =over 4 simply because its
more common and the formatting of the rendered POD is closer to what the
user typed in. Less difference, less confusion.
And fwiw I've recently switched from =item B<new> to =head3 new because I
keep forgetting the B<> and having to futz with =over and =back. This
style might be simpler for newbies for their method documentation.
> =head1 LICENSE
> This is released under the Artistic License. See L<perlartistic>.
Since people like to cut & paste, this should probably be the standard
"same as Perl" wording plus a copyright notice.
> =head1 AUTHOR
> Juerd - L<http://juerd.nl/>
Michael G Schwern firstname.lastname@example.org http://www.pobox.com/~schwern/
There's a Balrog in the woodpile.