perl-docs-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Per Einar Ellefsen <per.ei...@skynet.be>
Subject Re: Autogenerating XS code and Docs
Date Wed, 12 Jun 2002 15:54:58 GMT
At 14:17 12.06.2002, Stas Bekman wrote:
>Per Einar Ellefsen wrote:
>>At 12:04 12.06.2002, Gerald Richter - ecos gmbh wrote:
>>
>>>That's only a rought idea, maybe somebodyelse has another idea how to handle
>>>this?
>>
>>Might not be the best idea, but what I was thinking about was making it 
>>template-like, having the auto-fetches things inserted in the manual 
>>edited POD. Like.
>>[% ap_table_add %] <---- inserts POD with function synopsis etc.
>>Manually added notes go here......
>>The problem is that new functions won't be picked up automatically, 
>>except if we have some special mark at the EOF where new functions can be 
>>inserted. However, I think that new functions will need to be handled 
>>manually anyway, as they need to have some order/classification that 
>>automatic generation can't do.
>
>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.

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.

>>> > And of course we need to discuss the template, but this can be done
>>> > later when and if we start deploying ExtUtils::XSBuilder.
>>
>>I think he meant the data structure...
>
>No, I meant the template for the Apache::Foo manpage. Template in a sense 
>of how the manpage should be constructed to keep docs consistent and 
>intuitive. Check the existing manpages to see what I mean.

Ok, I see what you mean now.

-- 
Per Einar Ellefsen
per.einar@skynet.be



---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org


Mime
View raw message