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

Re: perlpodtut

Thread Previous | Thread Next
December 24, 2004 17:30
Re: perlpodtut
Message ID:
> >We use the C<=head1> .. C<=head4> commands. (They are called I<command
> >paragraphs officially. They are paragraphs because they're separated from
> >the rest of the POD by blank lines.)
> I dont see sufficient value in explaining the official name.

I do, and think it's *VERY* important to include such things.

Different people learn in different ways. For many, including myself, it
helps to see a name in one place and the same name used elsewhere. It
makes it easier to realise that the same thing is discussed.

Also, if I see where a word comes from, that helps me remember why the
word is used for what it's used for. You're not taking these pointers
away from me :)

They are:

* I<command paragraphs>
* "see together"
* I<verbatim paragraph>
* I<formatting code>
* I<indentlevel>

And actually every single word that can be seen as Perl jargon.

If something has a name, I think not using that name in documentation
about it is wrong. Names have a very specific purpose: identification.

Also, if you know that it's a command *paragraph*, that empty lines are
around it and that it can span multiple lines are implied. That's
certainly worth having there, for people with logically functioning minds.

>     all pod elements, including commands, are paragraphs ( ie 1 or
> more lines of text, surrounded by *empty* lines )

Not true. A formatting code is a POD element, but not a paragraph.

>     Conveying your document's logical structure is important, so use
> (the following) formatting commands to reflect your document outline.

The numbers in =head imply that. Everyone who writes documentation for
software, or is about to, knows how structured documents work, I think.

Let's not make this a "writing documents" tutorial. It's about POD, and
in specific, about using POD for code documentation.

>     formatting commands cannot be indented; the examples below are
> purposely indented to prevent their interpretation as formatting
> commands, so that you can read them literally.

A good example of why using the right names from the very beginning is

What is a "formatting command"?

[A] command paragraph
[B] formatting code
[C] either one of A, B

Anyway, assuming you meant A, the explanation of verbatim paragraphs
implies this entirely.

Please keep in mind that this is a very consise tutorial, not a guide or
a reference manual. Anything that can be determined by putting different
pieces of the information together, should IMHO not be explicitly
stated. The verbose version is in perlpod, if more hand holding or more
specific information is needed.

Possibly "crash course" is more appropriate than "tutorial", in the
title of this document. Comments?


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