X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlstyle.pod;h=3fb93970909dbf52e25eac33b6a0ac350d21572a;hb=eda6e075b0c0944056eda3d4a7d8ace8624d5b26;hp=46c17ddae37ca2af49323e83dfde519637ef35d5;hpb=184e971831b273a4209000a9990327c3ea67e866;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlstyle.pod b/pod/perlstyle.pod
index 46c17dd..3fb9397 100644
--- a/pod/perlstyle.pod
+++ b/pod/perlstyle.pod
@@ -6,17 +6,17 @@ perlstyle - Perl style guide
 
 Each programmer will, of course, have his or her own preferences in
 regards to formatting, but there are some general guidelines that will
-make your programs easier to read, understand, and maintain.  
+make your programs easier to read, understand, and maintain.
 
 The most important thing is to run your programs under the B<-w>
 flag at all times.  You may turn it off explicitly for particular
-portions of code via the C<$^W> variable if you must.  You should
-also always run under C<use strict> or know the reason why not.
-The C<use sigtrap> and even C<use diagnostics> pragmas may also prove
-useful.
+portions of code via the C<no warnings> pragma or the C<$^W> variable 
+if you must.  You should also always run under C<use strict> or know the
+reason why not.  The C<use sigtrap> and even C<use diagnostics> pragmas
+may also prove useful.
 
 Regarding aesthetics of code lay out, about the only thing Larry
-cares strongly about is that the closing curly brace of
+cares strongly about is that the closing curly bracket of
 a multi-line BLOCK should line up with the keyword that started the construct.
 Beyond that, he has other preferences that aren't so strong:
 
@@ -32,7 +32,7 @@ Opening curly on same line as keyword, if possible, otherwise line up.
 
 =item *
 
-Space before the opening curly of a multiline BLOCK.
+Space before the opening curly of a multi-line BLOCK.
 
 =item *
 
@@ -64,7 +64,7 @@ Uncuddled elses.
 
 =item *
 
-No space between function name and its opening paren.
+No space between function name and its opening parenthesis.
 
 =item *
 
@@ -76,7 +76,7 @@ Long lines broken after an operator (except "and" and "or").
 
 =item *
 
-Space after last paren matching on current line.
+Space after last parenthesis matching on current line.
 
 =item *
 
@@ -117,7 +117,7 @@ is better than
 
     $verbose && print "Starting analysis\n";
 
-since the main point isn't whether the user typed B<-v> or not.
+because the main point isn't whether the user typed B<-v> or not.
 
 Similarly, just because an operator lets you assume default arguments
 doesn't mean that you have to make use of the defaults.  The defaults
@@ -135,7 +135,7 @@ schmuck bounce on the % key in B<vi>.
 
 Even if you aren't in doubt, consider the mental welfare of the person
 who has to maintain the code after you, and who will probably put
-parens in the wrong place.
+parentheses in the wrong place.
 
 =item *
 
@@ -154,13 +154,13 @@ the middle.  Just "outdent" it a little to make it more visible:
 =item *
 
 Don't be afraid to use loop labels--they're there to enhance
-readability as well as to allow multi-level loop breaks.  See the
+readability as well as to allow multilevel loop breaks.  See the
 previous example.
 
 =item *
 
 Avoid using grep() (or map()) or `backticks` in a void context, that is,
-when you just throw away their return values.  Those functions all 
+when you just throw away their return values.  Those functions all
 have return values, so use them.  Otherwise use a foreach() loop or
 the system() function instead.
 
@@ -178,7 +178,7 @@ determined by the B<Configure> program when Perl was installed.
 Choose mnemonic identifiers.  If you can't remember what mnemonic means,
 you've got a problem.
 
-=item * 
+=item *
 
 While short identifiers like $gotit are probably ok, use underscores to
 separate words.  It is generally easier to read $var_names_like_this than
