Re: Autogenerated PODs :-)

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