Beefy Boxes and Bandwidth Generously Provided by pair Networks
good chemistry is complicated,
and a little bit messy -LW
 
PerlMonks  

Re: Crash Course in POD

by PodMaster (Abbot)
on Sep 25, 2002 at 08:23 UTC ( #200583=note: print w/replies, xml ) Need Help??


in reply to Crash Course in POD

The other fella have pointed you to the meat of the subject (perlpod and perlpodspec), and I'd like to point you to Pod::Tree (watchout for pod2html being overwritten, edit the makefile and don't install any of the scripts, they're interdependent, and will install the missing ones) and Pod::Html (fyi: i like Pod::Simple very much, as well as ActivePerl::DocTools).

Nobody reads pod in pod format.

Pod is best kept with the sourcecode, that way synchronization doesn't become a problem. If the pod is staring you in the face, at the same time as the sourcecode, it's hard to ignore mismatches ;)

Any stuff you put in external pod files (.pod) should be tutorial like material (extended documentation) ~ the api spec should be in with the module (.pm )

Aside from that, don't get fancy with the pod (avoid =begin exoticFormat , bah!). Keep it simple.

Here are a few modules with pod that I wrote ;)

HTML::LinkExtractor ~ a good pod example. I most like to read pod produced by Pod::Html, cause it makes a nice TOC at the top (like you can see there).

If you look at the source, you'll see that the pod is at the __END__. Since this was a very short module, it makes little difference, but for bigger modules, it will definetly be harder to manage __END__ pod, so you'll wanna use inline pod , like:


=head1 NAME

The name Is ~ And it does this in one line of desc

=head1 DESCRIPTION

You know.
See L<"new"> aka See L<the newest|"new">

=head1 SYNOPSIS

a short usage example (at least I like to keep it short)

    use Foo::Bar;
    my $foo = new Foo::Bar ( Foo => 'required' );
    die $foo->Bar;


=head1 METHODS (or Functions ;))

A little blurb about the methods/functions or the overall
interface of the thingamajigger ;)

=cut


use strict;

...

=head2 C<new>

The constructor.  The only class method. Takes 4 arguments.

=over 4

=item Foo

Required argument, cause Bar bar bar Baz!

...

=back

=cut

sub new {
  ...
}

...

1;
# the end of the code
# I try not to put an __END__ token here cause mod_perl
# generally doesn't like that

=head1 SEE ALSO

L<Foo::Bar::Tutorial>, L<perlpod|Pod::perlpod>, L<perlpodspec|Pod::perlpodspec>

=head1 LICENSE

This software is released under the same terms as perl itself.
If you don't know what that means visit http://perl.com/

=head1 AUTHOR

Copyright (c) A. U. Thor 
All rights Reserved

=cut
Which when viewed through Pod::Html turns into:

NAME

The name Is ~ And it does this in one line of desc


DESCRIPTION

You know. See new aka See the newest


SYNOPSIS

a short usage example (at least I like to keep it short)

    use Foo::Bar;
    my $foo = new Foo::Bar ( Foo => 'required' );
    die $foo->Bar;


METHODS (or Functions ;))

A little blurb about the methods/functions or the overall interface of the thingamajigger ;)

new

The constructor. The only class method. Takes 4 arguments.

Foo
Required argument, cause Bar bar bar Baz!

...


SEE ALSO

the Foo::Bar::Tutorial manpage, perlpod, perlpodspec


LICENSE

This software is released under the same terms as perl itself. If you don't know what that means visit http://perl.com/


AUTHOR

Copyright (c) A. U. Thor All rights Reserved


 

Now that is gravy right there ;)(that's the way i'd lay it out). It is important to remember not to document methods that the user of your module should not be calling directly. Use #c#o#m#m#e#n#t#s# for those.

Pod::Stripper ~ a bad example, mostly cause they're test cases ;)(deep pod voodoo, cause perl's idea of pod is different ~ perlpod/perlsyn explains)

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