@@ -189,20 +189,20 @@ Package names are sometimes an exception to this rule.  Perl informally
 reserves lowercase module names for "pragma" modules like C<integer> and
 C<strict>.  Other modules should begin with a capital letter and use mixed
 case, but probably without underscores due to limitations in primitive
-filesystems' representations of module names as files that must fit into a
-few sparse bites.
+file systems' representations of module names as files that must fit into a
+few sparse bytes.
 
 =item *
 
-You may find it helpful to use letter case to indicate the scope 
-or nature of a variable. For example: 
+You may find it helpful to use letter case to indicate the scope
+or nature of a variable. For example:
 
-    $ALL_CAPS_HERE   constants only (beware clashes with perl vars!)  
-    $Some_Caps_Here  package-wide global/static 
-    $no_caps_here    function scope my() or local() variables 
+    $ALL_CAPS_HERE   constants only (beware clashes with perl vars!)
+    $Some_Caps_Here  package-wide global/static
+    $no_caps_here    function scope my() or local() variables
 
-Function and method names seem to work best as all lowercase. 
-E.g., $obj-E<gt>as_string(). 
+Function and method names seem to work best as all lowercase.
+E.g., $obj-E<gt>as_string().
 
 You can use a leading underscore to indicate that a variable or
 function should not be used outside the package that defined it.
@@ -216,9 +216,9 @@ Don't use slash as a delimiter when your regexp has slashes or backslashes.
 =item *
 
 Use the new "and" and "or" operators to avoid having to parenthesize
-list operators so much, and to reduce the incidence of punctuational
+list operators so much, and to reduce the incidence of punctuation
 operators like C<&&> and C<||>.  Call your subroutines as if they were
-functions or list operators to avoid excessive ampersands and parens.
+functions or list operators to avoid excessive ampersands and parentheses.
 
 =item *
 
@@ -227,12 +227,12 @@ Use here documents instead of repeated print() statements.
 =item *
 
 Line up corresponding things vertically, especially if it'd be too long
-to fit on one line anyway.  
+to fit on one line anyway.
 
-    $IDX = $ST_MTIME;       
-    $IDX = $ST_ATIME 	   if $opt_u; 
-    $IDX = $ST_CTIME 	   if $opt_c;     
-    $IDX = $ST_SIZE  	   if $opt_s;     
+    $IDX = $ST_MTIME;
+    $IDX = $ST_ATIME 	   if $opt_u;
+    $IDX = $ST_CTIME 	   if $opt_c;
+    $IDX = $ST_SIZE  	   if $opt_s;
 
     mkdir $tmpdir, 0700	or die "can't mkdir $tmpdir: $!";
     chdir($tmpdir)      or die "can't chdir $tmpdir: $!";
@@ -242,7 +242,7 @@ to fit on one line anyway.
 
 Always check the return codes of system calls.  Good error messages should
 go to STDERR, include which program caused the problem, what the failed
-system call and arguments were, and VERY IMPORTANT) should contain the
+system call and arguments were, and (VERY IMPORTANT) should contain the
 standard system error message for what went wrong.  Here's a simple but
 sufficient example:
 
@@ -250,7 +250,7 @@ sufficient example:
 
 =item *
 
-Line up your translations when it makes sense:
+Line up your transliterations when it makes sense:
 
     tr [abc]
        [xyz];
@@ -260,9 +260,9 @@ Line up your translations when it makes sense:
 Think about reusability.  Why waste brainpower on a one-shot when you
 might want to do something like it again?  Consider generalizing your
 code.  Consider writing a module or object class.  Consider making your
-code run cleanly with C<use strict> and B<-w> in effect.  Consider giving away
-your code.  Consider changing your whole world view.  Consider... oh,
-never mind.
+code run cleanly with C<use strict> and C<use warnings> (or B<-w>) in
+effect.  Consider giving away your code.  Consider changing your whole
+world view.  Consider... oh, never mind.
 
 =item *