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 Jack Nerad <jn...@bellsouth.net> on 2003/07/11 05:06:47 UTC
Docs Format
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
Re: Docs Format
Posted by Stas Bekman <st...@stason.org>.
Jack Nerad wrote:
> Stas Bekman wrote:
>
>>
>> the only tweaks we are going to do are semantic ones (i.e. messing
>> with pod tags), and that should be trivially to fix. The biggest
>> challenge is to get a sensible conversion of the C docs to Perl docs.
>> So I won't worry about this now. We will polish this later.
>
>
> Should I then just post a patch to the PODTemplate.pm?
I think that will work. If you have a webspace you can upload too, you may
want to upload a link to it and the tar with everything, so we can download
and play with.
>> Feel free to ask questions and we will provide the answers. But really
>> this is just a template to use for creating the docs.
>>
>> I suppose what's confusing is that Gerald has suggested the
>> intermediate format, which I suggest to simply drop and everything
>> becomes simpler at once (of course at the price of having less
>> flexible sources)
>
>
> Assuming we drop the intermediate format (just for a moment) what would
> the "stages" of AUTOGENERATION be?
>
> Stage 1. Pull docs into raw_src
> Stage 2. Edit the docs by hand
There are going to be only 2 stages that concern us at this point. The ones
you have mentioned.
> Stage 3. Write scripts using the POD::* modules that convert the docs to
> alternate formats (or leave that to those who want those alternate
> formats)?
so that won't be the case, other than the "normal" pod->html|ps|pdf that we
already have.
> I think with all the POD::* modules available, it shouldn't be too hard
> to deal without the intermediate format. What was the original thinking
> behind having the intermediate format?
Gerald was thinking to import docs into doxygen if I remember correctly. If
you search this list's archives, you can find all the discussion regarding
this topic.
__________________________________________________________________
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: Docs Format
Posted by Jack Nerad <jn...@bellsouth.net>.
Stas Bekman wrote:
>
> the only tweaks we are going to do are semantic ones (i.e. messing
> with pod tags), and that should be trivially to fix. The biggest
> challenge is to get a sensible conversion of the C docs to Perl docs.
> So I won't worry about this now. We will polish this later.
Should I then just post a patch to the PODTemplate.pm?
>
> Feel free to ask questions and we will provide the answers. But really
> this is just a template to use for creating the docs.
>
> I suppose what's confusing is that Gerald has suggested the
> intermediate format, which I suggest to simply drop and everything
> becomes simpler at once (of course at the price of having less
> flexible sources)
Assuming we drop the intermediate format (just for a moment) what would
the "stages" of AUTOGENERATION be?
Stage 1. Pull docs into raw_src
Stage 2. Edit the docs by hand
Stage 3. Write scripts using the POD::* modules that convert the docs to
alternate formats (or leave that to those who want those alternate formats)?
?
I think with all the POD::* modules available, it shouldn't be too hard
to deal without the intermediate format. What was the original thinking
behind having the intermediate format?
--
Jack
>
>
>
> __________________________________________________________________
> 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: Docs Format
Posted by Stas Bekman <st...@stason.org>.
Jack Nerad wrote:
> Stas Bekman wrote:
>
>>
>>
>> For more info see: http://gisle.aas.no/perl/illguts/
>>
>> So for docs I think we should replace those with "string", "number", etc.
>>
>>>> @since: 1.99 : should probably be more specific, i.e. 1.99_09
>>>
>>>
>>>
>>>
>>> Where does that version come from?
>>
>>
>>
>> we set it once automatically when we generate the first docs set and
>> from then maintain it manually.
>
>
> Okay.
>
>>>
>>> =head2 C<pool()>
>>>
>>> $val = $obj->pool($newval)
>>
>>
>>
>> please add two spaces in front of the code sections
>
>
> I guess it'd be easier if I had some perldoc that was already
> acceptable. Is the current mp1 perldoc in acceptable shape?
the only tweaks we are going to do are semantic ones (i.e. messing with pod
tags), and that should be trivially to fix. The biggest challenge is to get a
sensible conversion of the C docs to Perl docs. So I won't worry about this
now. We will polish this later.
>>> =over 4
>>>
>>> =item Calling Object Type: Apache::RequestRec
>>>
>>> =item Return Value Type: APR::Pool
>>>
>>> =item since: 1.99
>>
>>
>>
>> Have you looked at modperl-docs/src/docs/2.0/api/AUTOGENERATION
>>
>> we need to update it a bit though, but it's good enough to get the idea.
>
>
> Yes, but I don't really understand it. I'll have to study it a bit.
Feel free to ask questions and we will provide the answers. But really this is
just a template to use for creating the docs.
I suppose what's confusing is that Gerald has suggested the intermediate
format, which I suggest to simply drop and everything becomes simpler at once
(of course at the price of having less flexible sources)
__________________________________________________________________
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: Docs Format
Posted by Jack Nerad <jn...@bellsouth.net>.
Stas Bekman wrote:
>
>
> For more info see: http://gisle.aas.no/perl/illguts/
>
> So for docs I think we should replace those with "string", "number", etc.
>
>>> @since: 1.99 : should probably be more specific, i.e. 1.99_09
>>
>>
>>
>> Where does that version come from?
>
>
> we set it once automatically when we generate the first docs set and
> from then maintain it manually.
Okay.
>>
>> =head2 C<pool()>
>>
>> $val = $obj->pool($newval)
>
>
> please add two spaces in front of the code sections
I guess it'd be easier if I had some perldoc that was already
acceptable. Is the current mp1 perldoc in acceptable shape?
>
>> =over 4
>>
>> =item Calling Object Type: Apache::RequestRec
>>
>> =item Return Value Type: APR::Pool
>>
>> =item since: 1.99
>
>
> Have you looked at modperl-docs/src/docs/2.0/api/AUTOGENERATION
>
> we need to update it a bit though, but it's good enough to get the idea.
Yes, but I don't really understand it. I'll have to study it a bit.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: Docs Format
Posted by Stas Bekman <st...@stason.org>.
Jack Nerad wrote:
> 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?
PV = string
IV = integer value
For more info see: http://gisle.aas.no/perl/illguts/
So for docs I think we should replace those with "string", "number", etc.
>> @since: 1.99 : should probably be more specific, i.e. 1.99_09
>
>
> Where does that version come from?
we set it once automatically when we generate the first docs set and from then
maintain it manually.
>> 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.
It's fine with us end users, Gerald wanted to have an intermediate format for
other reasons.
> A sample function entry would look like this, as I understand it:
>
> =head2 C<pool()>
>
> $val = $obj->pool($newval)
please add two spaces in front of the code sections
> =over 4
>
> =item Calling Object Type: Apache::RequestRec
>
> =item Return Value Type: APR::Pool
>
> =item since: 1.99
Have you looked at modperl-docs/src/docs/2.0/api/AUTOGENERATION
we need to update it a bit though, but it's good enough to get the idea.
__________________________________________________________________
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