How to match up external pod files with module code

leocharre has asked for the wisdom of the Perl Monks concerning the following question:

I have my pod embedded with my code. I'm using ExtUtils::MakeMaker for deployment.

I want to instead have the pod in external files. But I want them to still deploy properly.

Where should the pod files be? If my code is lib/Book/Page.pm, should it be lib/Book/Page.pod ? I've been looking for like an hour- It's hurting my self esteem.

update. Yes indeed, if you have a file for use with Makefile.PL in lib/Uber/Cool.pm, and your documentation in lib/Uber/Cool.pod - Things work out real nice on deployment etc. ( do remember to put the files in the MANIFEST ).

I find that putting all the doc in another file is handy as far as planning (you can write out your docs with nice syntax coloring under vim, get ya real organisized)- it's nice also to look at your doc besides your code in a sepparate window. Helpful to remind you what you're supposed to be doing.

One con here- is that as a developer, looking at other people's code, I kind of like to see the documentation right besides the code. So, it could be annoying to some people to have the code and doc sepparate.

Comment on How to match up external pod files with module code

Replies are listed 'Best First'.
Re: How to match up external pod files with module code by Joost (Canon) on Dec 01, 2006 at 23:58 UTC
If my code is lib/Book/Page.pm, should it be lib/Book/Page.pod I guess so. Have you tried it? For what it's worth, MakeMaker can be a bit hard to comprehend. For some reason I couldn't get the additional XS modules in my Audio::LADSPA module to compile unless I put them in their own subdirectory with their own Makefile.PL. For instance, Audio::LADPSA::Plugin goes into /Plugin/Plugin.pm and then the docs go into /Plugin/Plugin.pod. By the way, if you want to see how other people do it, did you know you can browse inside module distributions on search.cpan.org by clicking one the "browse" link on the module page? like this "What should it profit a man, if he should win a flame war, yet lose his cool?"	[reply]
Re: How to match up external pod files with module code by bart (Canon) on Dec 02, 2006 at 12:19 UTC
If my code is lib/Book/Page.pm, should it be lib/Book/Page.pod That appears to be where `perldoc` looks for it. So IMO all you have to do is mention it in you module's MANIFEST, and it should then be included in your distro and installed with `make`. But, that's what I expect, it's an untested claim. Why don't you test it? You have all the files handy. Add it the file to MANIFEST, do `make tardist`, and then extract the archive to a new location, do both `perl Makefile.PL` and `make`, and see that the POD gets where it should be. Right next to the .pm file.	[reply] [d/l] [select]
Re: How to match up external pod files with module code by tinita (Parson) on Dec 02, 2006 at 12:41 UTC
If my code is lib/Book/Page.pm, should it be lib/Book/Page.pod exactly. at least that has been working for a cpan-module i wrote.	[reply]