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.

In reply to Layout of "pure pod" files in a hierarchy? by deprecated

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.