=head1 NAME
   
Test - Test POD for PerlMonks question

=head1 SYNOPSIS

  # download this code from PerlMonks, then
  perldoc test.pod

  # or, probably better...
  pod2html test.pod

=head1 ABSTRACT

Test POD for PerlMonks question

=head1 DESCRIPTION

Your question is a tough one. There isn't (according to the perlpod do
+cs) a
way to add a label to an area like there is in HTML, so it doesn't see
+m like
there's a way to 'jump to' a random place in the POD, which was my fir
+st
hope for an answer.

The good news is that some POD parsers (at least pod2html) can be tric
+ked
into doing the right thing. pod2html seems to label items 'item_itemna
+me' in
the pages it generates, and in the case of function names, it leaves t
+he
arguments out. So, to generate a link to such a function, just add
LE<lt>args_function()|/item_args_functionE<gt> to make a link like thi
+s one:
L<args_function()|/item_args_function>.

Unfortunately, this only seems to work for pod2html. pod2latex produce
+s a
link to the function with all of its arguments, so if you're planning 
+to use
that (or to make a POD doc that can be used with it), you're out of lu
+ck as 
far as I can tell.

See the documentation for the remaining() function for Another Way To 
+Do It.

=head1 FUNCTIONS

=over 4

=item noargs_function()

Text describing the noargs_function().

=item args_function($arg1,$arg2)

Text describing the args_function() . (Make sure there are no spaces b
+etween
the args there... it does funny things to the formatting, at least wit
+h
pod2html.)

=item remaining()

remaining() is the last function mentioned here, mostly to exhibit
pod2html's behavior of linkifying mentions of function names when ment
+ioned
in text. This should also serve your purposes, but be aware that chara
+cters  
(like the period in the noargs_function() item) touching the function 
+name
may cause this not to work. pod2latex doesn't appear to support this f
+eature
either.

=back
[download]

So, I changed some of them to just listing the method name in the headline, and put a illustrative parameter list and return value on the next line as a verbatim paragraph.

What's a better way to do it?

Actually, I think that is the better way of doing it :-) After some experimentation with various formats I've standardised on something like:

=item B<foo>

  $object->foo
  $object->foo($bar)

Do foo to $object using $bar, or undef if $bar is not specified.
[download]

The advantages for me are:

• I find it quite clear.

• You don't have to re-write indices/TOCs if you tweak the calling examples.

• It resolves the ambiguities of having multiple =item statements when you have multiple ways of calling a function.

Why use a bold tag around the item, too? Does that just look better on some particular translation?

In my documentation style that I've used in TeX and other formats, I found making the function name alone as a very noticable thing on the page is a good idea. This follows the same principle. I see, although Perl doesn't have overloading like C++, it still has multiple ways to call something that ought to be illustrated.

Why use a bold tag around the item, too? Does that just look better on some particular translation?

Yup. I find it makes it easier to spot methods when you're scrolling through a long document.

Re: Crash Course in POD

Also worth noting is the newest doc on pod, perlpodspec

____________________________________________________
** The Third rule of perl club is a statement of fact: pod is sexy.