CPAN not extracting documentation

Hello,

I just loaded a new module onto CPAN, and I've obviously done something
wrong, because my POD documentation isn't shown properly on CPAN.

http://search.cpan.org/~aakhter/Visio-1.008/

The extracted htmlified documentation is not representative on what is
actualy in the .pm files (the main Viso file, as well as the other .pm
files).

Any ideas on what I may be doing wrong.

(yes i I admit, even the current documentation needs some work, but I
wanted to run thru the process first)

Thanks for any help.

Re: CPAN not extracting documentation

Hello,


Aamer Akhter wrote:
> Hello,
>
> I just loaded a new module onto CPAN, and I've obviously done something
> wrong, because my POD documentation isn't shown properly on CPAN.
>
> http://search.cpan.org/~aakhter/Visio-1.008/
>
> The extracted htmlified documentation is not representative on what is
> actualy in the .pm files (the main Viso file, as well as the other .pm
> files).
>
> Any ideas on what I may be doing wrong.

Yes the POD documentation is wrong. I suggest to look into a module
which documentation looks good in CPAN, e.g.
http://search.cpan.org/~rpagitsch/Win32-Process-Perf-1.01/li b/Win32/Process/Perf.pm

As I can see:
ABSTRACT, DESCRIPTION having only the default documntation, generated by
h2xs.
For function documentation I use:
=head1 FUNCTIONS

=over 4

=item new(..)

=item otherfunc

=back

Also a good idea: perldoc perlpod

regards,
Reinhard

>
> (yes i I admit, even the current documentation needs some work, but I
> wanted to run thru the process first)
>
> Thanks for any help.
>


--
regards,
Reinhard

Re: CPAN not extracting documentation

Aamer Akhter wrote:
> Hello,
>
> I just loaded a new module onto CPAN, and I've obviously done something
> wrong, because my POD documentation isn't shown properly on CPAN.
>
> http://search.cpan.org/~aakhter/Visio-1.008/
>
> The extracted htmlified documentation is not representative on what is
> actualy in the .pm files (the main Viso file, as well as the other .pm
> files).
>
> Any ideas on what I may be doing wrong.
>
> (yes i I admit, even the current documentation needs some work, but I
> wanted to run thru the process first)
>
That was not a wise choice. Uploading your file to CPAN should follow
creation of code, tests and documentation. Not only does your
documentation not look good; your module has failed all its tests:
(http://testers.cpan.org/show/Visio.html#Visio-1.008)

Please see the Perl documentation, especially:

perldoc perlnewmod

.... which is also available online at
http://perldoc.perl.org/perlnewmod.html. Tutorials for writing
CPAN-ready modules are available in a number of places, including
http://mathforum.org/~ken/perl_modules.html

Re: CPAN not extracting documentation

Reinhard,

[snip]
> Yes the POD documentation is wrong. I suggest to look into a module
> which documentation looks good in CPAN, e.g.

Thanks for responding...

I looked at your module and I think something wierd is going on with
respect to the document generation.

If you look at the source at:
http://search.cpan.org/src/AAKHTER/Visio-1.008/Visio.pm

and the generated documentation at:
http://search.cpan.org/~aakhter/Visio-1.008

You'll notice that I do have the NAME, SYNOPSIS and the fucntions
filled out in the source documentation. But when the CPAN version is
generated, NAME is set to the h2x default.

It appears the CPAN is using the default pod documentation from one of
the sub-classes (Visio/Line.pm). This class is actually documented in
Visio.pm (as are the other classes).

For some reason the documentation in Visio.pm is not being picked. I
have tried pod2html and it does work fine on Visio.pm.

The tutorials refrencenced in the thread do not discuss the situation
with multi-file modules and how the documenation is extracted. Can
someone please send a pointer that explains what may be happening in my
case?


Thanks much.





>
> --
> regards,
> Reinhard

Re: CPAN not extracting documentation

[snip]
> For some reason the documentation in Visio.pm is not being picked. I
> have tried pod2html and it does work fine on Visio.pm.
>
> The tutorials refrencenced in the thread do not discuss the situation
> with multi-file modules and how the documenation is extracted. Can
> someone please send a pointer that explains what may be happening in my
> case?

It looks like CPAN is extracting the module name from

=head1 NAME

Visio - Perl extension mainpulating XML based Visio files


The other modules I had just cut and pasted the original h2x pod (and
retained the Visio name). This was confusing the CPAN extractor. I've
changed the NAME section under each of the modules such that they are
now unique, and this appears to work.

>
>
> Thanks much.
>
>
>
>
>
> >
> > --
> > regards,
> > Reinhard