Index: /trunk/doc/misc/perlCodeConventions.tex
===================================================================
--- /trunk/doc/misc/perlCodeConventions.tex	(revision 2593)
+++ /trunk/doc/misc/perlCodeConventions.tex	(revision 2594)
@@ -1,3 +1,3 @@
-%%% $Id: perlCodeConventions.tex,v 1.42 2004-12-01 22:34:22 jhoblitt Exp $
+%%% $Id: perlCodeConventions.tex,v 1.43 2004-12-02 04:17:05 jhoblitt Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -54,7 +54,6 @@
 This document is derived from the Pan-STARRS IPP C Code Standards document
 (PSDC 430-004), which is derived from the Sun Microsystems Java language coding
-standards presented in the Java Language Specification
-
-(\code{http://java.sun.com/docs/books/jls/index.html}).
+standards presented in the Java Language Specification\footnote{The Java
+Language Specification - http://java.sun.com/docs/books/jls/index.html}.
 
 \begin{verbatim}
@@ -80,5 +79,5 @@
 common with Perl programmers.  Instead, it is an attempt to make the C and Perl
 coding styles as consistent as is reasonably feasible within the Pan-STARRS
-project.  This document only contains brief discussion of Perl's
+project.  This document contains only a brief discussion of Perl's
 Object-Oriented features and none of it's more advanced features.
 
@@ -129,7 +128,8 @@
 \hline
 \file{Makefile.PL}&
-The preferred name for the file that invokes a ``build'' process.  Typically
-this calls \code{ExtUtils::MakeMaker} or \code{Module::Build} setup the the
-necessary files to install a module or compile Swig generated C code.\\
+The preferred name for a file that invokes a ``build'' process.  Typically this
+calls \code{ExtUtils::MakeMaker} or \code{Module::Build} setup the the
+necessary files to build and install a module or compile Swig generated C
+code.\\
 \end{tabular}
 \end{center}
@@ -178,5 +178,5 @@
 not allowed).  Where \code(requirement = revision + version / 1000 + subversion
 / 1\_000\_000).  e.g. A minimum requirement of \code{perl} 5.8.5 would be
-expressed as \code{use 5.008005}
+expressed as \code{use 5.008005}.
 
 \item 
@@ -226,5 +226,5 @@
 not allowed).  Where \code(requirement = revision + version / 1000 + subversion
 / 1\_000\_000).  e.g. A minimum requirement of \code{perl} 5.8.5 would be
-expressed as \code{use 5.008005}
+expressed as \code{use 5.008005}.
 
 \item 
@@ -268,6 +268,43 @@
 \label{pod} 
 
-This is the format for documentation in a \code{.pod} file that should
-accompany a module.
+Pod files that accompany a module should have the following order:
+
+\begin{itemize}
+\item
+A \code{pod} command.
+
+\item
+A \code{NAME} section.
+
+\item
+A \code{SYNOPSIS} section.
+
+\item
+A \code{DESCRIPTION} section.
+
+\item
+A \code{USAGE} section.
+
+\item
+A \code{DEVELOPER NOTES} section.
+
+\item
+A \code{CREDITS} section.
+
+\item
+A \code{SUPPORT} section.
+
+\item
+A \code{AUTHOR} section.
+
+\item
+A \code{COPYRIGHT} section.
+
+\item
+A \code{SEE ALSO} section.
+
+\item
+A \code{cut} command.
+\end{itemize}
 
 For an example of a properly organized Pod, see Pod File Example
@@ -334,9 +371,9 @@
 
 \begin{verbatim}
-    $longName1 = $longName2*($longName3 + $longName4 - $longName5) +
-        4*$longname6;                   # PREFER
+    $longName1 = $longName2 * ($longName3 + $longName4 - $longName5) +
+        4 * $longName6;                   # PREFER
     
-    $longName1 = $longName2*($longName3 + $longName4 -
-                           $longName5) + 4*$longname6; # AVOID 
+    $longName1 = $longName2 * ($longName3 + $longName4 -
+                           $longName5) + 4 * $longName6; # AVOID 
 \end{verbatim}
 
@@ -373,17 +410,17 @@
 \end{verbatim}
 
-When deactivating 3 or more lines of code an \code{if} statement should be used
-with a false boolean value.  The opening and closing of the \code{if} statement
-should be nested to the same depth as the surrounding code and the deactivated
-section should be indented.
+When deactivating 3 or more lines of code an embedded Pod statement should be
+used.  The opening statement should be \code{=for off} and the closing
+statement should be \code{=cut}.  The deactivated section should remain nested
+to the same depth as the surrounding code.
 
 Example of deactivating multiple lines of code.
 
 \begin{verbatim}
-    if (0) {
-        if ($foo) {
-            print("foo");
-        }
-    }
+    =for off
+    if ($foo) {
+        print("foo");
+    }
+    =cut
 \end{verbatim}
 
@@ -425,6 +462,6 @@
 
 Short comments can appear on a single line indented to the level of the code
-that follows.  The comment should appear above the code that it is describe and
-must have a space between the \code{#} and the first text.
+that follows.  The comment should appear above the code that it is describing
+and must have a space between the \code{#} and the first text.
 
 Example of a single-line comment.
@@ -512,5 +549,5 @@
 \end{verbatim}
 
-Do not put different types on the same line.  Example:
+Do not combine different types in the same declaration.  Example:
 
 \begin{verbatim}
@@ -659,6 +696,5 @@
 
 \item
-Closing brace \CODE.}. starts a line by itself.  Null statement should have the
-closing brace immediately after the opening brace.  e.g. \CODE.{}.
+Closing brace \CODE.}. starts a line by itself.
 
 \item
@@ -750,6 +786,5 @@
 \subsection{if, if-else, if-elsif-else Statements}
 
-\code{if} statements must always use braces \{\} around statements and parentheses
-() around conditionals.
+\code{if} statements must always use parentheses \code{()} around conditionals.
 
 The \code{if-else} class of statements should have the following form:
@@ -865,4 +900,16 @@
 \end{verbatim}
 
+\subsection{Blocks}
+
+The contense of a block should be idented one level.
+
+\begin{verbatim}
+    $foo = foobar($baz);
+    {
+        my $bat = fooBaz();
+        ...
+    }
+\end{verbatim}
+
 
 %------------------------------------------------------------------------------
@@ -949,6 +996,6 @@
 \begin{itemize}
 \item
-A dereferencing or method call should not have any blank spaces around the
-\code{->} operator.
+A variable dereference or method call should not have any blank spaces around
+the \code{->} operator.
 
 \begin{verbatim}
@@ -958,4 +1005,6 @@
 
 \end{itemize}
+
+
 %------------------------------------------------------------------------------
 
@@ -1051,8 +1100,5 @@
 Constants &
 
-Constant names should be in all capital letters and highly descriptive.  The
-\code{constant} pragma should be used to declare constants.
-\emph{``constants'' created this way can not be interpolated inside of double
-quoted strings.}
+Constant names should be in all capital letters and highly descriptive.
 
 &
@@ -1119,4 +1165,10 @@
 in a \code{for} loop as counter values.  
 
+The \code{constant} pragma should be used to declare constants.
+\emph{``constants'' created this way can not be interpolated inside of double
+quoted strings.}
+
+See the \code{constant} module's Pod for further details.
+
 \subsection{Variable Assignments}
 
@@ -1138,5 +1190,5 @@
 \end{verbatim}
 
-should be written as
+should be written as:
 
 \begin{verbatim}