Changeset 2377

Timestamp:

Nov 16, 2004, 12:15:07 PM (22 years ago)

Author:

jhoblitt

Message:

add appendices for example source and perltidy

Location:

trunk/doc/misc

Files:

• .perltidyrc (added)
• parseErrorCodes.pl (added)
• perlCodeConventions.tex (modified) (6 diffs)

trunk/doc/misc/perlCodeConventions.tex

@@ -1 @@
-%%% $Id: perlCodeConventions.tex,v 1.18 2004-11-16 21:20:22 jhoblitt Exp $
+%%% $Id: perlCodeConventions.tex,v 1.19 2004-11-16 22:15:07 jhoblitt Exp $
 \documentclass[panstarrs]{panstarrs}
+
+\usepackage{verbatim}
 
 % basic document variables
@@ -12 +14 @@
 \organization{Institute for Astronomy}
 \version{DR01}
-\docnumber{PSDC-430-010-DR}
+\docnumber{PSDC-430-010}
 
 \begin{document}
@@ -726 +728 @@
 the compound statement; the closing brace should begin a line and be
 indented to the beginning of the compound statement.
+\end{itemize}
 
 \subsection{return Statements}
@@ -1170 +1173 @@
 \end{verbatim}
 
-\end{document}
 %------------------------------------------------------------------------------
 \appendix                               %Begin Appendices
@@ -1179 +1181 @@
 \label{SourceExample} 
 
-And here's the C source; \file{psUtils.h} provides \code{psAlloc/psFree}.
-
-\begin{verbatim}
-/*
- * This file implements an example of formatting a file of C code
- *
- * It isn't a very good piece of code
- */
-#include <stdlib.h>
-#include <stdio.h>
-#include <string.h>
-#include <assert.h>
-#include <time.h>
-#include "psUtils.h"
-#include "psBuffer.h"
-
-typedef enum { CRNL, NL } NLType;
-
-static char *getNewline(NLType type);   // return a suitable newline
-
-static psBuffer *buf = NULL;            // I/O buffer
-
-/*****************************************************************************/
-/*
- * Create/destroy psBuffers
- */
-psBuffer *psBufferAlloc(void)
-{
-    psBuffer *buf = psAlloc(sizeof(psBuffer));
-    buf->n = 0;
-
-    return buf;
-}
-
-void psBufferFree(psBuffer *buf,         // buffer to delete
-                 int deep)              // NOTUSED. Do a deep delete
-{
-    if (buf == NULL) {
-        return;
-    }
-    
-    if (buf->n > 0) {
-        (void)fputs(buf->buf, stdout);
-    }
-    
-    psFree(buf);
-}
-
-/*****************************************************************************/
-/*
- * Append to a string to a psBuffer
- */
-void psBufferAppend(psBuffer *restrict buf, // psBuffer to append to
-                    const char *restrict str) // string to add
-{
-    assert(str != NULL);
-    const int len = strlen(str);
-
-    if (buf->n + len >= PS_BUFSIZE) {   // XXX Handle this better
-        fprintf(stderr, "Sorry; too many bytes. Bye bye\n");
-        abort();
-        exit(1);                        // NOTREACHED
-    }
-
-    (void)strcat(&buf->buf[buf->n], str);
-    buf->n += len;
-}    
-
-/*****************************************************************************/
-/*
- * Now do the work
- */
-int main(void)
-{
-    buf = psBufferAlloc();
-    long t;                               // current time
-
-    while(t = (long)time(NULL), t%3 == 2) {}
-    
-    if (t%3 == 0) {
-        psBufferAppend(buf, "Hello");
-    } else if (t%3 == 1) {
-        psBufferAppend(buf, "Aloha");
-    }
-    psBufferAppend(buf, " World!");
-
-    psBufferAppend(buf, getNewline(NL));
-
-    psBufferFree(buf, 0);
-
-    return 0;
-}
-
-/*****************************************************************************/
-/*
- * Return a desired line terminator
- */
-static char *getNewline(NLType type)    // what sort of newline?
-{
-    char *newline;                      // newline to add
-    switch (type) {
-      case CRNL:
-        newline = "\r\n";
-        break;
-
-      case NL:
-        newline = "\n";
-        break;
-
-      default:
-        newline = "NL";                     // FIXME
-        break;
-    }
-
-    return newline;
-}
-\end{verbatim}
+An example of \file{parseErrorCode.pl} that conforms with the Perl code
+convention.
+
+\verbatiminput{parseErrorCodes.pl}
 
 %------------------------------------------------------------------------------
@@ -1302 +1191 @@
 \label{perltidy}
 
-The purpose of a coding standard is to improve coding efficiency, not
-to hinder it.  Since people are inherently falible, 100\% adherence to
-the standard is an impossible goal for human-generated code.
-Furthermore, laziness and slopiness are human nature.  To minimize the
-amount of effort spent in keeping software in line with a coding
-standard is to use automatic re-formatting tools to enforce the
-standard.  Various software tools exist to perform these tasks.  One
-of these is \code{astyle}, an open-source tool which takes a variety
-of options which allow the use to tailor the coding standard to suit
-their preferences.  We have determined the following collection of
-astyle options which achieve the many of the coding standard
-guidelines specified above.  Note that any of the listed options
-(always in the 'long' form) may be specified in the user's
-\code{.astylerc} file by dropping the leading dash.
-
-\begin{itemize}
-\item \code{--mode=c} - This option tells \code{astyle} to recognize
-  the source code as C code.
-
-\item \code{--indent-switches} - This option tells \code{astyle} to
-  indent the \code{case} statements in a \code{switch}.  Do not also
-  specify \code{--indent-cases}.
-
-\item \code{--indent-labels} - This option tells \code{astyle} to add
-  indentation to labels so they are indented one level less than the
-  current level.
-
-\item \code{--min-conditional-indent=0} - This option tells
-  \code{astyle} not to add indentation to successive lines of
-  multiple-line conditional statements.
-
-\item \code{--max-instatement-indent=20} - This option tells
-  \code{astyle} to limit the total amount of indentation to 20 spaces.
-
-\item \code{--pad=oper} - This option tells \code{astyle} to add
-  padding about binary operators.
-
-\item \code{--brackets=break} - This option tells \code{astyle} to
-  break brackets from their pre-block statements, dropping them to the
-  next line.
-
-\item \code{--convert-tabs} - This option tells \code{astyle} to
-  convert tabs into the equivalent number of space characters.
-
-\item \code{--indent=spaces=4} - This option tells \code{astyle} to
-  use 4 spaces per indent level.
-\end{itemize}
+\code{pertidy} is a Perl specific code ``beautifier'' with functionality
+similar to \code{indent} or \code{astyle}.  It is freely avalible from
+\code{http://perltidy.sourceforge.net/}.
+
+\code{pertidy} can be configured with either command line switches or a
+\file{.perltidyrc} file in your home directory.
+
+Example \file{.perltidyrc} file to acheive the Perl code convention:
+
+\verbatiminput{.perltidyrc}
 
 \bibliographystyle{plain}