Per Einar Ellefsen wrote:At 14:17 12.06.2002, Stas Bekman wrote:As I've explained in my reply to Gerald, I doubt it'll be possible to automatically modify docs which were manually adjusted, because we want to be able to adjust parts that were autogenerated.
Yes, I understand what you mean. After some thought, here's what I think: we build some tool to auto-generate docs the first time around. Like that we can get instant documentation now, without writing it ourselves. Then, we just take those, and restructure them to they become manually edited. That'll need to be done, but atleast we'll have something upfront.
That's exactly what I was suggesting. Plus we continue to use this script to generate fresh sets of docs everytime we update the API. Then we make a diff with the previous autogenerated set (which we have wisely stored away) and voila we get only the changes that need to be manually integrated to the real docs.
Yes, sounds like a fair solution now that I think of it.
Furthermore, I think my example could still beneficially be used to insert things like function sysopsis, which aren't dependent on writing style, just on arguments etc.
That's for the template that will be used for creating the auto-docs, no?
No, for the final docs (must be run through a template engine though). API changes will then reflect automatically in the function synopsis, although manual addition of description might be needed. I'm not sure if this method is better/worse than your diff method though. My point was just that whatever we do, the only thing remaining from the auto-generation will probably be the function synopsis, as descriptions will be modified to Perl jargon. Like this we would only go through a make.pl (or something like that) stage, not the "update, diff, patch" sequence.
-- Per Einar Ellefsen [EMAIL PROTECTED]
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
