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

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

Thread Next
Jari Aalto
April 2, 2010 09:56
RFC: Perl manual pages -- update to follow the perlstyle.pod guidelines
Message ID:

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'v noticed:

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

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

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

    - Keywords are treated like function calls:

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

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

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

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

            if (stat$($filename))


            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;

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

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 chnages?
    - How should I prepare the chages 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,

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