[I failed to post this to the list earlier, so I'm doing it now. Maybe I'll be able to remember to do "Reply to all" from now on...]
> Good, but you still need a lot of other documentation that would be the > best maintained in POD. Hence I suggest that both are to be used: > > - the API/Metadata docs are to be maintained only via Attributes > (accessible in run time). > > - the rest of the docs are written in POD. > > - since the documentation must include APIs, convert these and append > into the existing PODs during 'make'. So now PODs can be used for > installing man pages, converting into various other formats. There is no > duplication. Stas: Part of our discussion revolved around the problem of getting at the API/Metadata docs when they are maintained as Perl code in order to update the docs or inspect modules that you don't necessarily want to use during runtime. It essentially requires either parsing the perl code or eval'ing the module, both of which are somewhat troublesome solutions. What's stopping us from maintaining the APIs in an external, easily parsable format and having Attributes::* (or whatever) parse that at runtime? I've been able to create a utility that converts code comments containing the API/Metadata information into an XML file, so I think that the concept could support Attributes::* as well. With this, I think you get the best of both: Runtime access without having to eval, easy updating of the XML document through comments or POD. The only inconvenience is keeping the XML document synced with the POD/comments, and a simple makefile entry could recursively update all the XML documents in your source tree. Not that tough. You could even take things one step further and have the Attributes::* code be updated in the source files using the XML documents (with another utility perhaps), which would do away with the runtime parsing of the XML file if you wanted that. I'm just as interested in keeping things in a single place if possible, but I've also been bitten by storing things in Perl code, which is by its nature hard to parse and often pretty scary to eval if you aren't controlling the source. jpt
