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

Re: perlpodtut

Thread Previous | Thread Next
Michael G Schwern
December 24, 2004 11:11
Re: perlpodtut
Message ID:
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-E<gt>bar>
>     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<>

email address?

Michael G Schwern
There's a Balrog in the woodpile.

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