You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@perl.apache.org by Stas Bekman <st...@stason.org> on 2002/12/27 06:30:06 UTC
Autogenerated PODs :-)
Forwarding to the dev list, which at this stage seems to be the right
place to discuss this issue at. Once we fledge things out, we could
continue discussing the layout and format at the docs list.
-------- Original Message --------
Subject: Autogenerated PODs :-)
Date: Thu, 26 Dec 2002 16:08:03 +0100
From: Gerald Richter <ri...@ecos.de>
Hi,
finaly I had the time to look at Lyles pod code. It was a good starting
point and I have tweaked it and added a bunch of things, so now we get pods
for mod_perl 2 which looks like a good starting point. I append the new
version along with two example pods to this mail. The next steps that should
be done is to verify that the content of the pods is correct. I have taken a
look around and fixed everything which doesn't looked quite ok to me, but
somebody who has more knowledge of all the functions should verify this.
Also it is possible that the paraser doesn't catch all functions. If
anything is wrong or functions are missing, let me know which ones and I
will fix it. As far as I can tell my time should be not so limited during
january, so I should be able to make fixes quicker then in the last time.
Also I think we should move this to the list, to involve more people. I am
not sure if the docs or the dev list is the best one. I think there are
issues for both...
Gerald
Changes:
- use args instead of doxygen args to iterate over, so we get all arguments,
also when we don't have a comment for them.
- handle non Apache functions (e.g. with mpxs_CLASS_ prefix)
- don't hardcode prefixes, use prefix and class_xs_prefix members instead
- handle return values (single return values only for now)
- ease configuration
Here is what you need to do to get it running:
- Install ExtUtils::XSBuilder (at least 0.23)
- Extract mpbuilder in an empty directory
- Create a config file in mpbuilder/xsbuilder named config.pl which contains
a single line that points to your mod_perl 2 source tree e.g.
$MODPERL="/usr/msrc/cvs/modperl-2.0_bld" ;
- Create symbolic link in the directory where you have extracted mpbuilder
name xs to the xs dirorecty of your mod_perl directory e.g.
ln -s /usr/msrc/cvs/modperl-2.0_bld/xs xs
- Run xsbuilder/source_scan.pl and xsbuilder/xs_generate.pl
- Now you should get the pod files under WrapXS directory
-------------------------------------------------------------
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
-------------------------------------------------------------
Re: Autogenerated PODs :-)
Posted by Stas Bekman <st...@stason.org>.
Gerald Richter wrote:
>>>I would do this in the final conversion state, since we decided that
>>
> this
>
>>>docs that are generated in stage 1 are only contain content, while the
>>>layout is added in stage 2
>>
>>Yes, but it'll require special logic for parsing the intermediate
>>formats. This is not needed when you render that format, because you
>>already have the right tokens.
>>
>
>
> That makes sense
>
>
>>OK, how about the following: let's generate the intermediate and final
>>formats at the same time. This will save us a lot of unnecessary coding
>>and errors.
>>
>
>
> I think for now we will generate just one version. The one with the markup,
> so we get the modperl docs out ASAP. A later version can support different
> formats.
In that case it should be without the special markup that you wanted
(@func, @parm, etc.) There are lots of manpages, so I'd rather have them
most closely to the final version that will go online before we start to
manually edit them. Which probably will happen to all of them.
>>should be relatively simple. If the function is going into Apache:: say:
>>
>>since: apache 2.xx.xx
>>
>>APR:: say
>>
>>since: apr 1.xx
>>
>>ModPerl:: say:
>>
>>since: mod_perl 2.xx
>>
>>You already have the versions for apache and apr, for mod_perl can just
>>use the current version. In any case we don't have mod_perl docs that we
>>reuse, so it'll require manual setting of the version.
>>
>
> Not sure if we get version from Apache and APR. We have to check this....
Should be able to. APR is a standalone project, and its versions are
unrelated to Apache's versions.
> P.S. I am on holiday for the next 5 days, but Lyle has told me that he will
> take some time to work on it.
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: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: Autogenerated PODs :-)
Posted by Gerald Richter <ri...@ecos.de>.
> >
> > I would do this in the final conversion state, since we decided that
this
> > docs that are generated in stage 1 are only contain content, while the
> > layout is added in stage 2
>
> Yes, but it'll require special logic for parsing the intermediate
> formats. This is not needed when you render that format, because you
> already have the right tokens.
>
That makes sense
> OK, how about the following: let's generate the intermediate and final
> formats at the same time. This will save us a lot of unnecessary coding
> and errors.
>
I think for now we will generate just one version. The one with the markup,
so we get the modperl docs out ASAP. A later version can support different
formats.
>
> should be relatively simple. If the function is going into Apache:: say:
>
> since: apache 2.xx.xx
>
> APR:: say
>
> since: apr 1.xx
>
> ModPerl:: say:
>
> since: mod_perl 2.xx
>
> You already have the versions for apache and apr, for mod_perl can just
> use the current version. In any case we don't have mod_perl docs that we
> reuse, so it'll require manual setting of the version.
>
Not sure if we get version from Apache and APR. We have to check this....
Gerald
P.S. I am on holiday for the next 5 days, but Lyle has told me that he will
take some time to work on it.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: Autogenerated PODs :-)
Posted by Stas Bekman <st...@stason.org>.
Gerald Richter wrote:
>>1) build: something is missing from README because
>>xsbuilder/xs_generate.pl was looking for xsbuilder/maps and couldn't
>>find it. I've added a symlink similar to xsbuilder/xs and then it
>>worked. shouldn't it look for xsbuilder/xs/maps instead?
>>
>
>
> makeing the symlink was the right thing to do. I forgot it in the README.
> The next version should work without these symlinks, only taking the value
> from config.pl, but I didn't had the time to implement it yesterday and I
> really wanted this thing o get out...
cool!
>>2) layout:
>>
>>Here is a snippet from perldoc's output on Apache/RequestUtil.pm
>>(indented to the right) with comments starting at /^/:
>>
>> Apache::RequestUtil
>>
>>To save typing would be a good idea to start the functions with:
>>
>>=head1 Functions
>>
>> @func: default_type()
>>
>> $ret = $r->default_type()
>>
>>semicolon would be nice
>>
>> @param: Apache::RequestRec $r
>> The current request
>>
>>would be nice to add the markup: C<L<Apache::RequestRec>> C<$r>, or
>>should this be done at the final conversion stage? It actually should
>>be
>>C<L<Apache::RequestRec|docs::2.0::api::mod_perl-2.0::Apache::RequestRec>>
>>
>
> I would do this in the final conversion state, since we decided that this
> docs that are generated in stage 1 are only contain content, while the
> layout is added in stage 2
Yes, but it'll require special logic for parsing the intermediate
formats. This is not needed when you render that format, because you
already have the right tokens.
OK, how about the following: let's generate the intermediate and final
formats at the same time. This will save us a lot of unnecessary coding
and errors.
>>2.0.1 is an Apache version, Shouldn't this be a mod_perl version?
>>suppose it should say since: httpd-2.0.1, mod_perl-1.99_apr-0.9.1
>>whatever is appropriate?
>>
>
>
> For now this is hardcoded in WrapXS.pm and only a placeholder for some
> information that makes more sense. I am not sure how we can get this
> information? Any ideas?
should be relatively simple. If the function is going into Apache:: say:
since: apache 2.xx.xx
APR:: say
since: apr 1.xx
ModPerl:: say:
since: mod_perl 2.xx
You already have the versions for apache and apr, for mod_perl can just
use the current version. In any case we don't have mod_perl docs that we
reuse, so it'll require manual setting of the version.
__________________________________________________________________
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: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: Autogenerated PODs :-)
Posted by Gerald Richter <ri...@ecos.de>.
>
> 1) build: something is missing from README because
> xsbuilder/xs_generate.pl was looking for xsbuilder/maps and couldn't
> find it. I've added a symlink similar to xsbuilder/xs and then it
> worked. shouldn't it look for xsbuilder/xs/maps instead?
>
makeing the symlink was the right thing to do. I forgot it in the README.
The next version should work without these symlinks, only taking the value
from config.pl, but I didn't had the time to implement it yesterday and I
really wanted this thing o get out...
> 2) layout:
>
> Here is a snippet from perldoc's output on Apache/RequestUtil.pm
> (indented to the right) with comments starting at /^/:
>
> Apache::RequestUtil
>
> To save typing would be a good idea to start the functions with:
>
> =head1 Functions
>
> @func: default_type()
>
> $ret = $r->default_type()
>
> semicolon would be nice
>
> @param: Apache::RequestRec $r
> The current request
>
> would be nice to add the markup: C<L<Apache::RequestRec>> C<$r>, or
> should this be done at the final conversion stage? It actually should
> be
> C<L<Apache::RequestRec|docs::2.0::api::mod_perl-2.0::Apache::RequestRec>>
>
I would do this in the final conversion state, since we decided that this
docs that are generated in stage 1 are only contain content, while the
layout is added in stage 2
> @ret: PV
> The default type
>
> C struct types aren't really useful to Perl programmers, I guess this
> can be converted in the final pod (e.g. PV => scalar, AV => list,...)
>
Yes, of couse, we should convert it.
> @since: 2.0.1
>
> 2.0.1 is an Apache version, Shouldn't this be a mod_perl version?
> suppose it should say since: httpd-2.0.1, mod_perl-1.99_apr-0.9.1
> whatever is appropriate?
>
For now this is hardcoded in WrapXS.pm and only a placeholder for some
information that makes more sense. I am not sure how we can get this
information? Any ideas?
> Retrieve the document root for this server
>
> May be put the short description first? And then full desc after the
> usage?
>
Mostly we only have one short description.
>
> ...
>
> In general < and > should be escaped E<lt>, E<gt>
Yes
>but we probably should
> do better in cases like: Apache/RequestIO/RequestIO.pod:
>
> @param: Apache::RequestRec $read_policy
> How the server should interpret a chunked transfer-encoding.
> One
> of: <pre>
> REQUEST_NO_BODY Send 413 error if message has
> any body
> REQUEST_CHUNKED_ERROR Send 411 error if body without
Con-
> tent-Length
> REQUEST_CHUNKED_DECHUNK If chunked, remove the chunks
> for me.
> </PRE>
>
> should probably convert <pre> by adding a separating new line and making
> sure that a 2 chars leading space starts every line of <pre>, including
> empty lines.
>
Yes
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: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: Autogenerated PODs :-)
Posted by Stas Bekman <st...@stason.org>.
Great work, Lyle and Gerald!
I've a few comments so far:
1) build: something is missing from README because
xsbuilder/xs_generate.pl was looking for xsbuilder/maps and couldn't
find it. I've added a symlink similar to xsbuilder/xs and then it
worked. shouldn't it look for xsbuilder/xs/maps instead?
2) layout:
Here is a snippet from perldoc's output on Apache/RequestUtil.pm
(indented to the right) with comments starting at /^/:
Apache::RequestUtil
To save typing would be a good idea to start the functions with:
=head1 Functions
@func: default_type()
$ret = $r->default_type()
semicolon would be nice
@param: Apache::RequestRec $r
The current request
would be nice to add the markup: C<L<Apache::RequestRec>> C<$r>, or
should this be done at the final conversion stage? It actually should
be
C<L<Apache::RequestRec|docs::2.0::api::mod_perl-2.0::Apache::RequestRec>>
@ret: PV
The default type
C struct types aren't really useful to Perl programmers, I guess this
can be converted in the final pod (e.g. PV => scalar, AV => list,...)
@since: 2.0.1
2.0.1 is an Apache version, Shouldn't this be a mod_perl version?
suppose it should say since: httpd-2.0.1, mod_perl-1.99_apr-0.9.1
whatever is appropriate?
Retrieve the document root for this server
May be put the short description first? And then full desc after the
usage?
...
In general < and > should be escaped E<lt>, E<gt> but we probably should
do better in cases like: Apache/RequestIO/RequestIO.pod:
@param: Apache::RequestRec $read_policy
How the server should interpret a chunked transfer-encoding.
One
of: <pre>
REQUEST_NO_BODY Send 413 error if message has
any body
REQUEST_CHUNKED_ERROR Send 411 error if body without Con-
tent-Length
REQUEST_CHUNKED_DECHUNK If chunked, remove the chunks
for me.
</PRE>
should probably convert <pre> by adding a separating new line and making
sure that a 2 chars leading space starts every line of <pre>, including
empty lines.
__________________________________________________________________
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: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: Autogenerated PODs :-)
Posted by Geoffrey Young <ge...@modperlcookbook.org>.
Gerald Richter wrote:
>>I had submitted a patch for adding this to the generic test suite. maybe
>>you can steal some of the code:
>>
>>http://marc.theaimsgroup.com/?l=apache-modperl-dev&m=103919146817077&w=2
>>
>
>
> As far as I see it only check if the generated POD is syntactical ok, or
> does it more?
nope. I misunderstood what you were after :)
--Geoff
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: Autogenerated PODs :-)
Posted by Gerald Richter <ri...@ecos.de>.
>
> I had submitted a patch for adding this to the generic test suite. maybe
> you can steal some of the code:
>
> http://marc.theaimsgroup.com/?l=apache-modperl-dev&m=103919146817077&w=2
>
As far as I see it only check if the generated POD is syntactical ok, or
does it more?
The problem is less the format of the generated POD (which could be changed
easily), but that it contains the right information. I expect that some of
the mod_perl/Apache functions still missing or not generated the right way,
but I can't check them all out manally. I only have done peeks into places
where I have expected trouble.
Gerald
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: Autogenerated PODs :-)
Posted by Geoffrey Young <ge...@modperlcookbook.org>.
> The next steps that
> should
> be done is to verify that the content of the pods is correct.
I had submitted a patch for adding this to the generic test suite. maybe
you can steal some of the code:
http://marc.theaimsgroup.com/?l=apache-modperl-dev&m=103919146817077&w=2
HTH
--Geoff
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org