Index: /trunk/doc/misc/perlCodeConventions.tex
===================================================================
--- /trunk/doc/misc/perlCodeConventions.tex	(revision 2333)
+++ /trunk/doc/misc/perlCodeConventions.tex	(revision 2334)
@@ -1,3 +1,3 @@
-%%% $Id: perlCodeConventions.tex,v 1.3 2004-11-11 02:00:42 jhoblitt Exp $
+%%% $Id: perlCodeConventions.tex,v 1.4 2004-11-11 02:27:56 jhoblitt Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -127,9 +127,9 @@
 A Bourne shell "she-bang" for perl.  \code{#!/usr/bin/perl}.
 \item 
-A Copright notice followed by a blank commented line.  Then one commented line
+A Copyright notice followed by a blank commented line.  Then one commented line
 per CVS keyword to be expanded.
 \item
-A minimum perl version requiremt in long form (vStrings are not allowed).
-Where \code(requriemnt = revision + version / 1000 + subversion / 1\_000\_000).
+A minimum perl version requirement in long form (vStrings are not allowed).
+Where \code(requirement = revision + version / 1000 + subversion / 1\_000\_000).
 E.g. A minimum requirement of Perl 5.8.5 would be expressed as \code{use
 5.008005}
@@ -155,5 +155,5 @@
 # Copyright (C) 2004  Joshua Hoblitt
 #
-# $Id: perlCodeConventions.tex,v 1.3 2004-11-11 02:00:42 jhoblitt Exp $
+# $Id: perlCodeConventions.tex,v 1.4 2004-11-11 02:27:56 jhoblitt Exp $
 
 use 5.008005;   # optional
@@ -181,11 +181,11 @@
 \begin{itemize}
 \item 
-A Copright notice followed by a blank commented line.  Then one commented line
+A Copyright notice followed by a blank commented line.  Then one commented line
 per CVS keyword to be expanded.
 \item
 A Perl Package declaration.  \code{package Foo}
 \item
-A minimum perl version requiremt in long form (vStrings are not allowed).
-Where \code(requriemnt = revision + version / 1000 + subversion / 1\_000\_000).
+A minimum perl version requirement in long form (vStrings are not allowed).
+Where \code(requirement = revision + version / 1000 + subversion / 1\_000\_000).
 E.g. A minimum requirement of Perl 5.8.5 would be expressed as \code{use
 5.008005}
@@ -212,5 +212,5 @@
 # Copyright (C) 2004  Joshua Hoblitt
 #
-# $Id: perlCodeConventions.tex,v 1.3 2004-11-11 02:00:42 jhoblitt Exp $
+# $Id: perlCodeConventions.tex,v 1.4 2004-11-11 02:27:56 jhoblitt Exp $
 
 package Foo;
@@ -355,5 +355,5 @@
 should not be included as a comment.
 
-Discussion of nontrivial or nonobvious design decisions is
+Discussion of nontrivial or non-obvious design decisions is
 appropriate, but avoid duplicating information that is present in (and
 clear from) the code. It is too easy for redundant comments to get out
@@ -389,5 +389,5 @@
 \subsubsection{Multi-Line Comments}
 
-Merely a repitition of single-line comments.
+Merely a repetition of single-line comments.
 
 \subsubsection{Trailing Comments}
@@ -464,5 +464,5 @@
 
 In almost all situations with the exception of when parameters are being passed
-into a subrutine.
+into a subroutine.
 
 Do not put different types on the same line. Example:
@@ -487,5 +487,5 @@
 \end{verbatim}
 
-Note: This restiction does not apply to Perl's built in variables.
+Note: This restriction does not apply to Perl's built in variables.
 
 \subsection{Initialization}
@@ -502,18 +502,6 @@
 Variables should ordinarily be declared at the top of the block in
 which they appear, unless there is some reason to declare them later.
-This allows them to be initialised as they are created, and naturally
+This allows them to be initialized as they are created, and naturally
 associates their declaration with their use.
-
-
-Indexes of loops should usually be declared on the line above loop statement.
-
-\begin{verbatim}
-my $i = 0;
-for (i < $maxLoops) {
-    # do stuff
-
-    $i++;
-}
-\end{verbatim}
 
 \subsection{Subroutine Declarations}
@@ -524,7 +512,7 @@
 \begin{itemize}
 \item 
-Subroutine declarations should be preceeded by a short comment describing what
+Subroutine declarations should be preceded by a short comment describing what
 the subroutine does.  These documentation comments should include a brief
-desription as well as other warnings, bugs, etc. as needed.
+description as well as other warnings, bugs, etc. as needed.
 
 \item
@@ -542,5 +530,5 @@
 
 \item
-The last line before the closing brace must explicity declare a return value.
+The last line before the closing brace must explicitly declare a return value.
 \end{itemize}
 
@@ -562,12 +550,12 @@
 Each line should usually contain only one statement. Example:
 \begin{verbatim}
-x = sqrt(x2);                           // Correct
-i++;                                    // Correct  
-x = sqrt(x2); i++;                      // Avoid!
+$x = sqrt($x2);                         # Correct
+$i++;                                   # Correct  
+$x = sqrt($x2); $i++;                   # Avoid!
 \end{verbatim}
 
 An example of a reasonably two-statement line is:
 \begin{verbatim}
-argv++; argc--;
+$foo++; $bar--;
 \end{verbatim}
 where the two actions are intimately related.
@@ -575,7 +563,6 @@
 \subsection{Compound Statements}
 
-Compound statements are statements that contain lists of statements
-enclosed in braces. See the
-following sections for examples.
+Compound statements are statements that contain lists of statements enclosed in
+braces. See the following sections for examples.
 
 \begin{itemize}
@@ -594,15 +581,25 @@
 \subsection{return Statements}
 
-A \code{return} statement with a value should not use parentheses unless they make the return value more obvious in some way. Example:
-\begin{verbatim}
-return;
-
-return myDisk.size;
-
-return (size ? size : defaultSize);
-
-\end{verbatim}
-
-\subsection{if, if-else, if else-if else Statements}
+A \code{return} statement with a value should not use parentheses unless they
+make the return value more obvious in some way.  All subroutines must have an
+explicit, non-null, return statement.   Example:
+
+\begin{verbatim}
+return undef;                           # Correct
+return;                                 # Wrong!
+
+return $myDisk->size;
+
+return ($size ? $size : $defaultSize);
+\end{verbatim}
+
+Note:  In absence of an explicit return statement Perl will return the results
+of the last statement executed.  A null return statement \code{return;} also
+causes the result of the last statement executed to be returned.
+
+\subsection{if, if-else, if elsif else Statements}
+
+\code{if} statements must always use braces {} around statements and parenthesis
+() around conditionals.
 
 The \code{if-else} class of statements should have the following form:
@@ -620,22 +617,15 @@
 if (condition) {
     statements;
-} else if (condition) {
+} elsif (condition) {
     statements;
 } else {
     statements;
 }
-
-\end{verbatim}
-
-Note: \code{if} statements always use braces {}. Avoid the following
-error-prone form:
-\begin{verbatim}
-if (condition)                          // AVOID! THIS OMITS THE BRACES {}!
-    statement;
-\end{verbatim}
-
-\subsection{for Statements}
+\end{verbatim}
+
+\subsection{C style for Statements}
 
 A \code{for} statement should have the following form:
+
 \begin{verbatim}
 for (initialization; condition; update) {
@@ -644,9 +634,16 @@
 \end{verbatim}
 
-An empty \code{for} statement (one in which all the work is done
-in the initialization, condition, and update clauses) should have one of
-the following forms:
-\begin{verbatim}
-for (initialization; condition; update);
+For example:
+
+\begin{verbatim}
+for (my $i =0; $i < 100; $i++) {
+    print "$i\n";
+}
+\end{verbatim}
+
+An empty \code{for} statement (one in which all the work is done in the
+initialization, condition, and update clauses) should have the following forms:
+
+\begin{verbatim}
 for (initialization; condition; update) {}
 \end{verbatim}
@@ -666,7 +663,6 @@
 }
 \end{verbatim}
-An empty \code{while} statement should have one of the following forms:
-\begin{verbatim}
-while (condition);
+An empty \code{while} statement should have the following form:
+\begin{verbatim}
 while (condition) {}
 \end{verbatim}
@@ -680,44 +676,4 @@
 } while (condition);
 \end{verbatim}
