Layout of "pure pod" files in a hierarchy?

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.
[download]

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?

dep.

--
Laziness, Impatience, Hubris, and Generosity.

Comment on Layout of "pure pod" files in a hierarchy? Select or Download Code

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 'hier.pl' 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.	[reply]
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 "$@"` [download] to tell `perldoc` to search in those three places.	[reply] [d/l]


Think about Loose Coupling
	PerlMonks