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: Patch: testing.pod Updates
Date Wed, 25 Aug 2004 07:08:24 GMT
David Wheeler wrote:
> On Aug 24, 2004, at 3:09 PM, Randy Kobes wrote:
> 
>> Yes, F<> is understood (I've been using it for the Win32
>> sections). There's a neat feature in the html conversion -
>> if there's a (physical) file "foo", F<foo> will become a
>> link to "foo".
> 
> 
> Ah, yeah, that's slick. Thanks Randy.
> 
> So I made it as far as "Stress Testing", but then just filled in 
> Apache::TestMB information in the rest of the document. Hopefully I can 
> get to editing the remainder for grammar, punctuation, etc. sometime soon.

Great work, David.

David, First of all, please read: 
http://perl.apache.org/contribute/docs/style.html
as most style things are all documented there:

I just quickly scrolled through, haven't had a chance to do a thorough
reading, so just a few comments for things that stood out:

> -=head1 Basics of Perl Modules Testing
> +=head1 Basics of Perl Module Testing

Make sure that you check whether there are some xrefs to any of the =head 
entries, before modifying them. I haven't checked if there are any, just a 
reminder :)

> -In the section L<Writing Tests|/"Writing_Tests"> several helper 
> functions which make
> -the tests writing easier are discussed.
> +The L<Writing Tests|/"Writing_Tests"> section documents several helper
> +functions that make simplify the writing of tests.

Hmm, not sure where that "" came from but as you work on the doc, please 
drop the quotes, there is already a way too much alien non-text chars in 
xrefs to further pollute them with extra quotes. so it should be just
L<Writing Tests|/Writing_Tests>. (I know you didn't write that :)

>    #file:lib/Apache/Amazing.pm
>    #--------------------------
>    package Apache::Amazing;
> -
> +
>    use strict;
>    use warnings;
> -
> +
>    use Apache::RequestRec ();
>    use Apache::RequestIO ();
> -
> +
>    $Apache::Amazing::VERSION = '0.01';
> -
> +
>    use Apache::Const -compile => 'OK';
> -
> +

Please don't do that (here and below). There should be /^\s\s\n/ and not 
/^\n/ in the code. If you run bin/build and look at your patched version's 
html you will see why (it won't get a continuous bar on the left side).
It's in the docs style guide.

 > unmodified version in C<blib/lib>. Of course, if you always run C<make

Why C<blib/lib>? It's a dir/file, so either I<> or F<>

-- 
__________________________________________________________________
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