On Sat, 23 Jun 2001, Doug MacEachern wrote:
> one question we should rethink is whether to have docs in their own
> modperl-2.0-docs cvs tree on all in a modperl-2.0/docs subdirectory.
>
> i'm pretty sure cvs allows access control so certain people can write to
> docs/ but not ../
I think it's just a matter of setting the right group permission on the
files. So ./docs has a different group permission.
> the other reason for the split is if we want to release docs more
> often than the rest of the distribution. if docs/ is self contained
> similar to Apache-Test (with its own Makefile.PL, MANIFEST, etc.), one
> can cd docs/ and 'make dist' for a seperate docs package. when the
> modperl-2.0 package is built from the top-level it will automatically
> include the docs thanks to MakeMaker subdir recursion. but, it docs
> live in modperl-2.0/../modperl-2.0-docs, we need todo special
> Makefile.PL magic to pick up that directory, which i think will be
> somewhat messy.
won't symlink work? I know that symlink doesn't survive cvs, so you have
to do it manually (e.g. from the same Makefile.PL).
Otherwise +1 on sub-dir (assuming that we work out the permissions issue).
> the other question is should docs for modules live inlined in the .pm's or
> be in docs/pod/lib/Apache/FooModule.pod ? i would think the latter so the
> pdf and other doc magic stas plans can be applied to the module docs.
it can be both, with the doc builder retrieving bits from .pm files and
using pod files as well. but it won't be easy to maintain.
That's why I was asking for a separation between user and developers
guides. The User guide should be more like a book where the information
flows in an easy way. The developer guide can be more of a manual where
there is some text linking manpages to each other, whereas the
documentation of each module can be self contained, with little awareness
of other modules. Of course ideally it should be more like a book, but it
would be harder to achieve.
So the user guide has to be made of pods and well thought out.
The developers guide can be a mix of .pm and .pod files if it makes sense
to keep some of the pods inside .pm files and will require some
preprocessing to extract the pods from .pm before building the final doc.
_____________________________________________________________________
Stas Bekman JAm_pH -- Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide http://perl.apache.org/guide
mailto:[EMAIL PROTECTED] http://apachetoday.com http://eXtropia.com/
http://singlesheaven.com http://perl.apache.org http://perlmonth.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
