> > I was talking about the same thing as a final *source* doc, not final > presentation.
ok, even better. I just though since you had pointed to the final html that it is the same for you > 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. > XML is just an option for generating html, pdf etc. , but that's not the discussion right now as you said. > > func is already in the =item/=head (I prefer head so it'll be in the > TOC). I prefer =head too >Do you want to duplicate it? no, my idea was that while the the editing document should still be pod, it is maybe not the pod which will be delivered in the distribution (this pod will be generated like html etc.), so we can add some more keywords in the editing document, to make automatic conversion easier later on. There are other =head's in the document and how should we detected that this is a start of function definition. If you like to render any function definition special later on, you will need this information. > > '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? 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 > --- > > 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 :) > ok, that sounds fine > 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. > That's why I suggest the =item syntax, you need some more newline, but that's pod. Just buy a screen with more lines ;-) > 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. > I don't think quoted text is a good idea > > may be we don't need these tags at all? or use them differently? e.g.: > That comes close to my suggestion, but you loose some informations here, that I like to preserve > > 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. > 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. 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]
