Beefy Boxes and Bandwidth Generously Provided by pair Networks
go ahead... be a heretic

Layout of "pure pod" files in a hierarchy?

by deprecated (Priest)
on Jul 01, 2003 at 17:37 UTC ( #270562=perlquestion: print w/replies, xml ) Need Help??
deprecated has asked for the wisdom of the Perl Monks concerning the following question:

I'm starting a project that will involve seven of my coworkers, roughly a hundred separate files, and on the order of 45,000 lines of code. So I'm setting up a hierarchy that should remain somewhat sensible throughout the project. We're not worried about feature creep right now, we're in early prototyping.

So, OpenBSD has this great hier(7) manpage:

NAME hier - layout of filesystems DESCRIPTION A sketch of the filesystem hierarchy.
and suchlike. I'd like to be able to have a user just do perldoc hier and have it DTRT. However, it seems to me that I'd have to have a file named hier in there to be spat out. I was thinking of having a Pod/ directory, but that strikes me as somewhat of a hack, given there will be pod inline with the documentation itself.

I'd do it in pod and use pod2man and leave the documentation up to man(1), but doing that means that I'd need a makefile, and users wouldn't be able to read the documentation from within the source tree, they'd have to check it out, build it, then read it, and be careful not to commit the "built" manpages.

There's going to be a LOT of POD with this project, so I need some way to make the documentation intuitive for the user and developer.

How should I go about doing this?


Laziness, Impatience, Hubris, and Generosity.

Replies are listed 'Best First'.
Re: Layout of "pure pod" files in a hierarchy?
by ant9000 (Monk) on Jul 01, 2003 at 17:59 UTC
    You could do it in Perl: leave a '' file in the top dir, that recurses through your structure and gets POD data via Pod::Man (or whatever). It's likely to become pretty slow on large amounts of data, so you might consider implementing some sort of caching as well, at least in the long term.
Re: Layout of "pure pod" files in a hierarchy?
by sgifford (Prior) on Jul 01, 2003 at 22:03 UTC
    According to its manpage, perldoc will search in any directories in the environment variable PERL5LIB. So if you wanted some POD documentation in a Pod directory or a doc directory and some mixed into libraries in lib and other mixed into executables in bin, you could just write a small script that did:
    PERL5LIB=./Pod:./lib:./bin perldoc "$@"
    to tell perldoc to search in those three places.

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://270562]
Approved by halley
Front-paged by hsmyers
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others chilling in the Monastery: (4)
As of 2017-08-21 10:44 GMT
Find Nodes?
    Voting Booth?
    Who is your favorite scientist and why?

    Results (321 votes). Check out past polls.