develooper Front page | perl.perl5.porters | Postings from April 2010

Re: RFC: Perl manual pages -- update to follow the perlstyle.pod guidelines

Thread Previous | Thread Next
Tom Christiansen
April 2, 2010 10:29
Re: RFC: Perl manual pages -- update to follow the perlstyle.pod guidelines
Message ID:
In-Reply-To: Message from Jari Aalto <>
   of "Fri, 02 Apr 2010 19:55:10 +0300." 

> I noticed that many of the manual pages are inconsistent with the
> perlstyle.pod guidelines. While this may seem like a minor quibble, I
> personally think the quality of documentation is visible from the
> writing and adhering to the style conventions.

> Some issues that I've noticed:

>     - 3-arg open() command not encouraged widely.

There are several reasons for that, some good and some less so.
The trick is to know the difference.

>     - Use of 'or' and 'and' not encouraged widely as a more safe and
>       readable over the '||' '&&' operators.

That's because they aren't.  This is a myth.

>     - Code indentation and placement deviates from manual page to manual
>       page (there are 1, 2, 3 space etc. indentations)

I noticed this on my last past through perlfunc, and wasn't sure how it
came about.  Probably by accident, I suppose.  I'd rather see them as 4,
but it may be that you run into problems with your horizontal line lenght
on nroffed manpages.

>     - Keywords are treated like function calls:

>             if($this and $more)             => if ($this)
>             while($that and $more)          => while($that and $more)

if ($this && $more) 

while ($that && $more) 

>     - for-loops do not encourage the use of 'my' variable localizations:

>             for $var (...)                  => for my $var (...)

Sometimes it gets too busy for the important point to come through.
This note suffices:

    Note: here and in subsequent examples, good style (and the C<use
    strict> pragma) would dictate that you add a C<my> modifier to 
    declare a new lexically scoped variable, like this:

	  my $diff = abs($first - $second);

    However, we've omitted C<my> from most of our examples for clarity.  
    Just assume that any such variable was declared earlier.

>     - Some conditionals could be written easier to the eye by reducing
>       function call parens. E.g

>             if (stat$($filename))

Spurious $.

>             =>

>             if (stat $filename)


>        Likewise for the variable assignments and simple built-in perl
>        function calls:

>             $var = function(arg, arg)

>             =>

>             $var = function arg, arg;   # An example: $str = sprintf "%02d", 1;

That's a slippery slope.

>     - Chunks of code do not have breaks to see where a statement group
>       starts and where next continues. Like stucking "use", "my",
>       "while", "if" every statement together above and below.

I don't know what that means.  You mean not enough vertical whitespace
for grouping code chunks?

> I've started fixing the the issues, but I would like ask:

>     - Would all of these be candidates for adjusting?


>     - Can I use perlstyle.pod as the guidelines for changes?

Depends on who hacked it last.

>     - How should I prepare the changes for inclusion?

> I've worked through GIT blead repository and have all the patches in
> standard format for:

>     git am *.patch

> I could send the patches for each pages in a separate threads?

> Let me know how could I be of help to improve the documentation,

Any help is better than no help: it should be encouraged and thanked.

Thank you,


Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About