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 paragraphs. > =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<http://juerd.nl/> email address? -- Michael G Schwern [EMAIL PROTECTED] http://www.pobox.com/~schwern/ There's a Balrog in the woodpile.
