[Doc-SIG] Re: POD

[Tim Peters]

[Guido]
> If the amount of markup is as light as suggested by Greg's examples, I
> have no problem reading POD.

Greg's markup was above the norm, in my experience.  Tom Christiansen writes
POD docs with minimal markup, like (from tchrist's Net::hostent):

------

=head1 DESCRIPTION

This module's default exports override the core gethostbyname() and
gethostbyaddr() functions, replacing them with versions that return
"Net::hostent" objects.  This object has methods that return the similarly
named structure field name from the C's hostent structure from F<netdb.h>;
namely name, aliases, addrtype, length, and addr_list.  The aliases and
addr_list methods return array reference, the rest scalars.  The addr
method is equivalent to the zeroth element in the addr_list array
reference.

You may also import all the structure fields directly into your namespace
as regular variables using the :FIELDS import tag.  (Note that this still
overrides your core functions.)  Access these fields as variables named
with a preceding C<h_>.  Thus, C<$host_obj-E<gt>name()> corresponds to
$h_name if you import the fields.  Array references are available as
regular array variables, so for example C<@{ $host_obj-E<gt>aliases()
}> would be simply @h_aliases.

------

So he doesn't bother wrapping function and module names in markup *except* in
actual code examples, leaving it to the reader to figure out that a trailing
"()" means he's talking about a function and that embedded "::" means a Perl
namespace gimmick, etc.  I really don't need a different font to tell me
that!  But markup is essential to distinguish, e.g., the English word "use"
from the Perl statement C<use> -- and this very paragraph is suitable input
to POD for showing the difference <wink -- and including the <wink>s>.

> ...
> The secret seems to be that their markup is so simple that you very
> quickly learn to recognize it, and it's pretty minimal.

Bingo!  It's not *obvious* at first glance, but the effort required to learn
it is truly minimal.  However, as with many things Perlish, the effort of
figuring out what it actually *does* in all cases is the basis for a lifetime
of adventure <0.9 wink> ...