protex

CCSM Research Tools: Community Atmosphere Model (CAM)

#!/ford1/local/bin/perl
#BOP
#
# !ROUTINE: ProTeX v. 2.00 - Translates DAO Prologues to LaTeX
#
# !INTERFACE:
#         protex [-hbACFS] ] [+-nlsxf] [src_file(s)]
#
# !DESCRIPTION:
#         Perl filter to produce a \LaTeX compatible document 
#         from a DAO Fortran source code with standard Pro\TeX 
#         prologues. If source files are not specified it
#         reads from stdin; output is always to stdout.
# 
# \noindent        
# {\bf Command Line Switches:} \vspace{0.2cm}
#
# \begin{center}
# \begin{tabular}{|c|l|} \hline \hline
#   -h   & Help mode: list command line options   \\ \hline
#   -b   & Bare mode, meaning no preamble, etc.  \\ \hline
#   +/-n & New Page for each subsection (wastes paper) \\ \hline
#   +/-l & Listing mode, default is prologues only \\ \hline
#   +/-s & Shut-up mode, i.e., ignore any code from BOC to EOC \\ \hline
#   +/-x & No LaTeX mode, i.e., put !DESCRIPTION: in verbatim mode \\ \hline
#   +/-f & No source file info \\ \hline
#   -A   & Ada code \\ \hline
#   -C   & C++ code \\ \hline
#   -F   & F90 code (default) \\ \hline
#   -S   & Shell script \\ \hline \hline
# \end{tabular}
# \end{center}
#
# The options can appear in any order.  The options, -h and -b, affect
# the input from all files listed on command-line input.  Each of the
# remaining options effects only the input from the files listed after
# the option and prior to any overriding option.  The plus sign
# turns off the option.  For example, the command-line input,
# \bv
#      protex -bnS File1 -F File2.f +n File3.f
# \ev
# will cause the option, {\tt -n} to affect the input from the files,
# {\tt File} and {\tt File2.f}, but not from {\tt File3.f}.  The
# {\tt -S} option is implemented for {\tt File1} but is overridden by
# the {\tt -F} for files {\tt File2.f} and {\tt File3.f}.
#
#
# !SEE ALSO:
#         For a more detailed description of ProTeX functionality,
#         DAO Prologue and other conventions, consult:
#
#           Sawyer, W., and A. da Silva, 1997: ProTeX: A Sample 
#           Fortran 90 Source Code Documentation System.
#           DAO Office Note 97-11
#         
#
# !REVISION HISTORY:
#
#  20Dec1995  da Silva  First experimental version
#  10Nov1996  da Silva  First internal release (v1.01)
#  28Jun1997  da Silva  Modified so that !DESCRIPTION can appear after
#             !INTERFACE, and !INPUT PARAMETERS etc. changed to italics.
#  02Jul1997  Sawyer    Added shut-up mode
#  20Oct1997  Sawyer    Added support for shell scripts
#  11Mar1998  Sawyer    Added: file name, date in header, C, script support
#  05Aug1998  Sawyer    Fixed LPChang-bug-support-for-files-with-underscores
#  10Oct1998  da Silva  Introduced -f option for removing source file info
#                       from subsection, etc.  Added help (WS).
#  06Dec1999  C. Redder Added LaTeX command "\label{sec:prologues}" just 
#                       after the beginning of the proglogue section.
#  13Dec1999  C. Redder Increased flexbility in command-line
#                       interface.  The options can appear in any
#                       order which will allow the user to implement
#                       options for select files.
#  01Feb1999  C. Redder Added \usepackage commands to preamble of latex
#                       document to include the packages amsmath, epsfig
#                       and hangcaption.
#  10May2000  C. Redder Revised LaTeX command "\label{sec:prologues}"
#                       to "\label{app:ProLogues}"
#
#EOP
#----------------------------------------------------------------------------

