perl-docs-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stas Bekman <s...@stason.org>
Subject Re: Docs Format
Date Fri, 11 Jul 2003 03:14:59 GMT
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


Mime
View raw message