Replies are listed 'Best First'.
Re^2: Crash Course in POD
by Aristotle (Chancellor) on Sep 25, 2002 at 15:50 UTC
    It is important to remember not to document methods that the user of your module should not be calling directly. Use #c#o#m#m#e#n#t#s# for those.
    Or you can steal Larry's own trick used while writing Camel III (which was done in POD): he "hid" little notes to self by using =for later. Or in this case, one might use =for internal use only. I prefer this over comments for two reasons. It is still accessible to POD tools if so chosen and can be extracted/marked up for an extended documentation. Secondly, it is a clear signal to human readers, more so than just mere comments.

    Makeshifts last the longest.

      IIRC, the Camel wasn't written in POD. It was written in POD + extensions, to be processed by a special pod2ora program. I've the "POD"s of the second edition of the Cookbook here - if you run it through pod2text, you'll get quite some warnings about unrecognized markup.

      Personally, I would use POD if the intended end result was man pages. I'd use LaTeX if the end result is intended to be a document of some form.

      Abigail

        Well, I just went by what Larry himself writes, in the POD chapter of Camel III - that they'd written the book this way.

        Makeshifts last the longest.

        I'd use LaTeX if the end result is intended to be a document of some form.

        Never used it myself, but a while ago there was some talk about using pod for the first draft and then continuing with the document that pod2latex creates. Is that how you work, or do you start with latex?

        Juerd
        - http://juerd.nl/
        - spamcollector_perlmonks@juerd.nl (do not use).
        

Re: Re: Crash Course in POD
by Juerd (Abbot) on Apr 23, 2003 at 08:43 UTC

    Nobody reads pod in pod format.

    Very not true.

    Most recent example is merlyn's article draft he refered to in the chatterbox. It was written in POD, but I doubt anyone has converted it to another format prior to reading it. And why would you convert it? If you understand POD, which is very easy, POD is perfectly readable (unlike some other documentation formats, xml based ones imho being the worst).

    so you'll wanna use inline pod

    No, I absolutely do NOT want that. And whenever I encounter code that does interleave pod with code, I podselect it and put it at the end instead. See also [style, *again

    # I try not to put an __END__ token here cause mod_perl

    You probably mean Apache::Registry, which is not the same as mod_perl. With mod_perl, you usually use a module with a handler in it, just like Apache::Registry itself. Please note that Apache::Registry has an __END__ token in it and works just fine.

    Juerd
    - http://juerd.nl/
    - spamcollector_perlmonks@juerd.nl (do not use).
    

      Monk please.

      merlyn is always asking for somebody to proofread his articles -- any time I help him out I most definetly use (podchecker and) pod2html before reading them.

      Yeah, inline pod is a personal style thing. I used to be like you, not liking inline pod, but now I feel its the way to go (tastes change).

      And as for mod_perl, yup, I guess I should've added cause like %80 of my dealing with mod_perl are with Apache::Registry (and alikes), so I don't assume like i'm writing some handler (I assume Registry).

      update: added like i'm writing -- besides, Registry is the handler I'm aiming for, not just some handler.


      MJD says you can't just make shit up and expect the computer to know what you mean, retardo!
      I run a Win32 PPM repository for perl 5.6x+5.8x. I take requests.
      ** The Third rule of perl club is a statement of fact: pod is sexy.

        any time I help him out I most definetly use (podchecker and) pod2html before reading them.

        This amazes me :)

        I used to be like you, not liking inline pod, but now I feel its the way to go (tastes change)

        Funny... my taste changed in the opposite direction.

        I don't assume some handler (I assume Registry).

        Apache::Registry *is* a handler ;)

        Juerd
        - http://juerd.nl/
        - spamcollector_perlmonks@juerd.nl (do not use).
        

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://200583]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others wandering the Monastery: (4)
As of 2019-10-20 06:37 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    Notices?