James Tillman wrote:
>>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. Yup, that sounds good. Keeping the XML or whatever intermediate meta cache up to date is easy. Just have some source control that before running the query checks that the files are up-to-date and updates those whose sources have changed. I'd suggest looking into the DocSet project that I've started, it's not that generic yet, but should be extended as more people chime in to satisfy their needs. At mod_perl we have similar documentation demands so joining the efforts will be only beneficial for us all. Gerald has already planned to extend DocSet to generate XML. The DocSet discussion and pointers are available from here http://www.template-toolkit.org/mailman/listinfo/template-docset the latest package: http://www.apache.org/~stas/DocSet-0.04.tar.gz > 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. That's true. I think that we can make try different things until we find out the best format/approach. The only thing we should worry about is that we can automatically convert any existing documentation into the new format without any manual work. Once we have this requirement satisfied, we can experiment with things. _____________________________________________________________________ Stas Bekman JAm_pH -- Just Another mod_perl Hacker http://stason.org/ mod_perl Guide http://perl.apache.org/guide mailto:[EMAIL PROTECTED] http://ticketmaster.com http://apacheweek.com http://singlesheaven.com http://perl.apache.org http://perlmonth.com/
