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: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
> [.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: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org