You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs-dev@perl.apache.org by Stas Bekman <st...@stason.org> on 2002/06/13 08:00:40 UTC
the API pod template
[splitting the dev list off, moving the template discussion into a
separate thread]
Gerald Richter wrote:
>>If you look at the existing 2.0 API docs, I've tried to follow the same
>>layout (i.e. template), but I'm not entirely satisfied with it yet.
>>
>
>
> For that reason it is maybe a good idea to keep some more information in the
> generated docs (maybe they have then to be postprocessed before they get
> into the distribution), but when we keep what are the function defeintion,
> parameters, comment, we will be able to convert it to any layout.
>
> There is some idea at the p5ee project
> (http://www.officevision.com/pub/p5ee/software/htdocs/P5EEx/Blue/podstyle.ht
> ml), not sure if this helps anything. For example for a method you have
> something like:
>
> # Every method (each if applicable)
> =head2 <Method-Name>()
> * Signature: <Sample-Usage-Illustrating-The-Signature>
> * Param: <Param-Name> <Type> <In/Out> <Undef-OK>
> * Return: <Return-Name> <Type> <Undef-OK>
> * Throws: <Exception-Name>
> * Deprecated: <Since-Version> <Planned-Discontinue-Version>
> * Since: <Version-Number>
>
> If you use this schema you will be able to transform it any layout later,
> because you keep this extra informations you need in the keywords like
> "*Param:"
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.
I don't care much about (1), whichever format is used is fine with me,
as long as it's not xml.
Though we should discuss the (2), again see the URL above for some ideas.
actually we have only 2 types of arguments:
param
return
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.
Is that enough?
__________________________________________________________________
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
Re: the API pod template
Posted by Stas Bekman <st...@stason.org>.
Gerald Richter - ecos gmbh wrote:
>>Great, I understand what you mean and agree with you. Let me sum things
>
> up:
>
>
> I agree 100% to your summary :-)
"Das ist groß" says the fish :)
>>p.s. if you have better names for stage{1,2,3} say so, I don't seem to
>>have any imagination today :)
>>
>
>
> Maybe auto, edit and final? Does this sound better?
sounds cool!
__________________________________________________________________
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
Re: the API pod template
Posted by Gerald Richter - ecos gmbh <ri...@ecos.de>.
>
> Great, I understand what you mean and agree with you. Let me sum things
up:
>
I agree 100% to your summary :-)
>
> p.s. if you have better names for stage{1,2,3} say so, I don't seem to
> have any imagination today :)
>
Maybe auto, edit and final? Does this sound better?
Gerald
-------------------------------------------------------------
Gerald Richter ecos electronic communication services gmbh
Internetconnect * Webserver/-design/-datenbanken * Consulting
Post: Tulpenstrasse 5 D-55276 Dienheim b. Mainz
E-Mail: richter@ecos.de Voice: +49 6133 925131
WWW: http://www.ecos.de Fax: +49 6133 925152
-------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: mod_perl logo
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
> At 04:51 15.06.2002, Stas Bekman wrote:
>
>> Per Einar Ellefsen wrote:
>>
>>> At 04:01 14.06.2002, Stas Bekman wrote:
>>>
>>>> Hmm, I've looked closely at the new logos, there is a problem with
>>>> them: they don't have a "safe" margin and the logo ends at the edges
>>>> without white/transparent border :( Jonathan, can this be fixed?
>>>> This looks quite bad.
>>>
>>>
>>> I guess we can just insert them into a bigger background if that's
>>> what you mean; shouldn't be a problem.
>>
>>
>> I'm talking about images themselves, not HTML background. I think it's
>> a bad idea to suggest images which are overcropped.
>
>
> Yes, I was talking about the images themselves.It isn't too hard to just
> copy the image over to a bigger canvas (is that the name?).
sure
>> That's a lot of manual work to get the cropped margin back on all
>> images. Michael Demers has probably done most of the formats
>> converting automatically. Jonathan, can you contact him or give us his
>> email address? Thanks!
>
>
> That would of course be best...but are we prepared to wait?
Well, I don't know his email address. Of course we don't know anything
before we ask.
__________________________________________________________________
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
Re: mod_perl logo
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 04:51 15.06.2002, Stas Bekman wrote:
>Per Einar Ellefsen wrote:
>>At 04:01 14.06.2002, Stas Bekman wrote:
>>>Hmm, I've looked closely at the new logos, there is a problem with them:
>>>they don't have a "safe" margin and the logo ends at the edges without
>>>white/transparent border :( Jonathan, can this be fixed? This looks quite bad.
>>
>>I guess we can just insert them into a bigger background if that's what
>>you mean; shouldn't be a problem.
>
>I'm talking about images themselves, not HTML background. I think it's a
>bad idea to suggest images which are overcropped.
Yes, I was talking about the images themselves.It isn't too hard to just
copy the image over to a bigger canvas (is that the name?).
>That's a lot of manual work to get the cropped margin back on all images.
>Michael Demers has probably done most of the formats converting
>automatically. Jonathan, can you contact him or give us his email address?
>Thanks!
That would of course be best...but are we prepared to wait?
--
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
RE: mod_perl logo
Posted by "Jonathan M. Hollin" <ne...@digital-word.com>.
I'm talking about images themselves, not HTML background. I think it's a
bad idea to suggest images which are overcropped.
That's a lot of manual work to get the cropped margin back on all
images. Michael Demers has probably done most of the formats converting
automatically. Jonathan, can you contact him or give us his email
address? Thanks!
Yikes - sorry for the delay guys. Here's Michael's email address: mike
[at] inteo.com.
Jonathan - WYPUG
http://wypug.pm.org/
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: mod_perl logo
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
> At 04:01 14.06.2002, Stas Bekman wrote:
>
>> Per Einar Ellefsen wrote:
>>
>>> At 19:01 13.06.2002, Stas Bekman wrote:
>>>
>>>> Stas Bekman wrote:
>>>>
>>>>> What are the new images?
>>>>
>>>>
>>>>
>>>> apologies, they were at the attached tar. You posted the URL, so I
>>>> was looking for them there :)
>>>>
>>>> Very nice, I'll later add them to the site's cvs. Or may be Per
>>>> Einar is already working on this :)
>>>
>>>
>>> I'll do this. Should I replace the current buttons I made from the
>>> logo with the new ones? I guess I won't incorporate his new versions
>>> of the logo, as that one's already being used. ?
>>
>>
>> Hmm, I've looked closely at the new logos, there is a problem with
>> them: they don't have a "safe" margin and the logo ends at the edges
>> without white/transparent border :( Jonathan, can this be fixed? This
>> looks quite bad.
>
>
> I guess we can just insert them into a bigger background if that's what
> you mean; shouldn't be a problem.
I'm talking about images themselves, not HTML background. I think it's a
bad idea to suggest images which are overcropped.
That's a lot of manual work to get the cropped margin back on all
images. Michael Demers has probably done most of the formats converting
automatically. Jonathan, can you contact him or give us his email
address? Thanks!
__________________________________________________________________
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
Re: mod_perl logo
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 04:01 14.06.2002, Stas Bekman wrote:
>Per Einar Ellefsen wrote:
>>At 19:01 13.06.2002, Stas Bekman wrote:
>>
>>>Stas Bekman wrote:
>>>
>>>>What are the new images?
>>>
>>>
>>>apologies, they were at the attached tar. You posted the URL, so I was
>>>looking for them there :)
>>>
>>>Very nice, I'll later add them to the site's cvs. Or may be Per Einar is
>>>already working on this :)
>>
>>I'll do this. Should I replace the current buttons I made from the logo
>>with the new ones? I guess I won't incorporate his new versions of the
>>logo, as that one's already being used. ?
>
>Hmm, I've looked closely at the new logos, there is a problem with them:
>they don't have a "safe" margin and the logo ends at the edges without
>white/transparent border :( Jonathan, can this be fixed? This looks quite bad.
I guess we can just insert them into a bigger background if that's what you
mean; shouldn't be a problem.
--
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
Re: mod_perl logo
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
> At 19:01 13.06.2002, Stas Bekman wrote:
>
>> Stas Bekman wrote:
>>
>>> What are the new images?
>>
>>
>> apologies, they were at the attached tar. You posted the URL, so I was
>> looking for them there :)
>>
>> Very nice, I'll later add them to the site's cvs. Or may be Per Einar
>> is already working on this :)
>
>
> I'll do this. Should I replace the current buttons I made from the logo
> with the new ones? I guess I won't incorporate his new versions of the
> logo, as that one's already being used. ?
Hmm, I've looked closely at the new logos, there is a problem with them:
they don't have a "safe" margin and the logo ends at the edges without
white/transparent border :( Jonathan, can this be fixed? This looks
quite bad.
__________________________________________________________________
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
Re: mod_perl logo
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 19:01 13.06.2002, Stas Bekman wrote:
>Stas Bekman wrote:
>
>>What are the new images?
>
>apologies, they were at the attached tar. You posted the URL, so I was
>looking for them there :)
>
>Very nice, I'll later add them to the site's cvs. Or may be Per Einar is
>already working on this :)
I'll do this. Should I replace the current buttons I made from the logo
with the new ones? I guess I won't incorporate his new versions of the
logo, as that one's already being used. ?
--
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
Re: mod_perl logo
Posted by Stas Bekman <st...@stason.org>.
Stas Bekman wrote:
> What are the new images?
apologies, they were at the attached tar. You posted the URL, so I was
looking for them there :)
Very nice, I'll later add them to the site's cvs. Or may be Per Einar is
already working on this :)
__________________________________________________________________
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
Re: mod_perl logo
Posted by Stas Bekman <st...@stason.org>.
Jonathan M. Hollin wrote:
> Michael Demers has emailed me some more work he has done on the mod_perl
> logo and I attach his file here for anyone who might find a use for these
> new items. I will, of course, add these to the galleries at
> http://wypug.digital-word.com/mod_perl/ in the near future.
Strange, I cannot see any images with mozilla-1.0/linux from your site.
Works fine with Galeon. And I can see images from other sites with
mozilla. Just the names, but no images.
What are the new images?
> P.S. I apologise for my absence from the list for such a long time. It's
> not that I've lost interest in the project or anything - just that I am
> extremely busy with work at the moment.
no prob, busy is good :)
p.s. btw, it's a very bad idea to post 500k size messages to the list. I
know I've sent a bunch of snapshots before, but 500k is probably a big
pain for somebody with a slow connection. The URL should be just 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
mod_perl logo
Posted by "Jonathan M. Hollin" <ne...@digital-word.com>.
Michael Demers has emailed me some more work he has done on the mod_perl
logo and I attach his file here for anyone who might find a use for these
new items. I will, of course, add these to the galleries at
http://wypug.digital-word.com/mod_perl/ in the near future.
Kindest regards to all...
Jonathan M. Hollin - WYPUG
http://wypug.pm.org/
P.S. I apologise for my absence from the list for such a long time. It's
not that I've lost interest in the project or anything - just that I am
extremely busy with work at the moment.
Re: the API pod template
Posted by Stas Bekman <st...@stason.org>.
> 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, \@b)
>
> =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, \@b)
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: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
Re: the API pod template
Posted by Gerald Richter <ri...@ecos.de>.
>
> 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, \@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?
To make things easier to parse I would slightly modify this and suggest
something like
=head2 *func: function()
($foo, $bar) = function($a, \@b)
=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: richter@ecos.de Voice: +49 6133 925131
WWW: http://www.ecos.de Fax: +49 6133 925152
-------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: the API pod template
Posted by Stas Bekman <st...@stason.org>.
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
Re: the API pod template
Posted by Gerald Richter <ri...@ecos.de>.
> 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)
>
> 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.
> 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.
Gerald
-------------------------------------------------------------
Gerald Richter ecos electronic communication services gmbh
Internetconnect * Webserver/-design/-datenbanken * Consulting
Post: Tulpenstrasse 5 D-55276 Dienheim b. Mainz
E-Mail: richter@ecos.de Voice: +49 6133 925131
WWW: http://www.ecos.de Fax: +49 6133 925152
-------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org