On Wed, 2 Oct 2002, Erik Lechak wrote: > I'm looking at it right now. Thanks for the link. This is the first > time I have heard of doxygen.
I meant the pointer at least partly as a reminder that this is one wheel we shouldn't have to reinvent. I think there are plenty of solutions out there to the easy problem of marking up documentation, and to that of embedding blocks of doc in a program. At some point, we may also want to cross-link the documentation based on information gathered from the code, and (at least for C/C++) there are already good tools (doxygen among them) to handle this much more difficult problem. Rewriting any of these things sounds like a lot of work to me. If it's interesting work to you, please don't let me hold you back, but if the task were left to me, I'd grab something ready-made if it were at all possible to do so. > By the way is this an RFC thing? Should this "concept" be submitted > to someone other than this group? Who makes the call about what finds > its way into perl err ... I mean parrot? I'm sure we have a form for wanting to change the official project documentation format, but I don't remember the number. > If others want me to continue with this. The next step would be to > throw away 90% of my code and parse the parrotdoc into true XML. Then > that opens up parrotdoc to all the functionality of XML. Gack! :) The beauty of POD is that human beings can actually read it. XML, on the other hand, can easily become more than half meta-information, and thus less than half legible. If I were going the XML route, however, I'd suggest making it DocBook compatible, since people I've known who like their docs in XML seem to use that. btw, I think we'd have a much better idea of whether or not POD does what we need if we were a bit better at following our existing doc standards... /s
