I have already started using something like the following: http://perl.apache.org/release/docs/2.0/api/mod_perl-2.0/APR/Table.html as I said I'm not happy with it, just trying.
So as you say we are talking about two different templates:
1. for the autogenerated docs, which keeps as much info as possible, if the info that we will not use (e.g. some C side effects, like 'const char *' vs 'char *')
2. the template for the final pod.
(2) is the final layout, which *I* don't care much about for now. I thinking about something between 1 and 2. (1) is what is generated automaticly, then we take this and do manualy editing it, so it contains the final content. This final content should be independend of the final layout, so we would get 1,2,3
1.) autogenerated 2.) editied 3.) layout -> pod,html,pdf etc. (autogenerated from 2)
2 should be something that is still editable by hand (so I perfer not use XML here too), but also can be easly parsed (maybe transformed to XML and then from there via XSLT to the other output formats)
I was talking about the same thing as a final *source* doc, not final presentation. But it must be in POD. Other html, pdf are generated from POD and we aren't discussing these now.
And please let's leave XML out of this.
Though we should discuss the (2), again see the URL above for some ideas.
actually we have only 2 types of arguments:
param return
Yes, but for my (2) I also would like to see something like func:, note:, since: etc.
func is already in the =item/=head (I prefer head so it'll be in the TOC). Do you want to duplicate it?
'since:' is fine.
I don't think we really need 'note:', since the rest of the section is one big note.
So currently I see it as:
--- =head2 function()
($foo, $bar) = function($a, [EMAIL PROTECTED])
param: $a is ... param: $b is ... return: $foo is ... return: $bar is ... since: 2.0.1
The rest is one big note with examples and what not, so the autogenerator will simply copy the note from C header file as is, without any headers. no? ---
notice that the first element of the section is an example of usage. See
http://perl.apache.org/release/docs/2.0/api/mod_perl-2.0/APR/Table.html and you will see that there are different ways to invoke the same function and they should all be presented and each be followed by the spec of params, return values (e.g. called in scalar context, list context, etc). Therefore we may end up with a few sections for the same =head2 (without repeating the =head2 tag). Of course this will never be created by the autogenerator, because only Perl can make functions behave differently in different circumstances :)
Now as you understand the suggested format has a problem. perldoc will smash all the param/return things into one para, so it's not good.
Putting each entry on a separate line seems to be a big waste of space (though probably the only solution). And it also allows us to have multilined entries which wrap around.
we could make these entries into quoted text, but then it makes it harder to wrap multilines and I'm not sure if it's a good idea.
What do you think? Any other ideas?
may be we don't need these tags at all? or use them differently? e.g.:
----- =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
this is a lot of noise in the source, but will make any rendered doc look very good. So it seems that I prefer the latter format if thinking towards the final product.
so it shouldn't be a problem. I also had 'remark' in the APR::Table doc, but this can probably go into the body of the description of the method.
For the final layout it can, for the editited version (my 2) it may not.
fine.
--
__________________________________________________________________ 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]
