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.

---

---

• Are you posting in the right place? Check out Where do I post X? to know for sure.
• Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:

  <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>

• Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
• Want more info? How to link or How to display code and escape characters are good places to start.