perl-docs-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stas Bekman <s...@stason.org>
Subject Re: the API pod template
Date Thu, 13 Jun 2002 07:11:13 GMT
Gerald Richter wrote:
>>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, \@b)

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, \@b)

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:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org   http://ticketmaster.com



---------------------------------------------------------------------
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