pdldoc doesn't find PDL::Graphics::Prima

[devel-chm]

A default install of PDL::Graphics::Prima version 0.8
into an existing PDL install went cleanly. However,
the online docs were only viewable via perldoc and
not pdldoc or the PDL shells online docs features.

I ran scantree.pl by hand an now the docs are
available. I think Maggie determined a way to
update the docs on install. I suggest the same
here.

[run4flat]

Thanks, Chris. I'll look at Maggie's code and add that to my Build.PL file, probably later this week.

[devel-chm]

I tried running scantree.pl with no luck. Apparently your docs have routines in =item rather than =head2 which why the functions are not picked up.

[run4flat]

"... later this week." Oops. Yes, the use of =item is a problem here.

[run4flat]

Sorry I haven't worked on this. Lots of balls in the air, and writing the tutorial-esque docs is a higher priority. This will happen, I promise! :-)

[nawglan]

This might be fixed after my pull request gets merged to address CPANTS pod errors. shrug

[run4flat]

@nawglan alas, no. The pdldoc system requires that I use =head2 elements, not =item elements. I prefer =item elements for most pod rendering situations. I think the most important things for pdldoc are probably in PDL::Graphics::Prima::Simple, and I would be amenable to changing that. I plan to brush things up and release something soon, so perhaps I will tackle this in the next month or so.

[nawglan]

If you want me to do it, I can. I was assigned this distro for the month of May... so if you have anything that you want to offload to me let me know.

[run4flat]

@nawglan Thanks! I wonder, though, who assigned this distro to you? What are you assigned to do with it? Anyway, if you are willing to help out, the documentation task at hand is to change (at least) how PDL::Graphics::Prima::Simple is documented to follow the conventions in PDL::Doc. During the process of writing this comment, I think I've come up with a solution that I like. Here's what I propose.

I would like to create a pure pod document called PDL::Graphics::Prima::CheatSheet which has =head1 CONSTRUCTORS and =head1 METHODS sections. These sections could list all of the P::G::Prima "commands" with a quick snippet of documentation, and link to the appropriate module for a more complete discussion. This way it's findable via pdldoc, but I get to use the more general pod formatting for the long-winded documentation.

@nawglan, you are welcome to contribute as much or as little to this as you wish. Simply having the conversation has helped me work out what I think is an good solution to this problem, and hopefully I'll have a chance soon to work on this.

[nawglan]

http://cpan-prc.org/ This module was selected as a part of the 2015 CPAN Pull Request Challenge. I will give this a go. PDL::Graphics::Prima::CheatSheet.pod will be my main contribution for this month I hope. 8) I haven't used your module or anything in PDL actually, so this will be fun to learn something new.

[run4flat]

Oh, hey, that's really cool! Thanks! I think that CheatSheet.pod would be a great resource for this project, and low hanging fruit for a pull request challenge. I've worked plenty with PDL and know the documentation system, so please let me know if you have any questions about the spec. Also, I'd be happy to write the =for sig portions as PDL function signatures may seem a bit cryptic to the uninitiated.