Hi Stas, > > I've posted a question about this issue a while ago, but received no answer. >
I remembered something, but didn't find it my mail folders anymore .... > Your proposal is almost perfect. The only flaw it has is that once you > do manual adjustments you cannot use the automatic retrieval anymore, > since it'll overwrite your manual changes. You do address this issue, > but I don't think it can work with free non-structured text. Or can it? > It will not do anything for you, but it can help. > This kind of tool will be very useful for completed, stable .h files, to > save a lot of time generating initial documentation. However currently > httpd .h files still change a lot. > Then it's even more helpfull. > Please look at the APR::Table and Apache::RequestRec pods that I've > created already: > docs/src/api/mod_perl-2.0/APR/Table.pod and > docs/src/api/mod_perl-2.0/Apache/RequestRec.pod > > It would be very handy to have the tool you suggest for generating > APR::Table since I had to copy-n-paste a lot from .h file. Yes, I have looked at it, and for example the documentation for "make()" function could be totaly autogenerated, without any adjustments needed. > However this > is not the case with Apache/RequestRec.pod where most of the doc is > coming from nothing :) > Such things you still will have to write manualy. > That's said, I'm looking forward to your new doc ripper and if you have > a chance please look at the docs I've done already and tell me whether > we should change the format of functions declaration/description. > My idea is to not directly write the pod files, but to have a kind of map file. This file contains addtional information, for example some text to end to the start or the end of a function documention, text which should be used instead of the auto generated one etc. There will be one entry per function/structure, so you can leave the auto generated docs for one function, add some additional text to another and repleace to the text totaly for a thrid function. Also it should be possible to add new sections of functions which are not detected by the autogeneration code. So you never edit the resuting pod file itself, because it will be overwritten, but only these map files. This way you save at least the copy & paste work and have only to write the other parts of the documentation which could not be auto generated. I have still some work with the XS generation and generation docs will be the next step, so it may take a few weeks until the work is done, but as soon as I have anything to show I will post here so you can comment on it, if this would be a reasonable way to go. For now I can't tell you the format that these files will have, but maybe you first continue with writing docs that can't be auto gernerated (i.e. don't do any copy&paste work). 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 ------------------------------------------------------------- --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
