perldoc 
Author Message
 perldoc

        I want to document my modules internally, so that they can be read with
perldoc.  So in my module, Dir/Mod.pm, which is in a library in the
PERLLIB path, I put:

======8<---SNIP----------
=pod

        Documentation goes here!

=cut
======8<---SNIP----------

        ...expecting to be able to type "perldoc Dir::Mod" and get
"\nDocumentation goes here!\n" in return.  What I get, though, is "No
documentation found for Dir::Mod."

        Any hints as to what I've got wrong?  I really want to use in-module
and in-script documentation.

        Thanks,

/|/|ike /+yers



Wed, 18 Jun 1902 08:00:00 GMT  
 perldoc

Quote:

>    I want to document my modules internally, so that they can be read with
>perldoc.  So in my module, Dir/Mod.pm, which is in a library in the
>PERLLIB path, I put:

>======8<---SNIP----------
>=pod

>    Documentation goes here!

>=cut
>======8<---SNIP----------

>    ...expecting to be able to type "perldoc Dir::Mod" and get
>"\nDocumentation goes here!\n" in return.  What I get, though, is "No
>documentation found for Dir::Mod."

>    Any hints as to what I've got wrong?  

I think you forgot to type:

   perldoc perlpod

:-)

Quote:
>I really want to use in-module
>and in-script documentation.

You do not have any POD markup there.

-------------------
=item =pod

=item =cut

The "=pod" directive does nothing beyond telling the compiler to lay
off parsing code through the next "=cut".  It's useful for adding
another paragraph to the doc if you're mixing up code and pod a lot.
-------------------

The only POD you have is for the _compiler_ to use. All of the
other markup (of which you have none) are for the POD tools...

So, give it some markup:

=pod

=head1 Some Cool Docs

        Documentation goes here!

=cut

perldoc should make something for you then.

--
    Tad McClellan                          SGML Consulting

    Fort Worth, Texas



Wed, 18 Jun 1902 08:00:00 GMT  
 perldoc

Quote:
> I think you forgot to type:

>    perldoc perlpod

> :-)

        Typed it plenty, just missed the importance of the part that says to
use a =head1 to start things.  It reads more like a suggestion, really,
but I've found that perldoc won't acknowledge the documentation without
the =head1.

Quote:
> You do not have any POD markup there.
> The "=pod" directive does nothing beyond telling the compiler to lay
> off parsing code through the next "=cut".  It's useful for adding
> another paragraph to the doc if you're mixing up code and pod a lot.
> -------------------

> The only POD you have is for the _compiler_ to use. All of the
> other markup (of which you have none) are for the POD tools...

        I had been going for {*filter*} docs there - just wanted to push something
through without formatting it to prove that I would get something out.
Now that I've done that, I'll move on to advanced commands, like =item
(WOOHOO!).

        Oh yeah, and thanks!

/|/|ike /+yers



Wed, 18 Jun 1902 08:00:00 GMT  
 
 [ 3 post ] 

 Relevant Pages 

1. perldoc -i switch/perldoc documentation

2. perldoc PERLLOCALE(1)

3. perldoc in Active Perl

4. perldoc vs man why so much slower

5. Difference between Camel & perldoc

6. redirecting perldoc ouput on Win32

7. Help using perldoc

8. Perldoc vs. module installation

9. Newbie question : How to use perldoc?

10. Tutorial question - perldoc perlxs - learning how to write XS-based code

11. Perldoc formatting on Linux

12. Bad Output from Perldoc

 

 
Powered by phpBB® Forum Software