Front page | perl.perl5.porters |
Postings from December 2004
From: Michael G Schwern
December 25, 2004 11:52
Message ID: 20041225034250.GB17979@windhund.schwern.org
On Fri, Dec 24, 2004 at 08:57:14PM +0100, Juerd wrote:
> > > =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.
Ahh, I see what confused me.
Because you indented both the =head1 SYNOPSIS and the code itself I thought
you were using that whole thing as an example of a code paragraph, =head1
and all. I understand your intention now but the double indentation is
I dunno, I'm just confused.
> > 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?
Nahh, not terribly. And it turns out I was wrong anyway.
> > > 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.
Completeness isn't important in a 5 minute tutorial. Not overloading the
user with a bunch of marginally useful information is. Besides, I'm sure
POD entities and HTML entities have diverged, or will diverge, in other ways.
I think its sufficient to say "they have names like HTML entities, see
L<perlpod|Formatting Codes> for details.
> I kind of assumed everyone knows HTML entities, and at least lt and gt.
> Am I naive?
While writing up a comment to a different part of the document, I think it
was the code paragraphs, I considered suggesting an analogy to <pre> tags.
Then I realized lots of competant programmers don't know anything about
HTML. Or perhaps they've only ever used WYSIWYG editors.
Perl is a general programming language. As the main documentation should not
assume Unix knowledge, POD shouldn't assume HTML knowledge where it can
> 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 :)
Again, don't assume that everybody knows HTML.
But I really only bring up E<lt> and E<gt> against E<sol> in the sense that
if you're going to bring up any specific entities bring up gt and lt.
> > 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'd just not bring it up and punt this to L<perlpod|Formatting Codes>. I've
never used it.
> > > =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.
Its not about the indentation, its that in the unformatted POD the item
comes above the description, not on the left. Anyhow, like I said its
not a big deal either way.
> If this horizontal formatting is not discussed, I think no number should
> be in the example at all: the default is 4.
You could do that. I have a feeling something yells at you for doing that
> > 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.
Command line switches.
> > > =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?
I'd say this is largely out of the scope of this tutorial and just go
with current practise. Or you can just punt the whole issue.
Michael G Schwern firstname.lastname@example.org http://www.pobox.com/~schwern/
"Congratulations, you're a thieving bastard... Now give me back my pants."
"That's MISTER Pants!"
-- Ian's Adventures In Morrowind