Hi, > > > > What experiences to people have with using inline POD within > > the Module.pm as opposed to maintaining two files, > > Module.pm (for code) and Module.pod (for documentation)? > > What recommendations would you have for P5EE code? > > > > I would assume Inline POD is the way to go.
The main advantage of separate files I see, is that they could be maintained separately. It's quite usual for greater projects (see Apache or mod_perl and others) that the people who are maintaining the code, not the same who are writing the documentation. If both is in separate files it's simply easier to handle. Another point is translation of docs. You could have many pod files for different languages for the same module, but only one language in the module itself. I personaly have projects with inline docs and with separate files and as long as I maintain the docs myself I see no differences when updateing the docs. If I don't discipline myself to update the docs, I would never do it... > > I think POD has to go for this project. At least in its default form. > > We need something way more structured, that maintains API details to the > extreme, like JavaDOC does, only we want something easier/better than > JavaDOC. > I don't know anything of JavaDOC, so what does it give to us ? If it something like doxygen for C, which scans the C code and combine it with the comments to generate documenation ? > I'd suggest XML for docs, in particular sdocbook (simple docbook), but I > know it gives people hives, so maybe an extended POD format would work > (but it starts to get real ugly when you extend it to this extent). > I really don't like to write docs in XML, it's much more harder to read in the source (as long as you don't use special tools) Does anybody know what the current discussion about pod in the Perl community is ? Are there any intentions the extent it, for example to display tables ? Gerald ------------------------------------------------------------- Gerald Richter ecos electronic communication services gmbh Internetconnect * Webserver/-design/-datenbanken * Consulting Post: Tulpenstrasse 5 D-55276 Dienheim b. Mainz E-Mail: [EMAIL PROTECTED] Voice: +49 6133 925131 WWW: http://www.ecos.de Fax: +49 6133 925152 -------------------------------------------------------------