-
-\subsection{switch Statements}
-
-A \code{switch} statement should have the following form):
-\begin{verbatim}
-switch (condition) {
-    case ABC:
-        statements;
-        /* falls through */
-
-    case DEF:
-    case GHI:
-        statements;
-        break;
-
-    case XYZ:
-        statements;
-        break;
-
-    default:
-        statements;
-        break;
-}
-\end{verbatim}
-
-Every time a case falls through (doesn't include a \code{break}
-statement), add a comment where the \code{break} statement would
-normally be. This is shown in the preceding code example with the
-\code{/* falls through */} comment. A comment is not required (or
-expected) when the fall-through is between multiple case statements.
-
-Every \code{switch} statement should include a default case, which
-should come last. The \code{break} in the default case is redundant,
-but it prevents a fall-through error if later another \code{case} is
-later (and illegally) added after the default clause.
-
-When switching on an enumerated type, if all the elements of the type
-are included in the switch a default clause should still be added (not
-all compilers diagnose missing elements).  In this case, the action in
-the default clause should be to generate an error and abort.
 
 \subsection{label Statements}
@@ -871,5 +827,5 @@
 \code{float myWidth;}\hfil\break
 \hfil\break
-\code{int psNumOTA;}\hfil\break
+\code{int pseudo;}\hfil\break
 \code{int p_psMyFiddleFactor;}\hfil\break