> As I said, I think we should create an intermediate pod, that is perfectly
> good for editing and information transport and then a small script that
> converts to the final pod with the correct layout/design. In this way you
> separate the informations and the layout and you are able to make a new
> layout anytime you feel it's necessary without haveing to rewrite anything.
>
Great, I understand what you mean and agree with you. Let me sum things up:
So the following is suggested for the intermediate POD, right? let's call it stage2 template.
To make things easier to parse I would slightly modify this and suggest something like
=head2 *func: function()
($foo, $bar) = function($a, [EMAIL PROTECTED])
=over
=item *param: $a
is ...
=item *param: @b
is ...
=item *return: $foo
is ...
=item *since: 2.0.1
=back
Text/Note goes here
I'd rather use @key instead of *key, the same way Apache headers use. So we may even be able to deploy doxygen or a similar tool :)
And in the final POD those *{func|param|...} will be rewritten as I suggested (let's call it stage3 template):
--- =head2 function()
($foo, $bar) = function($a, [EMAIL PROTECTED])
Arguments:
=over
=item $a
is ...
=item @b
is ...
=back
Return values:
=over
=item $foo
is ...
=item $bar
is ...
=back
Since: 2.0.1 ---
right?
So we agree on the following:
1) Stage1: The autogenerator will generate chunks of API docs conforming to the stage2 template format.
2) Stage2:
- first time the stage1 doc is copied over to stage2 and manually edited.
- afterwards the stage2 doc is synced with stage1 doc, (currently using the diffing approach with the older version of the stage1 doc).
This is the only doc that is ever touched manually. This doc includes Rich information that makes it easy to parse for datastructures.
At this stage we use use stage2 template.
3) Stage3: The autoconvert converts stage2 doc into the final representation POD for user consumption. The stage3 template is used here. This stage's doc isn't edited manually.
This is the doc that will be distributed to user
4) Stage2 or Stage3 can be used for converting into other formats (xml, html, pdf, etc.).
Stage3 actually falls into the Stage4 category but it's special, because the rendered results are required to be distributed with the mod_perl source distribution.
---
As I said I'm more interested in the final POD layout (stage3 template), because that's what the users will see, but as you said we can always change this layout without manual work, so I guess I'll start with the template that I've suggested (stage3 template) and then we will see if we change it.
p.s. if you have better names for stage{1,2,3} say so, I don't seem to have any imagination today :)
__________________________________________________________________ Stas Bekman JAm_pH ------> Just Another mod_perl Hacker http://stason.org/ mod_perl Guide ---> http://perl.apache.org mailto:[EMAIL PROTECTED] http://use.perl.org http://apacheweek.com http://modperlbook.org http://apache.org http://ticketmaster.com
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
