Stas Bekman wrote:
[moving this discussion to the mod_perl docs list so others can contribute. Also CC'ing Lyle and Jack who has offered help with this project and probably have already gave up, trying to figure out where they could help. Hopefully this Gerald's code will provide the missing fuel]
I have started to work on XSBuilder again. The first thing I have done is to
create a module called ModPerl::PODTemplate, which contains a set of methods
which allows to easily change the format of the generated POD. I attach you
the new version, along with two files I have generated. I didn't have made
any changes in the format so far. I would like to get your feedback, on how
the output should look like, them I can implement it imediately (or of
course you can change mpbuilder/lib/ModPerl/PODTemple.pm on your own and
play with it)
But I have already provided the feedback, when you first posted it long time ago. http://mathforum.org/epigone/modperl-docs-dev/fyhahmen
Here are some more comments:
The examples look OK I suppose, I think we have already agreed to have $t->foo and not $t -> foo.
From the recent work on the docs, I think I prefer to have all the functions in =head2 to be enclosed in C<> so they look good in the TOC. Granted it makes it more cumbersome to write L<> links manually, but the end user gets better docs.
same for all variables, they should be C<>, to save us a lot of manual work.
Should description of the method come before its arguments?
things like <PRE> are HTML, not pod. see Table.pod that you have attached.
Things like PV/IV make little sense to users. Perhaps replace them with SCALAR? So we may have SCALAR, ARRAY, VOID
What are PV and IV?
@since: 1.99 : should probably be more specific, i.e. 1.99_09
Where does that version come from?
Finally, are you sure that we want to maintain this intermediary format. It's going to be a big pain. I suggest to drop the idea and go with the plain pod. We have very little human resources to work on docs, so the less we have to maintain the better.
That's fine with me.
A sample function entry would look like this, as I understand it:
=head2 C<pool()>
$val = $obj->pool($newval)
=over 4
=item Calling Object Type: Apache::RequestRec
=item Return Value Type: APR::Pool
=item since: 1.99
yes?
-- Jack
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
