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

Re: perlpodtut

Thread Previous | Thread Next
December 24, 2004 13:07
Re: perlpodtut
Message ID:
Michael G Schwern skribis 2004-12-24 14:11 (-0500):
> > 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".

You're right. Same is true for "a code font" (discussion of C<>). For
some reason, it was natural to me, but if I google for "a code font", I
find list of HTML tags (<A>, <CODE>, <FONT>) and perlpodtut itself :)

> >     =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? :)

Isn't example code very likely to be exactly what code/verbatim
paragraphs are used for? 

Or isn't the "use ... as_string;" not code?

Sorry, I have no idea what you mean.

> However, it is worth pointing out that POD markup is not rendered in code
> paragraphs.

It is.

> F<> is, I think, what you're supposed to use for URLs and email addresses
> and the like (in addition to filenames).

Does that matter for a 5 minute tutorial?

And is it used much? AFAICT, C<> and I<> are more often used for file
names, L<> is used for URLs and email addresses are usually just in <>
or the unnecessary E<lt>E<gt>.

> >     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.

I disagree. Sometimes, with very clear examples that are impossible to
misinterpret, giving the example first is better. I think this is one of
those situations. It makes explaining the entities easier.

> 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>

They're not really worth bringing up, but with one sentence, all of E<>
instead of just most of it, could be covered.

I kind of assumed everyone knows HTML entities, and at least lt and gt.
Am I naive?

Besides, the example given above displays E<gt> already. Anyone
incapable of realising that E<lt> is its counterpart, especially in a
Perl context, should probably not be using POD at all :)

> This might need a example.  Do they come out as numbers or are they ASCII
> representations of characters?  Not clear.

I currently can't think of a good way to clarify this. Suggestions are

(I don't even know if any charset is assumed.)

> >     =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.

I don't understand where the "what the user typed in" comes from.
Neither =over and =item nor the definition paragraphs are indented.

I personally like the way pod2man and pod2text render things
horizontally when possible. 

If this horizontal formatting is not discussed, I think no number should
be in the example at all: the default is 4.

> 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.

I don't think B<>'s are a good idea, even. It might be a better idea for
method documentation (please discuss this further - I have no specific
opinion re this), but still some list needs to be in the tutorial to
show how it works, and most non-method lists do not have normal
paragraphs in between =items.

So if you think methods should be in head3s, please come up with another
good example for =over/=item/=list. 

> >     =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.

IANAL, but I don't think the "same as Perl" wording is legal, even. And
if it's legal, it's certainly dangerous: a license change in Perl has
effect on your code, possibly without you knowing it.

I'm also not too sure about copyright notices. Are they useful? Isn't
everything covered by copyright by default anyway?

Perhaps it's better to leave out the example, and not suggest any
default license. People should think about this and not copy and paste.

> >     Juerd - L<>
> email address?

I'm thinking of removing my email address entirely from all my modules,
because module documentation is too wide spread. Anyone with at least a
nanobrain can find out many ways to contact me.

As long as there's contact information on (and there will be
for as long as I have this domain), the website URL is a good


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