/*::.
==================================================================================================================================
=================================================¦ Copyright © 2014 Allen Baker ¦=================================================
                                                 +------------------------------+
File:       SourceCodeFileCFamily.java
Originator: Allen Baker (2014.06.24 15:26)
LayoutRev:  5
================================================================================================================================== */
package cosmicabyss.com.lib;

import java.io.*;
import java.util.*;
import java.net.*;
import java.util.regex.*;
import java.lang.reflect.*;



/*::
======================================================================================================================== *//**
Instances of this class represent a source code file for a programming language that is derived from the C
programming language. This includes among others C, C++, C#, and Java.<P>

Salient characteristics of a SourceCodeFileCFamily are:
<BLOCKQUOTE>
   => It contains programming language source code such as C, C++, C#, Java, etc..
</BLOCKQUOTE>

This class is derived from the SourceCodeFile class. The abstraction it layers on top of SourceCodeFile includes the
following:
<BLOCKQUOTE>
   => It is a collection of computer instructions (including comments) written using a programming language derived
      from the C Programming Language.
</BLOCKQUOTE>

<P>
<DL>
   <DT>
      <B>Example usage:</B>
      <DD>
         <PRE>
            *java cosmicabyss.com.app.SourceCodeFileCFamily -t cpp
         </PRE>
      </DD>
   </DT>
   <DT>
      <B>View Source:</B>
      <DD>
         <A href="SourceCodeFileCFamily.java.html">SourceCodeFileCFamily.java</A>
      </DD>
   </DT>
   <DT>
      <B>Author:</B>
      <DD>
         <A href="mailto:sourcecode.v01@cosmicabyss.com">
            Allen Baker
         </A>
      </DD>
   </DT>
</DL>
*//*
======================================================================================================================== */
public class SourceCodeFileCFamily extends SourceCodeFile
   {



   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Constants  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
   ============================================================================================================== */



   /*.
   ==========================================================================================
   CLASS_NAME:
      the name of this class
   DFLT_LINE_LEN:
      the default line length for word wrapping
   ------------------------------------------------------------------------------------------ */
   private static final XString  CLASS_NAME    = new XString(SourceCodeFileCFamily.class.getName());
   /*.
   ==========================================================================================
   this keeps track of the width of the end-of-function-header comment lines so all of them
   can be replaced with one of the new style and size.
   ------------------------------------------------------------------------------------------ */
   private static HashSet<XString>  cEndOfHeaderLineSet = null;



   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Types  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Enums  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Structs  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Classes  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Interfaces  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Variables  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
   ============================================================================================================== */



   /*.
   ==========================================================================================
   cOut:
      formatted and time-stamped console output.
   cTempFilenameRoot:
      The root of a temporary file name that is used for creating modified versions of
      existing files.
   ------------------------------------------------------------------------------------------ */
   private static ConsoleStream  cOut              = ConsoleStream.getSingleton();
   private static String         cTempFilenameRoot = "SourceCodeFileCFamily-";



   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Functions  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Constructors  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates a SourceCodeFile class Object.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#000">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public SourceCodeFileCFamily(File pFile) throws Exception
      {
      super(pFile.getCanonicalPath());
      throwExceptionOnThisFile(new XString(pFile.getCanonicalPath()));
      initializeInstanceConstantsAndVariables();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates a SourceCodeFile class Object.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#001">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public SourceCodeFileCFamily(XFile pXFile) throws Exception
      {
      super(pXFile.getCanonicalPath());
      throwExceptionOnThisFile(new XString(pXFile.getCanonicalPath()));
      initializeInstanceConstantsAndVariables();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates a SourceCodeFile class Object.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#002">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public SourceCodeFileCFamily(TextFile pTextFile) throws Exception
      {
      super(pTextFile.getCanonicalPath());
      throwExceptionOnThisFile(new XString(pTextFile.getCanonicalPath()));
      initializeInstanceConstantsAndVariables();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates a SourceCodeFile class Object.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#003">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public SourceCodeFileCFamily(SourceCodeFile pSourceCodeFile) throws Exception
      {
      super(pSourceCodeFile.getCanonicalPath());
      throwExceptionOnThisFile(new XString(pSourceCodeFile.getCanonicalPath()));
      initializeInstanceConstantsAndVariables();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates a SourceCodeFile class Object.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#004">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public SourceCodeFileCFamily(URI pUri) throws Exception
      {
      super(pUri);
      throwExceptionOnThisFile(new XString(pUri));
      initializeInstanceConstantsAndVariables();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates a SourceCodeFile class Object.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#005">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public <Type1> SourceCodeFileCFamily(File pParent,Type1 pChild) throws Exception
      {
      super(pParent,pChild);
      throwExceptionOnThisFile(new XString(pChild));
      initializeInstanceConstantsAndVariables();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates a SourceCodeFile class Object.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#006">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public <Type1> SourceCodeFileCFamily(Type1 pPathname) throws Exception
      {
      super(pPathname);
      throwExceptionOnThisFile(new XString(pPathname));
      initializeInstanceConstantsAndVariables();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates a SourceCodeFile class Object.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#007">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public <Type1,Type2> SourceCodeFileCFamily(Type1 pParent,Type2 pChild) throws Exception
      {
      super(pParent,pChild);
      throwExceptionOnThisFile(new XString(pChild));
      initializeInstanceConstantsAndVariables();
      }



   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Initialization  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */



   static
      {
      /*.
      ==========================================================================================
      make sure all the class constants and variables are initialized the first time the JVM
      loads this class code and before anything else in this class is accessed
      ------------------------------------------------------------------------------------------ */
      initializeClassConstantsAndVariables();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method initializes all the class constants and variables

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#008">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   private static void initializeClassConstantsAndVariables()
      {
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method initializes all the instance constants and variables. The intent of this method is to
   encapsulate all the common instance initializations in one place that can be called from all the
   constructors.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#009">View source</A>

   @return
      true if the initialization succeeded, flase otherwise.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   private boolean initializeInstanceConstantsAndVariables() throws Exception
      {
      boolean  successCode = true;

      return successCode;
      }



   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Methods  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method throws an exception if it is passed the name of this file

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#010">View source</A>

   @param
      pPathname is an XString containing the name of a file.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   private void throwExceptionOnThisFile(XString pPathname) throws Exception
      {
      /*.
      ==========================================================================================
      running SourceCodeFileCFamily.java on itself will completely screw up the code containing
      the substitution strings.
      ------------------------------------------------------------------------------------------ */
      if (pPathname.endsWithIgnoreCase("SourceCodeFileCFamily.java"))
         {
         throw new Exception("Cannot execute instances of this class on it's own source file: SourceCodeFileCFamily.java");
         }
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method calls all the comment fixing methods in the right order.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#011">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public void fixComments() throws Exception
      {
      this.fixHtmlElementIndentation();
      this.fixAllPreTags();
      this.replaceFileHeader();
      this.fixAllRegularComments();
      this.fixAllFunctionHeaders();
      this.wrapFunctionHeaders();
      this.fixAllFunctionHeadersExtraLine();
      this.fixAllObsoleteBanners();
      this.fixClassHeader();
      this.fixMissingNewlines();
      this.enclosePreElementsWithinBlockquoteElements();
      this.fixHtmlElementIndentation();
      this.miscCleanup();
      this.setEmptyLinesAtEof(1);
      this.setMaxConsecutiveEmptyLines(3);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method sets the indentation correct on the HTML elements we're interested in.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#012">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public void fixHtmlElementIndentation() throws Exception
      {
      /*.
      ==========================================================================================
      ------------------------------------------------------------------------------------------ */
      this.unwrapBlockDelimiters("<BLOCKQUOTE>", "</BLOCKQUOTE>");
      this.indentDelimitedBlockFromPriorText("<BLOCKQUOTE>", "</BLOCKQUOTE>");
      this.indentDelimitedBlockContentFromDelimiters("<BLOCKQUOTE>", "</BLOCKQUOTE>");
      /*.
      ==========================================================================================
      ------------------------------------------------------------------------------------------ */
      this.unwrapBlockDelimiters("<PRE>", "</PRE>");
      this.indentDelimitedBlockFromPriorText("<PRE>", "</PRE>");
      this.indentDelimitedBlockContentFromDelimiters("<PRE>", "</PRE>");
      /*.
      ==========================================================================================
      ------------------------------------------------------------------------------------------ */
      this.unwrapBlockDelimiters("<PRE id=\"unindent\">", "</PRE>");
      this.indentDelimitedBlockFromPriorText("<PRE id=\"unindent\">", "</PRE>");
      this.indentDelimitedBlockContentFromDelimiters("<PRE id=\"unindent\">", "</PRE>");
      /*.
      ==========================================================================================
      ------------------------------------------------------------------------------------------ */
      this.unwrapBlockDelimiters("<DL>", "</DL>");
      this.indentDelimitedBlockFromPriorText("<DL>", "</DL>");
      this.indentDelimitedBlockContentFromDelimiters("<DL>", "</DL>");
      /*.
      ==========================================================================================
      ------------------------------------------------------------------------------------------ */
      this.unwrapBlockDelimiters("<DT>", "</DT>");
      this.indentDelimitedBlockFromPriorText("<DT>", "</DT>");
      this.indentDelimitedBlockContentFromDelimiters("<DT>", "</DT>");
      /*.
      ==========================================================================================
      ------------------------------------------------------------------------------------------ */
      this.unwrapBlockDelimiters("<DD>", "</DD>");
      this.indentDelimitedBlockContentFromDelimiters("<DD>", "</DD>");
      /*.
      ==========================================================================================
      ------------------------------------------------------------------------------------------ */
      this.unwrapBlockDelimiters("<B>", "</B>");
      this.indentDelimitedBlockFromPriorText("<B>", "</B>");
      this.indentDelimitedBlockContentFromDelimiters("<B>", "</B>");
      /*.
      ==========================================================================================
      ------------------------------------------------------------------------------------------ */
      this.unwrapBlockDelimiters("<A href=\"mailto:sourcecode.v01@cosmicabyss.com\">", "</A>");
      this.indentDelimitedBlockFromPriorText("<A href=\"mailto:sourcecode.v01@cosmicabyss.com\">", "</A>");
      this.indentDelimitedBlockContentFromDelimiters("<A href=\"mailto:sourcecode.v01@cosmicabyss.com\">", "</A>");
      /*.
      ==========================================================================================
      ------------------------------------------------------------------------------------------ */
      String  thisFileName = this.getName();
      String  sourceLink   = "<A href=\"" + thisFileName + ".html\">";
      this.unwrapBlockDelimiters(sourceLink, "</A>");
      this.indentDelimitedBlockFromPriorText(sourceLink, "</A>");
      this.indentDelimitedBlockContentFromDelimiters(sourceLink, "</A>");
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method cleans up any messes that aren't worth troubleshooting or resolving the root cause.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#013">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public void miscCleanup() throws Exception
      {
      this.modify("miscCleanup");
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method cleans up any messes that aren't worth troubleshooting or resolving the root cause.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#014">View source</A>

   @param
      pIter is an XStringsIterator for reading the input file
   @param
      pOutput is a TextWriter for writing the modified content of the input file to the output file.
   @param
      pArguments is a variable sized list of arguments. This method does not expect it to contain any
      values.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public void miscCleanup(XStringsIterator pIter, TextWriter pOutput, Object... pArguments) throws Exception
      {
      /*.
      ==========================================================================================
      put the entire content of the input file into a StringBuffer
      ------------------------------------------------------------------------------------------ */
      StringBuffer  theWholeFile = new StringBuffer(2 * UMath.ONE_MEG);
      while (pIter.hasNext())
         {
         XString  s = pIter.next();
         s = s.trimRight();
         s = s.concat("\n");
         theWholeFile.append(s.toString());
         }
      /*.
      ==========================================================================================
      put the entire content of the input file into a String and release the StringBuffer for
      the garbage collector.
      ------------------------------------------------------------------------------------------ */
      XString  theWholeFileString = new XString(theWholeFile);
      theWholeFile = null;
      /*.
      ==========================================================================================
      replace all the old end of function headers with the new one.
      ------------------------------------------------------------------------------------------ */
      theWholeFileString = theWholeFileString.replace(">View source\n   </A>", ">View source</A>");
      /*.
      ==========================================================================================
      done.
      ------------------------------------------------------------------------------------------ */
      pOutput.println(theWholeFileString);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method replaces unattributed pre tags with attributed ones.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#015">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public void fixAllPreTags() throws Exception
      {
      this.modify("fixAllPreTags");
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method replaces unattributed pre tags with attributed ones.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#016">View source</A>

   @param
      pIter is an XStringsIterator for reading the input file
   @param
      pOutput is a TextWriter for writing the modified content of the input file to the output file.
   @param
      pArguments is a variable sized list of arguments. This method does not expect it to contain any
      values.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public void fixAllPreTags(XStringsIterator pIter, TextWriter pOutput, Object... pArguments) throws Exception
      {
      XString  currentLine        = new XString("");
      XString  currentLineTrimmed = new XString("");
      /*.
      ==========================================================================================
      retrieve and process every line of the file separately and in order
      ------------------------------------------------------------------------------------------ */
      while (pIter.hasNext())
         {
         /*.
         ==========================================================================================
         get the next current line from the file and make a trimmed copy of it
         ------------------------------------------------------------------------------------------ */
         currentLine        = pIter.next().trimRight();
         currentLineTrimmed = currentLine.trim();
         /*.
         ==========================================================================================
         Assign the unindent id to plain start pre tags
         ------------------------------------------------------------------------------------------ */
         if (currentLineTrimmed.equalsIgnoreCase("<PRE>"))
            {
            currentLine = currentLine.replace("<PRE>", "<PRE id=\"unindent\">");
            }
         /*.
         ==========================================================================================
         now after all that, output this line with any additional indentation that is indicated by
         the indentation counter.
         ------------------------------------------------------------------------------------------ */
         pOutput.println(currentLine.toString());
         }
      }



   public <Type1> void enclosePreElementsWithinBlockquoteElements() throws Exception
      {
      this.modify("enclosePreElementsWithinBlockquoteElements");
      }


   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method ensures that each HTML PRE element in the file are enclosed within an HTML BLOCKQUOTE
   element.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#017">View source</A>

   @param
      pIter is an XStringsIterator for reading the input file
   @param
      pOutput is a TextWriter for writing the modified content of the input file to the output file.
   @param
      pArguments is a variable sized list of arguments. This method does not expect it to contain any
      values.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public void enclosePreElementsWithinBlockquoteElements(XStringsIterator pIter, TextWriter pOutput, Object... pArguments) throws Exception
      {
      /*.
      ==========================================================================================
      Nested pre elements make no sense and should not occur, but since they CAN, we have to
      handle them when they do. So we keep a stack of the indents and push onto it every time we
      encounter a start pre tag and pop off of it every time we encounter an end pre tag. We
      also keep a counter of the nesting levels. This whole scheme fails if there is a pre
      element that is already enclosed in a blockquote element and which is nested within a
      higher-level pre element that is not enclosed within a blockquote element. But that is so
      unlikely that it doesn't justify the extra coding required to handle it.
      ------------------------------------------------------------------------------------------ */
      Stack<XString>  indentStack           = new Stack<XString>();
      int             blockquoteNeeded      = 0;
      boolean         lastLineWasBlockquote = false;
      XString         indent                = null;
      XString         thisLine              = null;
      XString         trimmedLine           = null;
      while (pIter.hasNext())
         {
         thisLine    = pIter.next();
         trimmedLine = thisLine.trim();
         /*.
         ==========================================================================================
         if this line is a pre tag, check to see if it was immediately preceeded by a blockquote
         tag. if not, inject a blockquote tag into the file before this line. Then remember that
         this pre tag element was not enclose in a blockquote element so that when the end pre tag
         shows up, we can inject the end blockquote tag just after it in the file.
            When we inject the blockquote tag into the file, we unindent it one tab (three spaces)
            relative to the line containing the pre tag.
         ------------------------------------------------------------------------------------------ */
         if (trimmedLine.startsWithIgnoreCase("<PRE"))
            {
            if (! lastLineWasBlockquote)
               {
               indent = thisLine.whitespacePrefix();
               indent = indent.substring(0, UMath.max(0, indent.length()-3));
               pOutput.println(indent.toString() + "<BLOCKQUOTE>");
               blockquoteNeeded++;
               indentStack.push(indent);
               }
            pOutput.println(thisLine.toString());
            }
         /*.
         ==========================================================================================
         if this line is an end pre tag, then if we remembered that this pre tag element was not
         enclose in a blockquote element, we will inject the end blockquote tag just after this end
         pre tag line in the file.
            When we inject the end blockquote tag into the file, we unindent it one tab (three
            spaces) relative to the line containing the pre tag.
         ------------------------------------------------------------------------------------------ */
         else if (trimmedLine.startsWithIgnoreCase("</PRE"))
            {
            pOutput.println(thisLine.toString());
            if (blockquoteNeeded > 0)
               {
               pOutput.println(indentStack.pop().toString() + "</BLOCKQUOTE>");
               blockquoteNeeded--;
               }
            }
         /*.
         ==========================================================================================
         otherwise, this line is neither a pre tag nor an end pre tag so just write it out to the
         file.
         ------------------------------------------------------------------------------------------ */
         else
            {
            pOutput.println(thisLine.toString());
            }
         /*.
         ==========================================================================================
         keep track of whether or not the most recent nonblank line was a blockquote
         ------------------------------------------------------------------------------------------ */
         if (! trimmedLine.equals(""))
            {
            lastLineWasBlockquote = trimmedLine.startsWithIgnoreCase("<BLOCKQUOTE>");
            }
         }
      }



   public void fixAllFunctionHeaders() throws Exception
      {
      /*.
      ==========================================================================================
      ------------------------------------------------------------------------------------------ */
      XString o00 = new XString
         (
         "   ==============================================================\n"       +
         "   ============================================================== *//**\n"
         );
      XString n00 = new XString
         (
         "   ==============================================================\n"       +
         "   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]\n"       +
         "   ============================================================== *//**\n"
         );
      /*.
      ==========================================================================================
      ------------------------------------------------------------------------------------------ */
      XString[][] strPairs =
         {
            { o00, n00 },
         };
      this.replace(strPairs);
      /*.
      ==========================================================================================
      ------------------------------------------------------------------------------------------ */
      this.modify("fixAllFunctionHeadersTop");
      this.modify("fixAllFunctionHeadersBottom");
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method puts the header comment's prefix in if it is not there.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#018">View source</A>

   @param
      pIter is an XStringsIterator for reading the input file
   @param
      pOutput is a TextWriter for writing the modified content of the input file to the output file.
   @param
      pArguments is a variable sized list of arguments. This method does not expect it to contain any
      values.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public void fixAllFunctionHeadersTop(XStringsIterator pIter, TextWriter pOutput, Object... pArguments) throws Exception
      {
      /*.
      ==========================================================================================
      This method only replaces the top banner of a function header. The bottom banner is
      replaced by fixAllFunctionHeadersBottom(). To communicate the String that is the bottom
      banner to fixAllFunctionHeadersBottom(), we GENERATE a copy of the bottom banner string
      and put it in a HashSet for use by fixAllFunctionHeadersBottom().
      fixAllFunctionHeadersBottom() will replace all the Strings in that HashSet with the new
      bottom banner String.
      ------------------------------------------------------------------------------------------ */
      cEndOfHeaderLineSet = new HashSet<XString>();
      /*.
      ==========================================================================================
      ------------------------------------------------------------------------------------------ */
      boolean  skippingLines      = false;
      int      skippedLineCounter = 0;
      XString  trimmedLine        = null;
      XString  thisLine           = null;
      while (pIter.hasNext())
         {
         thisLine    = pIter.next();
         trimmedLine = thisLine.trim();
         /*.
         ==========================================================================================
         Put the colon character that is a code meaning "this comment starts a function header" on
         the starting comment delimiter of function headers.
         ------------------------------------------------------------------------------------------ */
         if (trimmedLine.startsWith("/*") && trimmedLine.contains(":METHOD"))
            {
            thisLine = thisLine.replace("/* ", "/*:");
            trimmedLine = thisLine.trim();
            }
         /*.
         ==========================================================================================
         Now, if the current line has the comment delimiter with the colon code, replace it with a
         complete top function header banner comment and begin skipping the lines in the input file
         until past the old top function header banner comment.
         ------------------------------------------------------------------------------------------ */
         if (trimmedLine.equals("/*:") || trimmedLine.startsWith("/*: "))
            {
            skippingLines = true;
            skippedLineCounter = 1;
            XString  whitespacePrefix = thisLine.whitespacePrefix();
            pOutput.println(whitespacePrefix + "/*:");
            pOutput.println(whitespacePrefix + "===================================================================================================="       );
            pOutput.println(whitespacePrefix + "[][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]"       );
            pOutput.println(whitespacePrefix + "==================================================================================================== *//**" );
            }
         /*.
         ==========================================================================================
         Otherwise, we are not in a top function header banner comment in the input so ...
         ------------------------------------------------------------------------------------------ */
         else
            {
            /*.
            ==========================================================================================
            If we're not currently skipping the lines of the old top function header banner comment,
            then send the current line to the output.
            ------------------------------------------------------------------------------------------ */
            if (! skippingLines)
               {
               pOutput.println(thisLine.toString());
               }
            /*.
            ==========================================================================================
            If we're ARE currently skipping the lines of the old top function header banner comment
            ...
            ------------------------------------------------------------------------------------------ */
            else
               {
               skippedLineCounter++;
               /*.
               ==========================================================================================
               The lines immediately after the starting comment delimiter of the old top function header
               banner comment are identifiable by the pattern of characters they start with. If this line
               fits the pattern, then use it to generate a replica of a potential old bottom function
               header banner line and put it into the HashSet. The lines in the HashSet will be replaced
               with a new bottom function header banner line.
               ------------------------------------------------------------------------------------------ */
               if ((trimmedLine.startsWith("==========")) || (trimmedLine.startsWith("[][][][][]")))
                  {
                  if (skippedLineCounter == 2)
                     {
                     XString endOfHeaderLine = new XString(" " + trimmedLine.replace("=", "-").replace("[", "-").replace("]", "-").concat(" ").toString());
                     cEndOfHeaderLineSet.add(endOfHeaderLine);
                     }
                  }
               /*.
               ==========================================================================================
               If the current line is not identifiable by the pattern, then we have skipped over the old
               top function header banner and are now into the content of the function header comment. So
               turn off line skipping and send the current line to the output.
               ------------------------------------------------------------------------------------------ */
               else
                  {
                  skippingLines = false;
                  skippedLineCounter = 0;
                  if ( !trimmedLine.equals("")) pOutput.println(thisLine.toString());
                  }
               }
            }
         }
      /*.
      ==========================================================================================
      Finish writing the pOutput file, flush its buffers to physical storage, and close the file.
      ------------------------------------------------------------------------------------------ */
      while (pIter.hasNext())
         {
         thisLine = pIter.next();
         pOutput.println(thisLine.toString());
         }
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method puts the header comment's prefix in if it is not there.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#019">View source</A>

   @param
      pIter is an XStringsIterator for reading the input file
   @param
      pOutput is a TextWriter for writing the modified content of the input file to the output file.
   @param
      pArguments is a variable sized list of arguments. This method does not expect it to contain any
      values.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public void fixAllFunctionHeadersBottom(XStringsIterator pIter, TextWriter pOutput, Object... pArguments) throws Exception
      {
      /*.
      ==========================================================================================
      put the entire content of the input file into a StringBuffer
      ------------------------------------------------------------------------------------------ */
      StringBuffer  theWholeFile = new StringBuffer(2 * UMath.ONE_MEG);
      while (pIter.hasNext())
         {
         XString  s = pIter.next();
         s = s.trimRight();
         s = s.concat("\n");
         theWholeFile.append(s.toString());
         }
      /*.
      ==========================================================================================
      put the entire content of the input file into a String and release the StringBuffer for
      the garbage collector.
      ------------------------------------------------------------------------------------------ */
      String  theWholeFileString = theWholeFile.toString();
      theWholeFile = null;
      /*.
      ==========================================================================================
      replace all the old end of function headers with the new one.
      ------------------------------------------------------------------------------------------ */
      XString    endHeader = new XString(" ---------------------------------------------------------------------------------------------------- ");
      XString[]  y         = cEndOfHeaderLineSet.toArray(new XString[cEndOfHeaderLineSet.size()]);
      for (int idx = 0; idx < y.length; idx++)
         {
         theWholeFileString = theWholeFileString.replace(y[idx].toString(), endHeader.toString());
         }
      /*.
      ==========================================================================================
      done.
      ------------------------------------------------------------------------------------------ */
      pOutput.println(theWholeFileString);
      }



   public <Type1> void wrapFunctionHeaders() throws Exception
      {
      this.wrapCommentText
         (
         new XString(" ==================================================================================================== *//**"),
         new XString(" ---------------------------------------------------------------------------------------------------- */"),
         "====================================================================================================".length()
         );
      }


   public void fixMissingNewlines() throws Exception
      {
      XString[][] strPairs = new XString[1][2];

      strPairs[0][0] = new XString("View source</A> *//*");
      strPairs[0][1] = new XString("View source</A>\n\n   *//*");

      this.replace(strPairs);
      }


   public void fixAllFunctionHeadersExtraLine() throws Exception
      {
      XString[][] strPairs = new XString[6][2];

      strPairs[0][0] = new XString
         (
         "\n" +
         "   /*:\n" +
         "   ====================================================================================================\n" +
         "   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]\n" +
         "   ==================================================================================================== *//**\n" +
         "\n" +
         "\n"
         );
      strPairs[0][1] = new XString
         (
         "\n" +
         "   /*:\n" +
         "   ====================================================================================================\n" +
         "   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]\n" +
         "   ==================================================================================================== *//**\n"
         );
      strPairs[1][0] = new XString
         (
         "\n" +
         "      /*:\n" +
         "      ====================================================================================================\n" +
         "      [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]\n" +
         "      ==================================================================================================== *//**\n" +
         "\n" +
         "\n"
         );
      strPairs[1][1] = new XString
         (
         "\n" +
         "      /*:\n" +
         "      ====================================================================================================\n" +
         "      [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]\n" +
         "      ==================================================================================================== *//**\n"
         );
      strPairs[2][0] = new XString
         (
         "\n" +
         "         /*:\n" +
         "         ====================================================================================================\n" +
         "         [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]\n" +
         "         ==================================================================================================== *//**\n" +
         "\n" +
         "\n"
         );
      strPairs[2][1] = new XString
         (
         "\n" +
         "         /*:\n" +
         "         ====================================================================================================\n" +
         "         [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]\n" +
         "         ==================================================================================================== *//**\n"
         );


      strPairs[3][0] = new XString
         (
         "\n" +
         "   /*:\n" +
         "   ====================================================================================================\n" +
         "   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]\n" +
         "   ==================================================================================================== *//**\n" +
         "\n"
         );
      strPairs[3][1] = new XString
         (
         "\n" +
         "   /*:\n" +
         "   ====================================================================================================\n" +
         "   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]\n" +
         "   ==================================================================================================== *//**\n"
         );
      strPairs[4][0] = new XString
         (
         "\n" +
         "      /*:\n" +
         "      ====================================================================================================\n" +
         "      [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]\n" +
         "      ==================================================================================================== *//**\n" +
         "\n"
         );
      strPairs[4][1] = new XString
         (
         "\n" +
         "      /*:\n" +
         "      ====================================================================================================\n" +
         "      [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]\n" +
         "      ==================================================================================================== *//**\n"
         );
      strPairs[5][0] = new XString
         (
         "\n" +
         "         /*:\n" +
         "         ====================================================================================================\n" +
         "         [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]\n" +
         "         ==================================================================================================== *//**\n" +
         "\n"
         );
      strPairs[5][1] = new XString
         (
         "\n" +
         "         /*:\n" +
         "         ====================================================================================================\n" +
         "         [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]\n" +
         "         ==================================================================================================== *//**\n"
         );


      this.replace(strPairs);
      }



   public <Type1, Type2> void addPrefixToHeader(Type1 pCriteria, Type2 pPrefix) throws Exception
      {
      this.modify("addPrefixToHeader", UString.toString(pCriteria), UString.toString(pPrefix));
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method puts the header comment's prefix in if it is not there.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#020">View source</A>

   @param
      pIter is an XStringsIterator for reading the input file
   @param
      pOutput is a TextWriter for writing the modified content of the input file to the output file.
   @param
      pArguments is a variable sized list of arguments and this method expects it to contain these 2
      values in the first and second elements of the list respectively:
         <PRE>
            pCriteria is the header comment banner top to look for
            pPrefix is the prefix to add
         </PRE>
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public <Type1,Type2> void addPrefixToHeader(XStringsIterator pIter, TextWriter pOutput, Object... pArguments) throws Exception
      {
      /*.
      ==========================================================================================
      get the arguments
      ------------------------------------------------------------------------------------------ */
      String  criteria = UString.toString(pArguments[0]);
      String  prefix   = UString.toString(pArguments[1]);
      /*.
      ==========================================================================================
      read each line of the source file and write it out without a newline
      ------------------------------------------------------------------------------------------ */
      XString  prevLine = null;
      XString  line     = null;
      while (pIter.hasNext())
         {
         line = pIter.next();
         if (prevLine != null)
            {
            if (line.trim().equals(criteria) && prevLine.trim().equals("/*"))
               {
               prevLine = prevLine.trimRight().concat(prefix);
               }
            pOutput.println(prevLine);
            }
         prevLine = line;
         }
      pOutput.println(line);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method replaces all the inline code comment blocks with up-to-date ones regardless of whether
   or not they are already up-to-date.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#021">View source</A>

   @param
      pInPathname is the name of the file that will be copied to the output file with the modifications
      that this method performs. pOutPathname must not be the same as pInPathname. pOutPathname and
      pInPathname must not be null.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public void fixAllRegularComments() throws Exception
      {
      /*.
      ==========================================================================================
      ------------------------------------------------------------------------------------------ */
      XString[][] strPairs =
         {
            { new XString("<a href"),       new XString("<A href")       },
            { new XString("</a>"),          new XString("</A>")          },
            { new XString("<b>"),           new XString("<B>")           },
            { new XString("</b>"),          new XString("</B>")          },
            { new XString("<dd>"),          new XString("<DD>")          },
            { new XString("</dd>"),         new XString("</DD>")         },
            { new XString("<dt>"),          new XString("<DT>")          },
            { new XString("</dt>"),         new XString("</DT>")         },
            { new XString("<dl>"),          new XString("<DL>")          },
            { new XString("</dl>"),         new XString("</DL>")         },
            { new XString("<p>"),           new XString("<P>")           },
            { new XString("</p>"),          new XString("</P>")          },
            { new XString("<pre"),          new XString("<PRE")          },
            { new XString("</pre>"),        new XString("</PRE>")        },
            { new XString("<blockquote>"),  new XString("<BLOCKQUOTE>")  },
            { new XString("</blockquote>"), new XString("</BLOCKQUOTE>") },
            { new XString("<table>"),       new XString("<TABLE>")       },
            { new XString("</table>"),      new XString("</TABLE>")      },
            { new XString("<tt>"),          new XString("<TT>")          },
            { new XString("</tt>"),         new XString("</TT>")         },
            { new XString("<td>"),          new XString("<TD>")          },
            { new XString("</td>"),         new XString("</TD>")         },
            { new XString("<tr>"),          new XString("<TR>")          },
            { new XString("</tr>"),         new XString("</TR>")         },
            { new XString("<i>"),           new XString("<I>")           },
            { new XString("</i>"),          new XString("</I>")          },
            { new XString("<ul>"),          new XString("<UL>")          },
            { new XString("</ul>"),         new XString("</UL>")         },
            { new XString("<li>"),          new XString("<LI>")          },
            { new XString("</li>"),         new XString("</LI>")         },
            { new XString("<code"),         new XString("<CODE")         },
            { new XString("</code>"),       new XString("</CODE>")       },
            { new XString("\n\n\n\n\n"),    new XString("\n\n\n\n")      },
            { new XString("\n\n\n\n\n"),    new XString("\n\n\n\n")      },
            { new XString("\n\n\n\n\n"),    new XString("\n\n\n\n")      },
            { new XString("\n=========================================================================== */"),                        new XString("======================================================================================================================== */")  },
            { new XString("  ===============================================\n"),                                                     new XString("  ==========================================================================================\n")  },
            { new XString("  ====================================================\n"),                                                new XString("  ==========================================================================================\n")  },
            { new XString("  ==========================================================================================\n"),          new XString("  ==========================================================================================\n")  },
            { new XString("  ===========================================================================================\n"),         new XString("  ==========================================================================================\n")  },
            { new XString("  ==============================================================================================\n"),      new XString("  ==========================================================================================\n")  },
            { new XString("  ================================================================================================\n"),    new XString("  ==========================================================================================\n")  },
            { new XString("  ----------------------------------------------- */"),                                                    new XString("  ------------------------------------------------------------------------------------------ */") },
            { new XString("  ---------------------------------------------------- */"),                                               new XString("  ------------------------------------------------------------------------------------------ */") },
            { new XString("  ------------------------------------------------------------------------------------------ */"),         new XString("  ------------------------------------------------------------------------------------------ */") },
            { new XString("  ------------------------------------------------------------------------------------------- */"),        new XString("  ------------------------------------------------------------------------------------------ */") },
            { new XString("  ---------------------------------------------------------------------------------------------- */"),     new XString("  ------------------------------------------------------------------------------------------ */") },
            { new XString("  ------------------------------------------------------------------------------------------------ */"),   new XString("  ------------------------------------------------------------------------------------------ */") },

            { new XString("  ----------------------------------------------- "),                                                      new XString("  ------------------------------------------------------------------------------------------ ") },
            { new XString("  ---------------------------------------------------- "),                                                 new XString("  ------------------------------------------------------------------------------------------ ") },
            { new XString("  ------------------------------------------------------------------------------------------ "),           new XString("  ------------------------------------------------------------------------------------------ ") },
            { new XString("  ------------------------------------------------------------------------------------------- "),          new XString("  ------------------------------------------------------------------------------------------ ") },
            { new XString("  ---------------------------------------------------------------------------------------------- "),       new XString("  ------------------------------------------------------------------------------------------ ") },
            { new XString("  ------------------------------------------------------------------------------------------------ "),     new XString("  ------------------------------------------------------------------------------------------ ") },

            { new XString("  -----------------------------------------------\n"),                                                     new XString("  ------------------------------------------------------------------------------------------\n") },
            { new XString("  ----------------------------------------------------\n"),                                                new XString("  ------------------------------------------------------------------------------------------\n") },
            { new XString("  ------------------------------------------------------------------------------------------\n"),          new XString("  ------------------------------------------------------------------------------------------\n") },
            { new XString("  -------------------------------------------------------------------------------------------\n"),         new XString("  ------------------------------------------------------------------------------------------\n") },
            { new XString("  ----------------------------------------------------------------------------------------------\n"),      new XString("  ------------------------------------------------------------------------------------------\n") },
            { new XString("  ------------------------------------------------------------------------------------------------\n"),    new XString("  ------------------------------------------------------------------------------------------\n") },


            { new XString("\n===============================================\n"),                                                     new XString("\n==========================================================================================\n")  },
            { new XString("\n====================================================\n"),                                                new XString("\n==========================================================================================\n")  },
            { new XString("\n==========================================================================================\n"),          new XString("\n==========================================================================================\n")  },
            { new XString("\n===========================================================================================\n"),         new XString("\n==========================================================================================\n")  },
            { new XString("\n==============================================================================================\n"),      new XString("\n==========================================================================================\n")  },
            { new XString("\n================================================================================================\n"),    new XString("\n==========================================================================================\n")  },
            { new XString("\n----------------------------------------------- */"),                                                    new XString("\n------------------------------------------------------------------------------------------ */") },
            { new XString("\n---------------------------------------------------- */"),                                               new XString("\n------------------------------------------------------------------------------------------ */") },
            { new XString("\n------------------------------------------------------------------------------------------ */"),         new XString("\n------------------------------------------------------------------------------------------ */") },
            { new XString("\n------------------------------------------------------------------------------------------- */"),        new XString("\n------------------------------------------------------------------------------------------ */") },
            { new XString("\n---------------------------------------------------------------------------------------------- */"),     new XString("\n------------------------------------------------------------------------------------------ */") },
            { new XString("\n------------------------------------------------------------------------------------------------ */"),   new XString("\n------------------------------------------------------------------------------------------ */") },
         };
      this.replace(strPairs);
      /*.
      ==========================================================================================
      add the prefix code
      ------------------------------------------------------------------------------------------ */
      this.addPrefixToHeader
         (
         new XString("=========================================================================================="),
         new XString(".")
         );
      this.addPrefixToHeader
         (
         new XString("======================================================================================================================== */"),
         new XString("::")
         );
      /*.
      ==========================================================================================
      wrap the comment text
      ------------------------------------------------------------------------------------------ */
      this.wrapCommentText
         (
         new XString(" ==========================================================================================\n"),
         new XString(" ------------------------------------------------------------------------------------------ "),
         "==========================================================================================".length()
         );
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method replaces the class header comment blocks with up-to-date ones regardless of whether
   or not it is already up-to-date.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#022">View source</A>

   @param
      pInPathname is the name of the file that will be copied to the output file with the modifications
      that this method performs. pOutPathname must not be the same as pInPathname. pOutPathname and
      pInPathname must not be null.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public void fixClassHeader() throws Exception
      {
      /*.
      ==========================================================================================
      ------------------------------------------------------------------------------------------ */
      XString[][] strPairs =
         {
            { new XString("\n=========================================================================== */"), new XString("\n======================================================================================================================== */")  },
         };
      this.replace(strPairs);
      /*.
      ==========================================================================================
      add the prefix code
      ------------------------------------------------------------------------------------------ */
      this.addPrefixToHeader
         (
         new XString("======================================================================================================================== *//*"),
         new XString("::")
         );
      /*.
      ==========================================================================================
      fix the comment banners
      ------------------------------------------------------------------------------------------ */
      XString[][] strPairs2 =
         {
            { new XString("/*======================================================================================================================== *//**"), new XString("/*::\n======================================================================================================================== *//**")  },
            { new XString("*//*======================================================================================================================== */"),  new XString("*//*\n======================================================================================================================== */")     },
         };
      this.replace(strPairs2);
      /*.
      ==========================================================================================
      wrap the comment text
      ------------------------------------------------------------------------------------------ */
      this.wrapCommentText
         (
         new XString("======================================================================================================================== *//**"),
         new XString("======================================================================================================================== */"),
         "========================================================================================================================".length()
         );
      /*.
      ==========================================================================================
      fix the extra line after the top of the header banner
      ------------------------------------------------------------------------------------------ */
      XString[][] strPairs3 =
         {
            { new XString("/*::\n======================================================================================================================== *//**\n\n"), new XString("/*::\n======================================================================================================================== *//**\n")  },
            { new XString("   /*::\n   ======================================================================================================================== *//**\n\n"), new XString("   /*::\n   ======================================================================================================================== *//**\n")  },
         };
      this.replace(strPairs3);
      /*.
      ==========================================================================================
      fix the screwed-up bottom header of indented (nested) classes -- ugly, ugly, ugly.
      ------------------------------------------------------------------------------------------ */
      XString[][] strPairs4 =
         {
            { new XString(" *//*\n   ======================================================================================================================== */\n"), new XString("\n   *//*\n   ======================================================================================================================== */\n")  },
         };
      this.replace(strPairs4);
      XString[][] strPairs5 =
         {
            { new XString("\n\n   *//*\n   ======================================================================================================================== */\n"), new XString("\n   *//*\n   ======================================================================================================================== */\n")  },
         };
      this.replace(strPairs5);
      }




   public void replaceFileHeader() throws Exception
      {
      this.modify("replaceFileHeader");
      }


   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method replaces the file header comment block with an up-to-date one regardless of whether or
   not it already has an up-to-date file header comment block..

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#023">View source</A>

   @param
      pIter is an XStringsIterator for reading the input file
   @param
      pOutput is a TextWriter for writing the modified content of the input file to the output file.
   @param
      pArguments is a variable sized list of arguments. This method does not expect it to contain any
      values.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public void replaceFileHeader(XStringsIterator pIter, TextWriter pOutput, Object... pArguments) throws Exception
      {
      /*.
      ==========================================================================================
      ------------------------------------------------------------------------------------------ */
      XString  line           = null;
      XString  trimmedLine    = null;
      XString  theDateXString = null;
      XString  theYearXString = null;
      /*.
      ==========================================================================================
      skip empty lines until first actual line of file
      ------------------------------------------------------------------------------------------ */
      while (pIter.hasNext())
         {
         line = pIter.next();
         trimmedLine = line.trim();
         if (!trimmedLine.equals(""))
            {
            break;
            }
         }
      /*.
      ==========================================================================================
      if the file has no file header, insert one and quit.
      ------------------------------------------------------------------------------------------ */
      if (!trimmedLine.startsWith("/*"))
         {
         theDateXString = Util.timeStamp("yyyy.MM.dd HH:mm",new Date(this.created()));
         theYearXString = Util.timeStamp("yyyy",new Date(this.created()));
         pOutput.println("/*::.");
         pOutput.println("==================================================================================================================================");
         pOutput.println("=================================================¦ Copyright © " + theYearXString.toString() + " Allen Baker ¦=================================================");
         pOutput.println("                                                 +------------------------------+");
         pOutput.println("File:       " + this.getName());
         pOutput.println("Originator: Allen Baker (" + theDateXString.toString() + ")");
         pOutput.println("LayoutRev:  5");
         pOutput.println("================================================================================================================================== */");
         pOutput.println(line.toString());
         }
      else
         {
         /*.
         ==========================================================================================
         otherwise, the file has a file header, so read it all in to a string buffer
         ------------------------------------------------------------------------------------------ */
         StringBuffer  fileHeaderStringBuffer = new StringBuffer();
         while (pIter.hasNext())
            {
            line = pIter.next();
            trimmedLine = line.trim();
            fileHeaderStringBuffer.append(line);
            if (trimmedLine.endsWith("*/"))
               {
               break;
               }
            }
         /*.
         ==========================================================================================
         extract the date info from the old header
         ------------------------------------------------------------------------------------------ */
         XString                        fileHeaderXString = new XString(fileHeaderStringBuffer.toString());
         ListOfLists<XString>  wordsAndDelims    = fileHeaderXString.getWordsAndDelimiters("()");
         /*.
         ==========================================================================================
         if there is no date, use the file's create date
         ------------------------------------------------------------------------------------------ */
         if (wordsAndDelims.get(0).size() != 3)
            {
            theDateXString = Util.timeStamp("yyyy.MM.dd HH:mm",new Date(this.created()));
            theYearXString = Util.timeStamp("yyyy",new Date(this.created()));
            }
         else
            {
            theDateXString = wordsAndDelims.get(0).get(1);
            wordsAndDelims = theDateXString.getWordsAndDelimiters(".");
            theYearXString = wordsAndDelims.get(0).get(0);
            }
         /*.
         ==========================================================================================
         replace the header with a new header
         ------------------------------------------------------------------------------------------ */
         fileHeaderStringBuffer = new StringBuffer();
         fileHeaderStringBuffer.append("/*::.\n");
         fileHeaderStringBuffer.append("==================================================================================================================================\n");
         fileHeaderStringBuffer.append("=================================================¦ Copyright © " + theYearXString.toString() + " Allen Baker ¦=================================================\n");
         fileHeaderStringBuffer.append("                                                 +------------------------------+\n");
         fileHeaderStringBuffer.append("File:       " + this.getName() + "\n");
         fileHeaderStringBuffer.append("Originator: Allen Baker (" + theDateXString.toString() + ")\n");
         fileHeaderStringBuffer.append("LayoutRev:  5\n");
         fileHeaderStringBuffer.append("================================================================================================================================== */");
         pOutput.println(fileHeaderStringBuffer.toString());
         }
      /*.
      ==========================================================================================
      write out the rest of the file.
      ------------------------------------------------------------------------------------------ */
      while (pIter.hasNext())
         {
         pOutput.println(pIter.next());
         }
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method wraps the textual content of all of a source code file's (pFileName) multi-line comments
   that are delimited by specified start comment (pStartDelimiter) and end comment delimiters
   (pEndDelimiter) so that they fit within a specified width (pFieldWidth).<P>

   This method is how to use a class method to use the modifyInPlace pattern to wrapCommentText.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#024">View source</A>

   @param
      pInPathname is the name of the file that will be copied to the output file with the modifications
      that this method performs. pOutPathname must not be the same as pInPathname. pOutPathname and
      pInPathname must not be null.
   @param
      pStartDelimiter is the string that demarcates the beginning of a multi-line comment that is to be
      wrapped.
   @param
      pEndDelimiter is the string that demarcates the ending of a multi-line comment that is to be
      wrapped.
   @param
      pFieldWidth is the width to which the comments are to be wrapped.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public <Type1, Type2> void wrapCommentText(Type1 pStartDelimiter, Type2 pEndDelimiter, int pFieldWidth) throws Exception
      {
      this.modify("wrapCommentText", UString.toString(pStartDelimiter), UString.toString(pEndDelimiter), pFieldWidth);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method wraps the textual content of all of a source code file's (pFileName) multi-line comments
   that are delimited by specified start comment (pStartDelimiter) and end comment delimiters
   (pEndDelimiter) so that they fit within a specified width (pFieldWidth).<P>

   This method is the algorithm method for the modifyInPlace pattern. This is the method where the real
   work gets done on the file. The individual lines of the file are modified in here.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#025">View source</A>

   @param
      pInPathname is the name of the file that will be copied to the output file with the modifications
      that this method performs. pOutPathname must not be the same as pInPathname. pOutPathname and
      pInPathname must not be null.
   @param
      pOutPathname is the name that will be given to the file that is produced. pOutPathname must not
      be the same as pInPathname. pOutPathname and pInPathname must not be null.
   @param
      pStartDelimiter is the string that demarcates the beginning of a multi-line comment that is to be
      wrapped.
   @param
      pEndDelimiter is the string that demarcates the ending of a multi-line comment that is to be
      wrapped.
   @param
      pFieldWidth is the width to which the comments are to be wrapped.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public void wrapCommentText(XStringsIterator pIter, TextWriter pOutput, Object... pArguments) throws Exception
      {
      /*.
      ==========================================================================================
      get the arguments
      ------------------------------------------------------------------------------------------ */
      String  startDelimiter = UString.toString(pArguments[0]);
      String  endDelimiter   = UString.toString(pArguments[1]);
      int     fieldWidth     = (int)pArguments[2];
      /*.
      ==========================================================================================
      Put the entire content of the input file into a StringBuffer
      ------------------------------------------------------------------------------------------ */
      StringBuffer  theWholeFile = new StringBuffer(2 * UMath.ONE_MEG);
      while (pIter.hasNext())
         {
         XString  s = pIter.next();
         s = s.trimRight();
         s = s.concat("\n");
         theWholeFile.append(s.toString());
         }
      /*.
      ==========================================================================================
      For each pStartDelimiter in the file...
      ------------------------------------------------------------------------------------------ */
      int      startDelimiterLength = startDelimiter.length();
      int      endDelimiterLength   = endDelimiter.length();
      int      startSearchFromIdx   = 0;
      int      startDelimiterIdx    = 0;
      XString  commentText          = null;
      while ((startDelimiterIdx = theWholeFile.indexOf(startDelimiter, startSearchFromIdx)) != (-1))
         {
         /*.
         ==========================================================================================
         ignore sections of code that are commented out with single-line comments.
         ------------------------------------------------------------------------------------------ */
         if (SourceCodeFileCFamily.lineIsCommentedOut(theWholeFile, startDelimiterIdx))
            {
            startSearchFromIdx = startDelimiterIdx + startDelimiterLength;
            }
         else
            {
            /*.
            ==========================================================================================
            StartCommentTextIdx is the index of the first char in the comment's text.
            EndCommentTextIdx is the index of the last char in the comment's text *plus 1*.
            ------------------------------------------------------------------------------------------ */
            int  startCommentTextIdx = startDelimiterIdx + startDelimiterLength;
            int  endCommentTextIdx   = 0;
            /*.
            ==========================================================================================
            Find the indent whitespace for this comment.
            ------------------------------------------------------------------------------------------ */
            XString  indent       = new XString("");
            int      indentLength = 0;
            String   thisLine     = UString.lineContainingIndex(theWholeFile, startDelimiterIdx);
            int      indentIdx    = 0;
            if ((thisLine.equals("")) || (thisLine.charAt(0) != ' '))   // in case there is no indent
               {
               indent       = new XString("");
               indentLength = 0;
               }
            else
               {
               while (thisLine.charAt(indentIdx) == ' ')
                  {
                  indentIdx++;
                  }
               indent       = new XString(thisLine.substring(0, indentIdx));
               indentLength = indent.length();
               }
            /*.
            ==========================================================================================
            Find the end index of the startDelimiter's matching endDelimiter - it's the first
            uncommented out end delimiter found
            ------------------------------------------------------------------------------------------ */
            int  idxAfterEndDelimiter = startCommentTextIdx;
            while (true)
               {
               idxAfterEndDelimiter = UString.indexAfterDelimitedSpan(theWholeFile, startDelimiter, endDelimiter, idxAfterEndDelimiter, true);
               if (idxAfterEndDelimiter == (-1)) break;
               if (! SourceCodeFileCFamily.lineIsCommentedOut(theWholeFile, idxAfterEndDelimiter - endDelimiterLength)) break;
               }
            /*.
            ==========================================================================================
            It should never happen in a properly formed file, but if no matching end delimiter was
            located, don't do anything else.
            ------------------------------------------------------------------------------------------ */
            if (idxAfterEndDelimiter == (-1))
               {
               System.out.println(theWholeFile.substring( UMath.max(0,startDelimiterIdx-500), UMath.min(theWholeFile.length(),startDelimiterIdx+500) ));
               throw new Exception
                  (
                  "CommentFixer.wrapCommentText(): Malformed comments in file:\n"                                   +
                  "   idxAfterEndDelimiter is: -1\n"                                                                +
                  "   startDelimiterIdx is:    "    + startDelimiterIdx                                     +  "\n" +
                  "   line number is:          "    + UString.lineCount(theWholeFile, 0, startDelimiterIdx) +  "\n" +
                  "   startDelimiterLength is: "    + startDelimiterLength                                  +  "\n" +
                  "   indent is:               <"   + indent                                                + ">\n" +
                  "   endDelimiterLength is:   "    + endDelimiterLength                                    +  "\n"
                  );
               }
            else
               {
               /*.
               ==========================================================================================
               Big Assumption: The actual comment text ends on the line before the line containing the
                               end delimiter.

               Doing this backup thing here for the end idx eliminates the problem of when a comment is
               itself commented out with a double slash. Without backing up to the newline preceeding the
               '//', the '//' would be considered part of the comment text.
               ------------------------------------------------------------------------------------------ */
               endCommentTextIdx = idxAfterEndDelimiter - endDelimiterLength - 1;
               while (theWholeFile.charAt(endCommentTextIdx) != '\n')
                  {
                  endCommentTextIdx--;
                  }
               endCommentTextIdx++;
               /*.
               ==========================================================================================
               Grab all the content between the start and end delimiters into a single XString for
               wrapping
               ------------------------------------------------------------------------------------------ */
               commentText = new XString(theWholeFile.substring(startCommentTextIdx, endCommentTextIdx));
               /*.
               ==========================================================================================
               Wrap it and put the entire wrapped content into a single XString
               ------------------------------------------------------------------------------------------ */
               XString  wrappedComment = new XString("");
               if (!commentText.isEmpty())
                  {
                  ArrayList<XString>  wrappedLines = commentText.wordWrap(fieldWidth + indentLength, new UString.BasicEnglishCapitalizer());
                  commentText = new XString("");
                  for (XString wrappedLine : wrappedLines)
                     {
                     commentText = commentText.concat(wrappedLine + "\n");
                     }
                  }
               /*.
               ==========================================================================================
               Replace the original comment content with the wrapped content
               ------------------------------------------------------------------------------------------ */
               theWholeFile = theWholeFile.replace(startCommentTextIdx, endCommentTextIdx, commentText.toString());
               }
            /*.
            ==========================================================================================
            To continue searching for comments, increment the place in theWholeFile from which to
            start looking so it is past the comment we just processed
            ------------------------------------------------------------------------------------------ */
            startSearchFromIdx = startDelimiterIdx + startDelimiterLength + commentText.length() + indent.length() + endDelimiterLength;
            }
         }
      /*.
      ==========================================================================================
      Write the pOutput file
      ------------------------------------------------------------------------------------------ */
      pOutput.println(theWholeFile.toString());
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method recognizes a large number of section banners in obsolete formats and replaces each of
   them that is found in this file with an up-to-date alternative banner.<P>

   The source code for this method is notably ugly because of all the hard coded banner strings.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#026">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public void fixAllObsoleteBanners() throws Exception
      {
      XString o00 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\\               Public                /%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n"     +
         "   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%/  Classes, Constants, and Variables  \\%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n00 = SourceCodeFileCFamily.sectionBanner("Public Classes, Constants, and Variables", 0);

      XString o01 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   //////////////////////////////////////////////////     Public      \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  Inner Classes  //////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n01 = SourceCodeFileCFamily.sectionBanner("Public Inner Classes", 1);

      XString o02 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   /////////////////////////////////////////////////      Public       \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  Class Constants  /////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n02 = SourceCodeFileCFamily.sectionBanner("Public Class Constants", 1);

      XString o03 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   /////////////////////////////////////////////////      Public       \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  Class Variables  /////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n03 = SourceCodeFileCFamily.sectionBanner("Public Class Variables", 1);

      XString o04 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   ///////////////////////////////////////////////        Public        \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  Instance Constants  ////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n04 = SourceCodeFileCFamily.sectionBanner("Public Instance Constants", 1);

      XString o05 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   ///////////////////////////////////////////////        Public        \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  Instance Variables  ////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n05 = SourceCodeFileCFamily.sectionBanner("Public Instance Variables", 1);

      XString o06 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\\              Protected              /%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n"     +
         "   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%/  Classes, Constants, and Variables  \\%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n06 = SourceCodeFileCFamily.sectionBanner("Protected Classes, Constants, and Variables", 0);

      XString o07 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   //////////////////////////////////////////////////    Protected    \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  Inner Classes  //////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n07 = SourceCodeFileCFamily.sectionBanner("Protected Inner Classes", 1);

      XString o08 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   /////////////////////////////////////////////////     Protected     \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  Class Constants  /////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n08 = SourceCodeFileCFamily.sectionBanner("Protected Class Constants", 1);

      XString o09 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   /////////////////////////////////////////////////     Protected     \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  Class Variables  /////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n09 = SourceCodeFileCFamily.sectionBanner("Protected Class Variables", 1);

      XString o10 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   ///////////////////////////////////////////////      Protected       \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  Instance Constants  ////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n10 = SourceCodeFileCFamily.sectionBanner("Protected Instance Constants", 1);

      XString o11 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   ///////////////////////////////////////////////      Protected       \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  Instance Variables  ////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n11 = SourceCodeFileCFamily.sectionBanner("Protected Instance Variables", 1);

      XString o12 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\\               Private               /%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n"     +
         "   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%/  Classes, Constants, and Variables  \\%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n12 = SourceCodeFileCFamily.sectionBanner("Private Classes, Constants, and Variables", 0);

      XString o13 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   //////////////////////////////////////////////////     Private     \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  Inner Classes  //////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n13 = SourceCodeFileCFamily.sectionBanner("Private Inner Classes", 1);

      XString o14 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   /////////////////////////////////////////////////      Private      \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  Class Constants  /////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n14 = SourceCodeFileCFamily.sectionBanner("Private Class Constants", 1);

      XString o15 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   /////////////////////////////////////////////////      Private      \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  Class Variables  /////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n15 = SourceCodeFileCFamily.sectionBanner("Private Class Variables", 1);

      XString o16 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   ///////////////////////////////////////////////       Private        \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  Instance Constants  ////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n16 = SourceCodeFileCFamily.sectionBanner("Private Instance Constants", 1);

      XString o17 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   ///////////////////////////////////////////////       Private        \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  Instance Variables  ////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n17 = SourceCodeFileCFamily.sectionBanner("Private Instance Variables", 1);

      XString o18 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\\        Private         /%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n"     +
         "   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%/  Class initialization  \\%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n18 = SourceCodeFileCFamily.sectionBanner("Private Class Initialization", 0);

      XString o19 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\\  Private  /%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n"     +
         "   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%/  Methods  \\%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n19 = SourceCodeFileCFamily.sectionBanner("Private Methods", 0);

      XString o20 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   //////////////////////////////////////////////////    Private     \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  Constructors  ///////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n20 = SourceCodeFileCFamily.sectionBanner("Private Constructors", 1);

      XString o21 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   ////////////////////////////////////////////////      Private       \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  Instance Methods  /////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n21 = SourceCodeFileCFamily.sectionBanner("Private Instance Methods", 1);

      XString o22 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   //////////////////////////////////////////////////     Private     \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  Class Methods  //////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n22 = SourceCodeFileCFamily.sectionBanner("Private Class Methods", 1);

      XString o23 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\\  Protected  /%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n"     +
         "   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%/   Methods   \\%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n23 = SourceCodeFileCFamily.sectionBanner("Protected Methods", 0);

      XString o24 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   //////////////////////////////////////////////////   Protected    \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  Constructors  ///////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n24 = SourceCodeFileCFamily.sectionBanner("Protected Constructors", 1);

      XString o25 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   ////////////////////////////////////////////////     Protected      \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  Instance Methods  /////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n25 = SourceCodeFileCFamily.sectionBanner("Protected Instance Methods", 1);

      XString o26 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   //////////////////////////////////////////////////    Protected    \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  Class Methods  //////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n26 = SourceCodeFileCFamily.sectionBanner("Protected Class Methods", 1);

      XString o27 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\\  Public   /%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n"     +
         "   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%/  Methods  \\%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n27 = SourceCodeFileCFamily.sectionBanner("Public Methods", 0);

      XString o28 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   //////////////////////////////////////////////////     Public     \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  Constructors  ///////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n28 = SourceCodeFileCFamily.sectionBanner("Public Constructors", 1);

      XString o29 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   ////////////////////////////////////////////////       Public       \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  Instance Methods  /////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n29 = SourceCodeFileCFamily.sectionBanner("Public Instance Methods", 1);

      XString o30 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   //////////////////////////////////////////////////     Public      \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  Class Methods  //////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n30 = SourceCodeFileCFamily.sectionBanner("Public Class Methods", 1);

      XString o31 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   //////////////////////////////////////////////////////  Main  \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\n"     +
         "   \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\        ///////////////////////////////////////////////////////\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n31 = SourceCodeFileCFamily.sectionBanner("Main", 1);

      XString o32 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   =====================================================================================================================\n"     +
         "   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\\  Notes  /%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n"     +
         "   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%/         \\%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n"     +
         "   ===================================================================================================================== */\n"
         );
      XString n32 = SourceCodeFileCFamily.sectionBanner("Notes", 0);

      XString o33 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   ===================================================================\n"                                                       +
         "   ===================================================================\n"                                                       +
         "                --------------- Protected ---------------\n"                                                                    +
         "   =================================================================== */\n"
         );
      XString n33 = SourceCodeFileCFamily.sectionBanner("Protected", 0);

      XString o34 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   ===================================================================\n"                                                       +
         "   ===================================================================\n"                                                       +
         "                 --------------- Private ---------------\n"                                                                     +
         "   =================================================================== */\n"
         );
      XString n34 = SourceCodeFileCFamily.sectionBanner("Private", 0);

      XString o35 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   ===================================================================\n"                                                       +
         "   ===================================================================\n"                                                       +
         "              --------------- Inner Classes ---------------\n"                                                                  +
         "   =================================================================== */\n"
         );
      XString n35 = SourceCodeFileCFamily.sectionBanner("Inner Classes", 0);

      XString o36 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   ===================================================================\n"                                                       +
         "   ===================================================================\n"                                                       +
         "          --------------- Public Static Methods ---------------\n"                                                              +
         "   =================================================================== */\n"
         );
      XString n36 = SourceCodeFileCFamily.sectionBanner("Public Static Methods", 0);

      XString o37 = new XString
         (
         "   /*\n"                                                                                                                        +
         "   ===================================================================\n"                                                       +
         "   ===================================================================\n"                                                       +
         "              ------------------- Notes -------------------\n"                                                                  +
         "   =================================================================== */\n"
         );
      XString n37 = SourceCodeFileCFamily.sectionBanner("Notes", 0);

      XString o38 = new XString
         (
         "   /*\n"                                                                           +
         "   ===================================================================\n"          +
         "   ===================================================================\n"          +
         "                 --------------- Constants ---------------\n"                      +
         "   =================================================================== */\n"
         );
      XString n38 = SourceCodeFileCFamily.sectionBanner("Constants", 0);

      XString o39 = new XString
         (
         "   /*\n"                                                                           +
         "   ===================================================================\n"          +
         "   ===================================================================\n"          +
         "                 --------------- Public ---------------\n"                         +
         "   =================================================================== */\n"
         );
      XString n39 = SourceCodeFileCFamily.sectionBanner("Public", 0);

      XString o40 = new XString
         (
         "   /*\n"                                                                               +
         "   =============================================================================\n"    +
         "   --------------------------< Private Class Methods >--------------------------\n"    +
         "   ============================================================================= */\n"
         );
      XString n40 = SourceCodeFileCFamily.sectionBanner("Private Class Methods", 1);

      XString o41 = new XString
         (
         "   /*\n"                                                                               +
         "   =============================================================================\n"    +
         "   --------------------------< Private Class Methods >--------------------------\n"    +
         "   ============================================================================= */\n"
         );
      XString n41 = SourceCodeFileCFamily.sectionBanner("Private Class Methods", 1);

      XString o42 = new XString
         (
         "   /*\n"                                                                              +
         "   ========================================================================\n"        +
         "   ===================| Public Constants And Variables |===================\n"        +
         "   ======================================================================== */\n"
         );
      XString n42 = SourceCodeFileCFamily.sectionBanner("Public Constants And Variables", 0);

      XString o43 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "   --------------------< Public Class Constants >---------------------\n"             +
         "   ------------------------------------------------------------------- */\n"
         );
      XString n43 = SourceCodeFileCFamily.sectionBanner("Public Class Constants", 1);

      XString o44 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "   --------------------< Public Class Variables >---------------------\n"             +
         "   ------------------------------------------------------------------- */\n"
         );
      XString n44 = SourceCodeFileCFamily.sectionBanner("Public Class Variables", 1);

      XString o45 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "   -------------------< Public Instance Constants >-------------------\n"             +
         "   ------------------------------------------------------------------- */\n"
         );
      XString n45 = SourceCodeFileCFamily.sectionBanner("Public Instance Constants", 1);

      XString o46 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "   -------------------< Public Instance Variables >-------------------\n"             +
         "   ------------------------------------------------------------------- */\n"
         );
      XString n46 = SourceCodeFileCFamily.sectionBanner("Public Instance Variables", 1);

      XString o47 = new XString
         (
         "   /*\n"                                                                              +
         "   ========================================================================\n"        +
         "   =================| Protected Constants And Variables |==================\n"        +
         "   ======================================================================== */\n"
         );
      XString n47 = SourceCodeFileCFamily.sectionBanner("Protected Constants And Variables", 0);

      XString o48 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "   -------------------< Protected Class Constants >-------------------\n"             +
         "   ------------------------------------------------------------------- */\n"
         );
      XString n48 = SourceCodeFileCFamily.sectionBanner("Protected Class Constants", 1);

      XString o49 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "   -------------------< Protected Class Variables >-------------------\n"             +
         "   ------------------------------------------------------------------- */\n"
         );
      XString n49 = SourceCodeFileCFamily.sectionBanner("Protected Class Variables", 1);

      XString o50 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "   -----------------< Protected Instance Constants >------------------\n"             +
         "   ------------------------------------------------------------------- */\n"
         );
      XString n50 = SourceCodeFileCFamily.sectionBanner("Protected Instance Constants", 1);

      XString o51 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "   -----------------< Protected Instance Variables >------------------\n"             +
         "   ------------------------------------------------------------------- */\n"
         );
      XString n51 = SourceCodeFileCFamily.sectionBanner("Protected Instance Variables", 1);

      XString o52 = new XString
         (
         "   /*\n"                                                                              +
         "   ========================================================================\n"        +
         "   ==================| Private Constants And Variables |===================\n"        +
         "   ======================================================================== */\n"
         );
      XString n52 = SourceCodeFileCFamily.sectionBanner("Private Constants And Variables", 0);

      XString o53 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "   --------------------< Private Class Constants >--------------------\n"             +
         "   ------------------------------------------------------------------- */\n"
         );
      XString n53 = SourceCodeFileCFamily.sectionBanner("Private Class Constants", 1);

      XString o54 = new XString
         (
         "/*\n"                                                                                 +
         "===================================================================\n"                +
         "----------------------------< Package >----------------------------\n"                +
         "------------------------------------------------------------------- */\n"
         );
      XString n54 = SourceCodeFileCFamily.sectionBanner("Package", 1);

      XString o55 = new XString
         (
         "/*\n"                                                                                 +
         "===================================================================\n"                +
         "----------------------------< Imports >----------------------------\n"                +
         "------------------------------------------------------------------- */\n"
         );
      XString n55 = SourceCodeFileCFamily.sectionBanner("Imports", 1);

      XString o56 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "   --------------------< Private Class Variables >--------------------\n"             +
         "   ------------------------------------------------------------------- */\n"
         );
      XString n56 = SourceCodeFileCFamily.sectionBanner("Private Class Variables", 1);

      XString o57 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "   ------------------< Private Instance Constants >-------------------\n"             +
         "   ------------------------------------------------------------------- */\n"
         );
      XString n57 = SourceCodeFileCFamily.sectionBanner("Private Instance Constants", 1);

      XString o58 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "   ------------------< Private Instance Variables >-------------------\n"             +
         "   ------------------------------------------------------------------- */\n"
         );
      XString n58 = SourceCodeFileCFamily.sectionBanner("Private Instance Variables", 1);

      XString o59 = new XString
         (
         "   /*\n"                                                                              +
         "   ========================================================================\n"        +
         "   ===========================| Inner Classes |============================\n"        +
         "   ======================================================================== */\n"
         );
      XString n59 = SourceCodeFileCFamily.sectionBanner("Inner Classes", 0);

      XString o60 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "   ---------------------< Public Inner Classes >----------------------\n"             +
         "   ------------------------------------------------------------------- */\n"
         );
      XString n60 = SourceCodeFileCFamily.sectionBanner("Public Inner Classes", 1);

      XString o61 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "   --------------------< Protected Inner Classes >--------------------\n"             +
         "   ------------------------------------------------------------------- */\n"
         );
      XString n61 = SourceCodeFileCFamily.sectionBanner("Protected Inner Classes", 1);

      XString o62 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "   ---------------------< Private Inner Classes >---------------------\n"             +
         "   ------------------------------------------------------------------- */\n"
         );
      XString n62 = SourceCodeFileCFamily.sectionBanner("Private Inner Classes", 1);

      XString o63 = new XString
         (
         "   /*\n"                                                                              +
         "   ========================================================================\n"        +
         "   ====================| Private Class Initialization |====================\n"        +
         "   ======================================================================== */\n"
         );
      XString n63 = SourceCodeFileCFamily.sectionBanner("Private Class Initialization", 0);

      XString o64 = new XString
         (
         "   /*\n"                                                                              +
         "   ========================================================================\n"        +
         "   ==========================| Private Methods |===========================\n"        +
         "   ======================================================================== */\n"
         );
      XString n64 = SourceCodeFileCFamily.sectionBanner("Private Methods", 0);

      XString o65 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "   ---------------------< Private Constructors >----------------------\n"             +
         "   ------------------------------------------------------------------- */\n"
         );
      XString n65 = SourceCodeFileCFamily.sectionBanner("Private Constructors", 1);

      XString o66 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "   -------------------< Private Instance Methods >--------------------\n"             +
         "   ------------------------------------------------------------------- */\n"
         );
      XString n66 = SourceCodeFileCFamily.sectionBanner("Private Instance Methods", 1);

      XString o67 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "   ---------------------< Private Class Methods >---------------------\n"             +
         "   ------------------------------------------------------------------- */\n"
         );
      XString n67 = SourceCodeFileCFamily.sectionBanner("Private Class Methods", 1);

      XString o68 = new XString
         (
         "   /*\n"                                                                              +
         "   ========================================================================\n"        +
         "   =========================| Protected Methods |==========================\n"        +
         "   ======================================================================== */\n"
         );
      XString n68 = SourceCodeFileCFamily.sectionBanner("Protected Methods", 0);

      XString o69 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "   --------------------< Protected Constructors >---------------------\n"             +
         "   ------------------------------------------------------------------- */\n"
         );
      XString n69 = SourceCodeFileCFamily.sectionBanner("Protected Constructors", 1);

      XString o70 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "   ------------------< Protected Instance Methods >-------------------\n"             +
         "   ------------------------------------------------------------------- */\n"
         );
      XString n70 = SourceCodeFileCFamily.sectionBanner("Protected Instance Methods", 1);

      XString o71 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "   --------------------< Protected Class Methods >--------------------\n"             +
         "   ------------------------------------------------------------------- */\n"
         );
      XString n71 = SourceCodeFileCFamily.sectionBanner("Protected Class Methods", 1);

      XString o72 = new XString
         (
         "   /*\n"                                                                              +
         "   ========================================================================\n"        +
         "   ===========================| Public Methods |===========================\n"        +
         "   ======================================================================== */\n"
         );
      XString n72 = SourceCodeFileCFamily.sectionBanner("Public Methods", 0);

      XString o73 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "   ----------------------< Public Constructors >----------------------\n"             +
         "   ------------------------------------------------------------------- */\n"
         );
      XString n73 = SourceCodeFileCFamily.sectionBanner("Public Constructors", 1);

      XString o74 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "   --------------------< Public Instance Methods >--------------------\n"             +
         "   ------------------------------------------------------------------- */\n"
         );
      XString n74 = SourceCodeFileCFamily.sectionBanner("Public Instance Methods", 1);

      XString o75 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "   ---------------------< Public Class Methods >----------------------\n"             +
         "   ------------------------------------------------------------------- */\n"
         );
      XString n75 = SourceCodeFileCFamily.sectionBanner("Public Class Methods", 1);

      XString o76 = new XString
         (
         "   /*\n"                                                                              +
         "   ========================================================================\n"        +
         "   ================================| Main |================================\n"        +
         "   ======================================================================== */\n"
         );
      XString n76 = SourceCodeFileCFamily.sectionBanner("Main", 0);

      XString o77 = new XString
         (
         "   /*\n"                                                                              +
         "   ========================================================================\n"        +
         "   ===============================| Notes |================================\n"        +
         "   ======================================================================== */\n"
         );
      XString n77 = SourceCodeFileCFamily.sectionBanner("Notes", 0);



      XString o78 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "                ------------ The Math API -------------\n"                            +
         "   =================================================================== */\n"
         );
      XString n78 = SourceCodeFileCFamily.sectionBanner("The Math API", 1);


      XString o79 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "                ------------ The Extensions -------------\n"                          +
         "   =================================================================== */\n"
         );
      XString n79 = SourceCodeFileCFamily.sectionBanner("The Extensions", 1);

      XString o80 = new XString
         (
         "   /*\n"                                                                              +
         "   ===================================================================\n"             +
         "                ------------ The String API -------------\n"                          +
         "   =================================================================== */\n"
         );
      XString n80 = SourceCodeFileCFamily.sectionBanner("The String API", 1);

      XString[][] strPairs =
         {
            { o00, n00 },
            { o01, n01 },
            { o02, n02 },
            { o03, n03 },
            { o04, n04 },
            { o05, n05 },
            { o06, n06 },
            { o07, n07 },
            { o08, n08 },
            { o09, n09 },
            { o10, n10 },
            { o11, n11 },
            { o12, n12 },
            { o13, n13 },
            { o14, n14 },
            { o15, n15 },
            { o16, n16 },
            { o17, n17 },
            { o18, n18 },
            { o19, n19 },
            { o20, n20 },
            { o21, n21 },
            { o22, n22 },
            { o23, n23 },
            { o24, n24 },
            { o25, n25 },
            { o26, n26 },
            { o27, n27 },
            { o28, n28 },
            { o29, n29 },
            { o30, n30 },
            { o31, n31 },
            { o32, n32 },
            { o33, n33 },
            { o34, n34 },
            { o35, n35 },
            { o36, n36 },
            { o37, n37 },
            { o38, n38 },
            { o39, n39 },
            { o40, n40 },
            { o41, n41 },
            { o42, n42 },
            { o43, n43 },
            { o44, n44 },
            { o45, n45 },
            { o46, n46 },
            { o47, n47 },
            { o48, n48 },
            { o49, n49 },
            { o50, n50 },
            { o51, n51 },
            { o52, n52 },
            { o53, n53 },
            { o54, n54 },
            { o55, n55 },
            { o56, n56 },
            { o57, n57 },
            { o58, n58 },
            { o59, n59 },
            { o60, n60 },
            { o61, n61 },
            { o62, n62 },
            { o63, n63 },
            { o64, n64 },
            { o65, n65 },
            { o66, n66 },
            { o67, n67 },
            { o68, n68 },
            { o69, n69 },
            { o70, n70 },
            { o71, n71 },
            { o72, n72 },
            { o73, n73 },
            { o74, n74 },
            { o75, n75 },
            { o76, n76 },
            { o77, n77 },
            { o78, n78 },
            { o79, n79 },
            { o80, n80 },
         };
      this.replace(strPairs);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates an XString containing a C family source code file section banner with a
   specified title (pStr) and  with the banner design appropriate for a specified level (pLevel) within
   a hierarchy of source code file sections.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#027">View source</A>

   @return
      This method returns an XString containing a C family source code file section banner with a
      specified title (pStr) and  with the banner design appropriate for a specified level (pLevel)
      within a hierarchy of source code file sections.

   @param
      pStr is an Object whose XString representation is used as the title in the banner.
   @param
      pLevel indicates the level in a hierarchy of source code file sections for which the banner is
      tailored. Level 0 is the highest level, followed by level 1, and so on.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   private static XString sectionBanner(String pStr, int pLevel)
      {
      /*
      ==========================================================================================
      banner bars
      ------------------------------------------------------------------------------------------ */
      XString  iSectionPrefix     = new XString(":.");
      XString  iSectionHeavyBar   = new XString("==============================================================================================================");
      XString  iSectionLightBar   = new XString("--------------------------------------------------------------------------------------------------------------");
      int      iSectionWidth      = iSectionHeavyBar.length();
      /*
      ==========================================================================================
      tokens for framing banner comments
      ------------------------------------------------------------------------------------------ */
      XString[]  iLBracket =
         {
         new XString("["), new XString("["), new XString("["), new XString("["), new XString("[")
         };
      XString[]  iRBracket =
         {
         new XString("]"), new XString("]"), new XString("]"), new XString("]"), new XString("]")
         };
      XString[]  iLFill =
         {
         new XString("@"), new XString("<"), new XString(":"), new XString("-"), new XString(" ")
         };
      XString[]  iRFill =
         {
         new XString("@"), new XString(">"), new XString(":"), new XString("-"), new XString(" ")
         };
      /*
      ==========================================================================================
      build the comment
      ------------------------------------------------------------------------------------------ */
      int  mFieldWidth = iSectionHeavyBar.length();
      XString  cmmt = new XString(pStr);
      cmmt = new XString(iLBracket[pLevel] + "  " + cmmt.toString() + "  " + iRBracket[pLevel]);
      cmmt = cmmt.alignRight(((mFieldWidth-cmmt.length())/2) + cmmt.length(),iLFill[pLevel].charAt(0));
      cmmt = cmmt.alignLeft (mFieldWidth, iRFill[pLevel].charAt(0));
      /*
      ==========================================================================================
      put it into the banner and return it
      ------------------------------------------------------------------------------------------ */
      return new XString
         (
         "   " + "/*" + iSectionPrefix.toString() + "\n"  +
         "   " + iSectionHeavyBar.toString()      + "\n"  +
         "   " + cmmt.toString()                  + "\n"  +
         "   " + iSectionHeavyBar.toString()      + " */" + "\n"
         );
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method determines whether or not the line of text in a String (or any Object convertable to a
   String) containing the indexed character is commented out.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#028">View source</A>

   @return
      This method returns true if the line of text in a String (or any Object convertable to a String)
      (pStr) containing the indexed (pIdx) character is commented out. Otherwise, it returns false.

   @param
      pSringBuffer contains the line of text
   @param
      pIdx is the index that determines the line of text in pStr to check to see if it is commented
      out.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   private static <Type1> boolean lineIsCommentedOut(Type1 pStr, int pIdx)
      {
      /*.
      ==========================================================================================
      if pIdx is < 1, it is either an invalid negative number or there is no room for a start
      comment delimiter.
      ------------------------------------------------------------------------------------------ */
      if (pIdx < 1) return false;
      /*.
      ==========================================================================================
      get the line containing pStr.charAt(pIdx)
      ------------------------------------------------------------------------------------------ */
      String  thisLine = UString.lineContainingIndex(pStr, pIdx);
      /*.
      ==========================================================================================
      if there's no double slash on the line then it's not commented out
      ------------------------------------------------------------------------------------------ */
      if (! thisLine.contains("//")) return false;
      /*.
      ==========================================================================================
      if there is a double slash on the line then we have to make sure it isn't part of a end of
      comment - start of comment sequence as is found at the end of function header comment
      blocks.
      ------------------------------------------------------------------------------------------ */
      thisLine = "\n\n" + thisLine + "\n\n";
      int idx;
      int startIdx = 2;
      while ((idx = thisLine.indexOf("//", startIdx)) != (-1))
         {
         if (!thisLine.substring(idx-1, idx+3).contains("*//*")) return true;
         startIdx = idx + 2;
         }
      return false;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method sets the ConsoleStream for this Object.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#029">View source</A>

   @return
      a reference to this Object

   @param
      pConsole is a ConsoleStream through which this Objects sends its output.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public SourceCodeFileCFamily setOut(ConsoleStream pConsole)
      {
      cOut = pConsole;
      return this;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This boilerplate method is used for testing an instantiated Object of this class and may include any
   code the developer chooses.

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#030">View source</A>

   @return
      a reference to this Object
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public SourceCodeFileCFamily test() throws Exception
      {
      cOut.titledPrintf
         (
         "\"HELLO WORLD!\"",
         "%s  %s  %s",
         "I'm an Object of the", CLASS_NAME, "class, and I approved this message."
         );

      this.fixComments();

      return this;
      }



   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Main  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method allows this class file to be unit tested as a standalone application.  It's the method
   that's called when the class is invoked from the command line by using the java application launcher
   - "java". main() is not a required method, but the practice of putting one in each class and
   wrapping class test code within it allows easy unit testing of the class; and main does not need to
   be removed when testing is complete.

   <P>
   <DL>
      <DT>
         <B>Command line usage:</B>
         <DD>
            java cosmicabyss.com.lib.SourceCodeFileCFamily
         </DD>
      </DT>
   </DL>

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#031">View source</A>

   @param
      pArgs contains the command line arguments with which this class was invoked as an application.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static void main(String[] pArgs) throws Exception
      {
      /*.
      ==========================================================================================
      Greetings !
      ------------------------------------------------------------------------------------------ */
      cOut.banner(CLASS_NAME);
      /*.
      ==========================================================================================
      create an Object and send its output to the ConsoleStream
      ------------------------------------------------------------------------------------------ */
      SourceCodeFileCFamily  obj = new SourceCodeFileCFamily(pArgs[0]);
      /*.
      ==========================================================================================
      test code
      ------------------------------------------------------------------------------------------ */
      obj.test();
      }



   }  // End of Class SourceCodeFileCFamily



   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Notes  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
   ============================================================================================================== */
   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method<P>
   => -> --
   c  c  c  c  c  c  c

   <P><B>Implementation: </B><A HREF="SourceCodeFileCFamily.java.html#032">View source</A>

   @return
      This method returns

   @exception
      xx is thrown when
   @exception
      yy is thrown when

   @param
      pX (optional)(input/output)(output) is the
   @param
      pY (optional)(input/output)(output) is the
   *//*
   ---------------------------------------------------------------------------------------------------- */
      /*.
      ==========================================================================================
      ------------------------------------------------------------------------------------------ */
   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Section Level 0 Banner  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Section Level 1 Banner  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   :::::::::::::::::::::::::::::::::::::::::[  Section Level 2 Banner  ]:::::::::::::::::::::::::::::::::::::::::
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   -----------------------------------------[  Section Level 3 Banner  ]-----------------------------------------
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
                                            [  Section Level 4 Banner  ]
   ============================================================================================================== */