# Keep this if you don't know what it does...
# -------------------------------------------
  $[ = 1;                 # set array base to 1
  $, = ' ';               # set output field separator
  $\ = "\n";              # set output record separator

# Set valid options lists
# -----------------------
  $GlobOptions = 'hb';    # Global options (i.e for all files)
  $LangOptions = 'ACFS';  # Options for setting programming languages
  $SwOptions   = 'flnsx'; # Options that can change for each input 
                          #   file
  $RegOptions  = "$GlobOptions$LangOptions";
                          # Scan for global options until first first
                          #   file is processed.

# Scan for global options
# -----------------------
  $NFiles = 0;
Arg:
  foreach $arg (@ARGV) {
     $option = &CheckOpts ( $arg, $RegOptions, $SwOptions ) + 1;
     if ( $option ) {
        $rc = &GetOpts    ( $arg, $GlobOptions );
         next Arg; }

     else { $NFiles++;
}#   end if
}# end foreach

# If all inut arguments are options, then assume the
# filename, "-", for the standard input
# --------------------------------------------------
  if ( $NFiles == 0 ) { push (@ARGV, "-"); } 

# Implement help option
# ---------------------
  if ( $opt_h ) {
     &print_help();
      exit();
}#end if

# Optional Prologue Keywords
# --------------------------
  @keys = ( "!INTERFACE:",
            "!USES:",
            "!PUBLIC TYPES:",
            "!PUBLIC MEMBER FUNCTIONS:",
            "!PUBLIC DATA MEMBERS:",
            "!PARAMETERS:",
            "!DEFINED PARAMETERS:",
            "!INPUT PARAMETERS:",
            "!INPUT/OUTPUT PARAMETERS:",
            "!OUTPUT PARAMETERS:",
            "!RETURN VALUE:",
            "!REVISION HISTORY:",
            "!BUGS:",
            "!SEE ALSO:",
            "!SYSTEM ROUTINES:",
            "!FILES USED:",
            "!REMARKS:",
            "!TO DO:",
            "!CALLING SEQUENCE:",
            "!AUTHOR:",
            "!CALLED FROM:",
            "!LOCAL VARIABLES:" );

# Initialize these for clarity
# ----------------------------
  $intro = 0;             # doing introduction?
  $prologue = 0;          # doing prologue?
  $first = 1;             # first prologue?
  $source = 0;            # source code mode?
  $verb = 0;              # verbatim mode?
  $tpage = 0;             # title page?
  $begdoc = 0;            # has \begin{document} been written?

# Initial LaTeX stuff
# -------------------
  &print_notice();
  &print_preamble();      # \documentclass, text dimensions, etc.
  &print_macros();        # short-hand LaTeX macros

# Main loop -- for each command-line argument
# -------------------------------------------
ARG:
  foreach $arg (@ARGV) {

#    Scan for non-global command-line options
#    ----------------------------------------
     $option = &CheckOpts ( $arg, $RegOptions, $SwOptions, "quiet" ) + 1;
     if ( $option ) {
        &GetOpts  ( $arg, $SwOptions   );
        &SetOpt   ( $arg, $LangOptions );
        next ARG;

}#   end if

#    Determine the type of code, set corresponding search strings
#    ------------------------------------------------------------
#    if ( $opt_F ) {            # FORTRAN
        $comment_string = '!';  # -------
        $boi_string = '!BOI';
        $eoi_string = '!EOI';
        $bop_string = '!BOP';
        $eop_string = '!EOP';
        $boc_string = '!BOC';
        $eoc_string = '!EOC';
#}#   end if

     if ( $opt_A ) {            # ADA
        $comment_string = '--'; # ---
        $boi_string = '--BOI';
        $eoi_string = '--EOI';
        $bop_string = '--BOP';
        $eop_string = '--EOP';
        $boc_string = '--BOC';
        $eoc_string = '--EOC';
}#   end if

     if ( $opt_C ) {
        $comment_string = '//'; # C 
        $boi_string = '//BOI';  # -
        $eoi_string = '//EOI';
        $bop_string = '//BOP';
        $eop_string = '//EOP';
        $boc_string = '//BOC';
        $eoc_string = '//EOC';
}#   end if

     if ( $opt_S ) {            # Script
        $comment_string = '#';  # ------
        $boi_string = '#BOI';
        $eoi_string = '#EOI';
        $bop_string = '#BOP';
        $eop_string = '#EOP';
        $boc_string = '#BOC';
        $eoc_string = '#EOC';
}#   end if

#    Set file name parameters
#    ------------------------
     $InputFile           = $arg;
     @all_path_components = split( /\//, $InputFile     );
     $FileBaseName        = pop  ( @all_path_components );
     $FileBaseName        =~ s/_/\\_/g;
     if ( $InputFile eq "-" ) {$FileBaseName = "Standard Input";}

#    Set date
#    --------
     $Date                = `date`;

#    Open current file
#    -----------------
     open ( InputFile, "$InputFile" )
          or print STDERR "Unable to open $InputFile: $!";

#    Print page header
#    -----------------
     printf "\n\\markboth{Left}{Source File: %s,  Date: %s}\n\n",
                               $FileBaseName,    $Date;

LINE:
#    Inner loop --- for processing each line of the input file
#    ---------------------------------------------------------
     while ( <InputFile> ) {
        chop;     # strip record separator
        @Fld = split(' ', $_, 9999);

#       Straight quote
#       --------------
        if ($Fld[1] eq '!QUOTE:') {
           for ($i = 2; $i <= $#Fld; $i++) {
               printf '%s ', $Fld[$i];
}#         end for
           print " ";
           next LINE;
}#      end if

#       Handle optional Title Page and Introduction
#       -------------------------------------------
        if ($Fld[1] eq $boi_string) {
           print ' ';
           $intro = 1;
           next LINE;
}#      end if

        if ($Fld[2] eq '!TITLE:') {
           if ( $intro ) {
              shift @Fld;
              shift @Fld;
              @title = @Fld;
              $tpage = 1;
              next LINE;
}#         end if
}#      end if

        if ($Fld[2] eq '!AUTHORS:') {
           if ( $intro ) {
              shift @Fld;
              shift @Fld;
              @author = @Fld;
              $tpage = 1;
              next LINE;
}#         end if
}#      end if

        if ($Fld[2] eq '!AFFILIATION:') {
           if ( $intro ) {
              shift @Fld;
              shift @Fld;
              @affiliation = @Fld;
              $tpage = 1;
              next LINE;
}#         end if
}#      end if

        if ($Fld[2] eq '!DATE:') {
           if ( $intro ) {
              shift @Fld;
              shift @Fld;
              @date = @Fld;
              $tpage = 1;
              next LINE;
}#         end if
}#      end if

        if ($Fld[2] eq '!INTRODUCTION:') {
           if ( $intro ) {
              &do_beg();
              print ' ';
              print '%..............................................';
              shift @Fld;
              shift @Fld;
              print "\\section{@Fld}";
              next LINE;
}#         end if
}#      end if


#       End of introduction
#       -------------------
        if ($Fld[1] eq $eoi_string) {
           print ' ';
           print '%/////////////////////////////////////////////////////////////';
           print "\\newpage";
           $intro = 0;
           next LINE;
}#      end if

#       Beginning of prologue
#       ---------------------
        if ($Fld[1] eq $bop_string) {
           if ( $source ) { &do_eoc(); }
           print ' ';
           print '%/////////////////////////////////////////////////////////////';
           &do_beg();
           if ($first == 0) {
              ### print "\\newpage";
              print " ";
              print "\\mbox{}\\hrulefill\\ ";
              print " ";}
           else {
              unless($opt_b){print "\\section{Routine/Function Prologues} \\label{app:ProLogues}";}
}#         end if

           $first = 0;
           $prologue = 1;
           $verb = 0;
           $source = 0;
           &set_missing();   # no required keyword yet
           next LINE;
}#      end if

#       A new subroutine/function
#       -------------------------
        if ($Fld[2] eq '!ROUTINE:' ) { 
           if ($prologue) {
              shift @Fld;
              shift @Fld;
              $_ = join(' ', @Fld);
              $name_is = $_;
              s/_/\\_/g;                         # Replace "_" with "\_"
              if ( $opt_n && $not_first ) { printf "\\newpage\n"; }
              unless ($opt_f) {printf "\\subsection{%s (Source File: %s)}\n\n", $_, $FileBaseName;}
              else            {printf "\\subsection{%s }\n\n", $_;}
              $have_name = 1;
              $not_first = 1;
              next LINE;
}#         end if
}#      end if

#       A new Module
#       ------------
        if ($Fld[2] eq '!MODULE:' ) { 
           if ($prologue) {
              shift @Fld;
              shift @Fld;
              $_ = join(' ', @Fld);
              $name_is = $_;
              s/_/\\_/g;                         # Replace "_" with "\_"
              if ( $opt_n && $not_first ) { printf "\\newpage\n"; }
              unless($opt_f) {printf "\\subsection{Module %s (Source File: %s)}\n\n", $_, $FileBaseName;}
              else           {printf "\\subsection{Module %s }\n\n", $_;}
              $have_name = 1;
              $have_intf = 1;  # fake it, it does not need one.
              $not_first = 1;
              next LINE;
}#         end if
}#      end if

#       A new include file
#       ------------------
        if ($Fld[2] eq '!INCLUDE:' ) { 
           if ($prologue) {
              shift @Fld;
              shift @Fld;
              $_ = join(' ', @Fld);
              $name_is = $_;
              s/_/\\_/g;                         # Replace "_" with "\_"
              if ( $opt_n && $not_first ) { printf "\\newpage\n"; }
              unless($opt_f) {printf "\\subsection{Include File %s (Source File: %s)}\n\n", $_, $FileBaseName;}
              else           {printf "\\subsection{Include File %s }\n\n", $_;}  
              $have_name = 1;
              $have_intf = 1;  # fake it, it does not need one.
              $not_first = 1;
              next LINE;
}#         end if
}#      end if

#       A new INTERNAL subroutine/function
#       ----------------------------------
        if ($Fld[2] eq '!IROUTINE:') {            # Internal routine
           if ($prologue) {
              shift @Fld;
              shift @Fld;
              $_ = join(' ', @Fld);
              $name_is = $_;
              s/_/\\_/g;                        # Replace "_" with "\_"
              printf "\\subsubsection{%s}\n\n", $_;
              $have_name = 1;
              next LINE;
}#         end if
}#      end if

#       Description: what follows will be regular LaTeX (no verbatim)
#       -------------------------------------------------------------
        if (/!DESCRIPTION:/) {
           if ($prologue) {
              if ($verb) {
                 printf "\\end{verbatim}";
                 printf "\n{\\sf DESCRIPTION:\\\\ }\n\n";
                 $verb = 0; }
              else {                          # probably never occurs
}#            end if