Writing external pod for a distro executable

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

If I'm writing a module distro, and I have lib/Module.pm, and I want to write documentation in a separate file, I can write lib/Module.pod.

What if I have bin/app and I want to write separate documentation, should I place it in bin/app.pod or lib/app.pod? I'm thinking bin, will this make ExtUtils::MakeMaker upset? Looks like no. Is it poor practice?

Maybe I should just place all my docs in a different dir structure?

Maybe it doesn't matter as long as the documentation is written properly? (?)

Comment on Writing external pod for a distro executable

Replies are listed 'Best First'.
Re: Writing external pod for a distro executable by Anonymous Monk on Oct 14, 2008 at 21:48 UTC
What if I have bin/app and I want to write separate documentation, should I place it in bin/app.pod or lib/app.pod? I'm thinking bin, will this make ExtUtils::MakeMaker upset? Looks like no. Is it poor practice? It should be lib/app.pod (would conflict with App.pod, App.pm), but you don't have to worry about that if you include the pod after __END__ in the exe. Is it poor practice? Its very rare, AFAIK only perldoc does it, so I would say yes. Maybe I should just place all my docs in a different dir structure? No :) Ok you can do it, but then you have to make sure ExtUtils::MakeMaker::WriteMakefile() gets the right combination of arguments so they get installed in the right spot. I wouldn't bother.	[reply]

Replies are listed 'Best First'.

Re: Writing external pod for a distro executable
by Anonymous Monk on Oct 14, 2008 at 21:48 UTC

Is it poor practice?
Its very rare, AFAIK only perldoc does it, so I would say yes.

Maybe I should just place all my docs in a different dir structure?
No :) Ok you can do it, but then you have to make sure ExtUtils::MakeMaker::WriteMakefile() gets the right combination of arguments so they get installed in the right spot. I wouldn't bother.

[reply]