New version of script for creating ThornGuide from Ian Kelley

git-svn-id: http://svn.cactuscode.org/flesh/trunk@2730 17b73243-c579-4c4c-a9d2-2d5706c11dac

1 files changed, 334 insertions, 476 deletions

diff --git a/lib/sbin/ParamLatex.pl b/lib/sbin/ParamLatex.pl
index 8531cfc7..8f056744 100644
--- a/lib/sbin/ParamLatex.pl
+++ b/lib/sbin/ParamLatex.pl
@@ -1,559 +1,417 @@
 #!/usr/bin/perl -s
 
+# here we say to play it safe and not let variables pop up from anywhere, except for 
+# the following variables in the 'use vars' statement, that can be passed in from 
+# the command.
+use strict;
+use vars qw($h $help $cctk_home $thornlist $outdir $verbose $debug $arrangements_dir $document_type);
+
 #########################
 # ->> ParamLatex.pl <<- #
 #########################################################################
-#                                                                       #
 #                      standard help function                           #
-#                                                                       #
 #########################################################################
-if ($h || $help) {
-   print "--> ParamLatex.pl <--\n";
-   print "Options:\n";
-   print "\t-th=        : (semi opt) thorn to process\n";
-   print "\t-arr=       : (semi opt) arrangement to process\n";
-   print "\t-processall : (opt) process all arrangements\n";
-   print "\t-directory= : (opt) dir. of arrangements (default arrangements/)\n";
-   print "\t-thornlist= : (opt) list specific thorns to process\n";
-   print "\t-dump       : (opt) dumps output to screen, not in Latex\n";
-   print "\t-scope=     : (opt) restricted/global/private/shares/all (default all)\n";
-   print "\t-sort=      : (opt) by: scope, type, name (default name)\n";
-   print "\t\t-reverse    : (opt) reverse whatever the sorting is\n";
-   print "\t-grouping=  : (opt) file ouput grouping scope (bythorn/byarrangement/all)\n";
-   print "\t-document   : (opt) creates a TeX document, not just a table\n";
-   print "\t-width=     : (opt) fixed width of table (default 160mm)\n";
-   print "\t-spacing=   : (opt) vertical spacing between elements (default 6mm)\n";
-   print "\t-outdir=    : (opt) directory to dump output files, default is .\n";
-   print "\t-section    : (opt) makes this a section of a greater document\n";
-   print "\t-h/-help    : (opt) this screen\n";
-   print "Example:\n";
-   print "\tperl -s /lib/sbin/ParamLatex.pl -outfile=mytable.tex -width=8.5cm\n";
-   exit 0;
+if ($h || $help) 
+{
+print <<EOC;
+This program will take as input a thornlist, and outputs a latex table that contains the information in the thorns' param.ccl file(s).  This latex table can then be used as a stand-alone document, or as a section of a large "ThornGuide"         
+
+-cctk_home=        : root directory of Cactus 
+-arrangements_dir= : arrangements directory
+-thornlist=        : thornlist to process
+-outdir=           : where to place resulting output files
+-document_type=    : is this a self containted 'document' or 'section'
+-verbose           : verbose output
+-debug             : (=1 is debug, >1 prints more info)
+-h | -help         : this screen
+EOC
+   
+exit 0;
 }
 
-#########################################################################
-#                                                                       #
-#  This program will take as input a thorn, and output a latex table    #
-#  that contains the information in that thorns param.ccl file.         #
-#                                                                       #
-#########################################################################
+#/*@@
+#  @file      ParamLatex.pl
+#  @date      Sun Mar  3 19:05:41 CET 2002
+#  @author    Ian Kelley
+#  @desc 
+#  This program will take as input a thornlist, and outputs a latex table    
+#  that contains the information in the thorns' param.ccl file(s).  This latex
+#  table can then be used as a stand-alone document, or as a section of a large
+#  "ThornGuide"         
+#  @enddesc 
+#  @version 
+#@@*/
+
+# setup the cctk_home, if it doesn't exist, we leave it blank
+$cctk_home  .= '/' if (($cctk_home !~ /\/$/) && (defined $cctk_home));
+
+# set up the sbin dir, tacking cctk_home on the front
+my $sbin_dir = "${cctk_home}lib/sbin";
 
 ##############
 # REQUIRE(S) #
 ##############
 
-$sbin_dir = "lib/sbin";
+# common procedures used to create the thornguide(s)
+require "$sbin_dir/ThornUtils.pm";
+
+# for use of create_parametere_database
 require "$sbin_dir/parameter_parser.pl";
 require "$sbin_dir/CSTUtils.pl";
 
-###########################
-# COMMAND LINE VAR. CHECK #
-###########################
+# for reading of the thornlist routine: %thorns = &ReadThornlist($thornlist)
+require "$sbin_dir/MakeUtils.pl";
 
-if (! $width)   {$width="160mm";}
-if (! $sort)   {$sort="name";}
-if (! $spacing) {$spacing="6mm";}
-if (((! $th) && (! $arr)) && (! defined $processall)) {
-   die "\nNo -th= or -arr= (or -processall) specified, nothing to process!\n";
-}
-if (! $directory) {$directory="arrangements/";} 
-if (! $grouping)  {$grouping="bythorn";}
+#####################
+# INITIAL VARIABLES #
+#####################
 
+my $start_directory = `pwd`;
+chomp ($start_directory);
 
-##################
-# INITIALIZATION #
-##################
+my $TABLE_WIDTH     = "160";
+my $MAX_VAR_LENGTH  = "20";
 
-@valid_types = qw(restricted global private shared);
+# set some variables in ThornUtils(.pm) namespace
+$ThornUtils::cctk_home       	= $cctk_home;
+$ThornUtils::start_directory	= $start_directory;
+$ThornUtils::verbose 		= $verbose;
+$ThornUtils::debug		= $debug;
 
-$start_directory=`pwd`;
-chomp($start_directory);
+# Just declare stuff in a common place, with some brief descriptions
 
-if (! $outdir) {
-    $outdir = "./";
-} else {
-   if ($outdir =~ /^\//) {
-      if (! -d "$outdir") {
-         mkdir($outdir, 0755);
-         print STDERR "\nCreating directory: $outdir" if ($verbose);
-      }
-   } else {
-      if (! -d "$start_directory/$outdir") {
-         mkdir("$start_directory/$outdir", 0755);
-         print STDERR "\nCreating directory: $start_directory/$outdir" if ($verbose);
-      }
-   }
-   if (! ($outdir =~ /\/$/)) {
-      $outdir .= "/";
-   }
-}
+my %thorns;                # what we add the output of &ReadParameterDatabase to, used for
+                           #  /-> used temporary when calling &ReadThornlist, which returns a hash
+my %arrangements_database; # |--> simplicity of organization.
+my %parameter_database;    # what we get as a return value from &create_parameter_database
+my %pathsToThorns;         # hash of thorn names and absolute paths to their directories
+my %arrangements;          # hash of arrangements, with links to lists of thorns
+my @listOfThorns;          # a list of thorns, made by reading/creating a thornlist
 
-print STDERR "\nOutput directory is: $outdir" if ($verbose);
+# set some defaults
+$document_type 	||= 'section';
 
-if (defined $thornlist) {
-   &Read_ThornList($thornlist);
- }
+#####################
+# END: DECLARATIONS #
+#####################
 
-#################################################
-# FIND THORN(S)/ARRANGEMENT(S) AND CREATE LATEX #
-#################################################
+# get/setup the output directory and the arrangements directory
+$outdir 		= ThornUtils::SetupOutputDirectory($outdir); 
+$arrangements_dir 	= ThornUtils::GetArrangementsDir($arrangements_dir);
 
-@arrangements = &Find_Directories($directory);
+# determine thornlist, create one if one doesn't exist
+if (defined $thornlist) {
+   # provided by MakeUtils.pl, returns a hash with a list of the thorns in our thornlist
+   %thorns 	 = &ReadThornlist($thornlist);
+   @listOfThorns = keys %thorns; 
+} else {
+   # we don't have a thornlist, go find all thorns in arrangements directory
+   @listOfThorns = ThornUtils::CreateThornlist($arrangements_dir);
+}
 
-&StartDocument("MasterTable") if ((! $dump) && ($grouping eq "all"));
+# this will return us a hash with keys as thorn names, and values as absolute paths to the 
+# thorn's directory param.ccl can be located in that path.
+#   We need this information to create a parameter database using create_parameter_database
+#
+# We are not doing ''one'' call to parameter_database as we easily could, because there is NO WAY
+# (currently) to distinguish between two identical thorns in different arrangements.  So we
+# would get stuff from Alphathorns/IOHDF5 in CactusBase/IOHDF5, or/and visa-versa. 
+ThornUtils::ClassifyThorns(\%arrangements, @listOfThorns);
+
+# lets go through, one arrangement at a time
+foreach my $arrangement (keys %arrangements) 
+{
+   print "\n$arrangement" if ($debug);
+   # now each thorn in the given arrangement
+   foreach my $thorn (@{$arrangements{$arrangement}}) 
+   {
+      print "\n\t$thorn" if ($debug);
 
-foreach $arrangement (sort @arrangements) {
-   @thorns = &Find_Directories($directory . $arrangement);
+      # get the path for this individual thorn
+      %pathsToThorns = ThornUtils::GetThornPaths(["$arrangement/$thorn"], $arrangements_dir, "param.ccl");
 
-   &StartDocument($arrangement) if ((! $dump) && ($grouping eq "byarrangement"));
-   THORN: foreach $thorn (@thorns) 
-   {
-   #   print STDERR "\nTHORN: $arrangement $thorn";
-      if (($processall) || (($thorn eq $th) || ($arr eq $arrangement))) 
-      { 
-
-         ## do not create a file for this thorn if it is not in the THORNLIST (if one is specified)
-	 if ((defined $thornlist) && (! defined $thornlist{"$arrangement/$thorn"})) {
-            next THORN;
-	 }
-
-         if (-e "$directory$arrangement/${thorn}/param.ccl") 
-         {
-            &StartDocument($thorn, $arrangement) if ((! $dump) && ($grouping eq "bythorn"));
-
-            $$thorn{$thorn} = "${directory}${arrangement}/${thorn}";
-            %parameter_database = &create_parameter_database(%$thorn);
-            &ReadLatexDatabase(%parameter_database);
-            &FormatTable;
-
-            &EndDocument if ((! $dump) && ($grouping eq "bythorn"));
-
-	    ###################################################
-            # reset the variables in case they are used again #
-            undef %alreadydone;
-
-  	    foreach $group_name (@valid_types) {
-#                print STDERR "\n\t\t-->$group_name";
-      		foreach $table (@$group_name) {
- #                  print STDERR "[$table]";
-		   undef %$table;
-		}
-	    }
-            # END of reset #
-            ################
-         }       
-      }
+      # now we create a parameter database (for one thorn), using the function 
+      # &create_parameter_database which is provided by 'parameter_parser.pl'
+      %parameter_database = &create_parameter_database(%pathsToThorns);
+
+      # Go split up the information we have recieved (again, for just this one thorn)
+      $arrangements_database{$arrangement}->{$thorn} = &ReadParameterDatabase(\%parameter_database);
    }
-   &EndDocument if ((! $dump) && ($grouping eq "byarrangement")); 
 }
 
-&EndDocument if ((! $dump) && ($grouping eq "all")); 
+# just dump out the data-structure if we are in debug mode, don't create any files
+if ($debug) {
+   ThornUtils::Dump(\%arrangements_database);
+   print "\n";
+   exit 0;
+} else {
+   ThornUtils::ProcessAllArrangements(\%arrangements_database);
+}
 
-print "\n" if ($verbose);
-#########################################################################
-#                 END OF MAIN SECTION OF THE PROGRAM                    # 
-#########################################################################
+print "\nFinished.\n";
+#############
+# END: MAIN #
+#############
 
 #########################################################################
 #                     BEGINNING OF SUB-ROUTINES                         #
 #########################################################################
 
-#########################################################################
-# ReadLatexDataBase                                                     #
-#   Calls parameter_parser.pl, which will read in the param.ccl file    #
-#   from a single thorn and return all data as a %hash table, which we  #
-#   will then parse to put into our own %hash tables named according to #
-#   the variable names.                                                 #
-#                                                                       #
-#   %(variable_name)  : any number of hashes created with their names   #
-#                       being the variable names, they then have $keys  #
-#                       (descriptions) with $values (well, values)      #
-#                          (e.g.) $name{"default"} = "Cactus";          #
-#   @global       \                                                     #
-#   @restricted    \  -> arrays containing the names of the relative    #
-#   @private       /     hashes that are contained within their scopes  #
-#   @shared       /             (masterlist contained in @valid_types)  #
-#########################################################################
-sub ReadLatexDatabase
+#/*@@
+#  @routine   ReadParameterDatabase
+#  @date      Sun Mar  3 01:54:37 CET 2002
+#  @author    Ian Kelley
+#  @desc 
+#  Hops through the parameter_database we got from &create_paramater_database, and trys 
+#  to classify things in a complex data-structure (hash of hashes of (hashes/arrays)) or
+#  something like that. 
+#     &ReadParameterDatabase(\%parameter_database); 
+#
+#  It then returns this data-structure, which can then be better (and cleaner) accessed
+#  when creating the latex page (as all the parsing was done here)
+#  
+#  Below are some examples of how to access data in the newly created structure:
+#
+#  [print out all the ''variables'']
+#     print "\nProgram variables:";
+#     foreach my $variable (keys %{$thorn{"variables"}}) {
+#        print "\n   $variable";
+#        foreach my $key (keys %{$thorn{"variables"}{$variable}}) {
+#           print "\n      $key = $thorn{\"variables\"}->{$variable}->{$key}";
+#        }
+#     }
+#
+#  [print out which variables are shared (an array)]
+#     print "\nShared group variables: ";
+#     foreach (@{$thorn{"groups"}{"shares"}}) {
+#        print "\n   $_"; 
+#     }
+#
+#  NOTE: Naturally, you will have to take into account that the returned hash (%thorn) may be
+#        part of a greater data-structure, so you may have to do something like:
+#           foreach (keys %{$thorns{"CactusWave"}{"WaveToyC"}{"variables"}}) {
+#  @enddesc 
+#  @version 
+#@@*/
+sub ReadParameterDatabase
 {
-  my(%parameter_database) = @_;
-  my($field);
-  my(@temp) = ();
-  my($temp) = "";
-  my($name) = "";
-  
-  #######################
-  # reinitialize values #
-  foreach $typ (@valid_types) {
-     while (defined pop(@$typ)) {pop @$typ;}
-  }
-                                 # where is global type???
-
-  foreach $field (sort keys %parameter_database)
-  {
-      print STDERR "\n$field --> $parameter_database{$field}" if ($verbose);
-
-      &Clean;
-         #################
-         # ADD TO SCOPES #
-         #################
-      if ($field =~ /\sPRIVATE\s/) {
-	@private = split/ /, $parameter_database{$field};	
-      } elsif ($field =~ /\sRESTRICTED\s/) {
-        @restricted = split/ /, $parameter_database{$field};
-      } elsif ($field =~ /\sSHARES\s+(\w+)\s+var/) {
-        @temp = split/ /, $parameter_database{$field};
- 
-        foreach $var (@temp) {
-           $var=~ tr/A-Z/a-z/;
-           $$var{"shared"}=$1;
-        }
-        push @shared, @temp;
-      } else {
-        #####################
-        # ADD VARIABLE HASH #
-        #####################
+   my (%parameterDatabase)	= %{$_[0]};
 
-        if ($field =~ /(.*?)\s(.*?)\s(.*)/) {
-           $name = $2; 
-           $field_des=$3;
-           $temp = $1; 
-        } else {
-   	   #print STDERR "\n\nTHROWNING AWAY: $field $paramater_database{$field}"; 
-        }
+   my %thorn;
 
-        $name =~ tr/A-Z/a-z/;
-        $$name{$field_des}=$parameter_database{$field};
-
-        $$name{"name"} = $name;
+   # only deals with one thorn at a time, as that is currently the nature of this program
+   foreach (sort keys %parameterDatabase)
+   {
+      print "\n--> [$_] = [$parameterDatabase{$_}]" if ($debug>1);
 
-        $$name{"thorn"} = $temp;
-      }
-   } #-- foreach
-   print "\n";
+      # save he original key, as we will make it all lower case later
+      # and need the original for hash keys
+      my $old_key = $_;
 
-   ################################
-   # ADD ELEMENT $$table{"scope"} #
-   ################################
+      # just in case they have declared it, but put nothing in it.
+      # if they did, don't waste our time parsing it.
+      next if (! $parameterDatabase{$old_key} =~ /\w/);
 
-   foreach $group_name (@valid_types) 
-   {
-      foreach $table (@$group_name) 
+      # drop the keys to lower-case, as they are all upper-case
+      tr/A-Z/a-z/;       
+   
+      # see if we are grabbing variable lists 
+      # (by scopes: global, private, restricted, shared, ...)
+      if (/^(.*?)\s+(.*?)\s+(.*?)\s*?variables$/) 
       {
-       #  print STDERR "\n\t\t!!!!!!!! $table";
-         $table =~ tr/A-Z/a-z/;
-      # print STDERR "\n$table";
-         $$table{"scope"} = $group_name;
-         if ($$table{"shared"}) {
-            $$table{"scope"} .= " from " . $$table{"shared"};
-         } 
-      } 
-
-   } 
-   return $name;
-} ## END :ReadLatexDatabase:
+         my @vars = split/\s+/, ThornUtils::ToLower($parameterDatabase{$old_key});
 
-#########################################################################
-# FormatTable                                                           #
-#    Primary function to be used to format the LaTex output to whatever #
-#    sorting or grouping mechanism specified by the user.               #
-#########################################################################
-sub FormatTable {
-        # sort: scope, type, name
-   my (@all);
-   while (defined pop(@all)) {pop @all;}
-
-   if ($sort eq "scope") {
-      if ((defined $scope) && ($scope ne "all")) {  # only one scope to output
-           if ($dump) {
-               &Dump(sort @$scope);
-            } else {
-               &CreateLatexTable(sort @$scope);
-            }
-      } else {
-         foreach $type (@valid_types) {
-            if ($dump) {
-               &Dump(sort @$type);
-            } else {
-               &CreateLatexTable(sort @$type);
-            }
+         # remember the scopes for each variable
+         foreach (@vars) { 
+            $thorn{"variables"}->{$_}->{"scope"} = $2 eq "shares" ? "shared from ". ThornUtils::ToUpper($3) : $2;
          }
-      }
-   } else {
-      if ((defined $scope) && ($scope ne "all")) {   # only print one scope
-         @all = @$scope;
-      } else {                                       # print all scopes
-         foreach $type (@valid_types) {
-             push @all, @$type;
-          }   
-      }
 
-      if ($sort eq "name") {
-         @all = sort @all; 
-      } else {
-         @all = sort SortByType @all;
+         @{$thorn{"groups"}->{$2}} = @vars;
+         next;
       }
 
-      if ($dump) {
-        &Dump(@all);
-      } else {
-        &CreateLatexTable(@all);
-      }      
-  }
+      # see if we can parse out some information from the keys
+      # if we cannot, drop a warning and continue
+      if (! /^(.*?)\s(.*?)\s(.*)$/) {
+         print STDERR "\nConfused: [$_] = [$parameterDatabase{$old_key}]" if ($verbose); 
+         next;
+      }
 
-    print "\n" if ($verbose || $dump);
-} ## END :FormatTable:
+      # let the thorn hash explicitly know the thorn name
+      $thorn{"thorn name"} = $1;
 
-#########################################################################
-# CreateLatexTable                                                      #
-#    Intermediary function in the process of creating a LaTex table that#
-#    loops through an array (of name passed in) and outputs LaTex in    #
-#    THE ORDER SPECIFIED IN THAT ARRAY.  So, there you have it, the     #
-#    foundation for sorting. :)                                         #
-#########################################################################
-sub CreateLatexTable {
-   my (@cur_group) = @_;
+      # add the new variable in the form of:
+      #   $thorn{"variables"}->{"initialize_memory"}->{"default"} = "none";
+      $thorn{"variables"}->{$2}->{$3} = $parameterDatabase{$old_key};
+   } # end: foreach %parameterDatabase
 
-   foreach $table (@cur_group) 
-   {
-      $table =~ tr/A-Z/a-z/;
-
-      if (lc($$table{"thorn"}) eq lc($thorn)) {
-         if (! defined $alreadydone{"$thorn$table"}) { 
-            &LatexTableElement;
-            $alreadydone{"$thorn$table"} = 1;   # to try to only print each once.
-          }
-      } 
-   }
-} ## END :CreateLatexTable:
-
-
-#########################################################################
-# StartDocument                                                         #
-#    Opens the file OUT with the name sent in to this function a .tex   #
-#    extension in the working directory for output of LaTeX code.       #
-#                                                                       #
-#    If specified with the -document flag on the command line, this     #
-#    function will also print basic LaTeX commands to start a document  #
-#########################################################################
-sub StartDocument {
-   my ($group_name) = shift;
-   my ($arrangement) = shift;
-
-   die "Cannot group tables for output, internal error in &StartDocument" if (! defined $group_name);
-
-   chdir ($start_directory);
-   open(OUT, ">$outdir${arrangement}_${group_name}_par.tex") || die "cannot open $outdir${group_name}_par.tex for output: $!";
-   $oldfilehandle = select OUT;
-
-   if ($document) {
-      print "\\documentclass[12pt,a4paper]\{article\} \n";
-      print "\\begin\{document\} \n\n";
-   } elsif ($section) {
-      $group_name =~ s/\_/\\\_/g;
-      print "\\section{Parameters} \n\n";
-   }
+   # return a reference to the newly created hash
+   return \%thorn;
 
+}
 
-} ## :StartDocument:
+#/*@@
+#  @routine   ProcessOneThorn
+#  @date      Sun Mar  3 01:54:37 CET 2002
+#  @author    Ian Kelley
+#  @desc 
+#
+#  @enddesc 
+#  @version 
+#@@*/
+sub ProcessOneThorn 
+{
+   # get the thorn hash
+   my (%thorn)      = %{$_[0]};
+   my $arrangement  = $_[1];
+   my $thorn 	    = $_[2];
+   my $latex_output = "";
+  
+   my $ofh = ThornUtils::StartDocument("param", $thorn, $outdir, $arrangement, "Parameters", $document_type);
 
-#########################################################################
-# EndDocument                                                           #
-#    Ends a LaTeX document (if -document) specified, and closes the OUT #
-#    file, which is used to write the LaTeX table to.                   #
-#########################################################################
-sub EndDocument {
-   if ($document) {
-      print "\\end\{document\} \n";
+   # go get the latex for setting the width of the columns based on the longest variable we have 
+   # (contained in the vaor $paragraph_len
+   if (defined $thorn{"variables"}) {
+      $latex_output = ThornUtils::SetWidth($TABLE_WIDTH, ThornUtils::CleanForLatex(FindMaxVarLen($thorn{"variables"})));
    }
-   close OUT;
-   select $oldfilehandle;
-} ## :EndDocument:
-
-#########################################################################
-# LatexTableElement                                                     #
-#    Takes whatever table element is currently reffered to by $table    #
-#    and prints it out into a LaTeX table.  Only nifty things it curr.  #
-#    does is NOT print ranges for BOOLEAN and SHARED elements.          #
-#########################################################################
-sub LatexTableElement {
-   $table =~ tr/A-Z/a-z/;
-   my ($name) = $table;
-   my ($description) = $$table{"description"};
-   my ($default) = $$table{"default"};
-   $default =~ s/\_/\\\_/g;
-   $default =~ s/%/\\%/g;
-   
-   $name =~ s/\_/\\\_/g;
 
-   $description =~ s/\_/\\\_/g;
-   
-   # new addition 4/2001
-   $description =~ s/\^/\\\^/g;
-
-   print "$table{\"thorn\"}";
- 
-   $parawidth = $width;
-   $parawidth =~ /(\d+)(.*)/;
-
-   $parawidth = ($1 - 35) . $2;
-
-   if (! (($$table{"description"} !~ /\w/) && (defined $$table{"shared"}))) {
-      print "\\begin\{tabular*\}\{$width\}\{|c|c|c|\@\{\\extracolsep\{\\fill\}\}r|\} \\hline \n";
-      print "\{\\bf Name\} & \{\\bf Default\} & \{\\bf Scope\} & \{\\bf Type\} \\\\ \n";
-      print "\\hline \n";
-      print "$name & $default & $$table{\"scope\"} & $$table{\"type\"} \\\\ \n";
-      print "\\hline\\hline\n";
-      print "\\multicolumn\{4\}\{|l|\}\{\\rule[-2mm]\{-2mm\}\{0.5cm\}\{\\bf Description\}~\\vline~ \n";
-      print "\\parbox\{${parawidth}\}\{\\it $description\}\} \\\\ \n";
-      print "\\hline \n";
-   } else {
-      print "\\begin\{tabular*\}\{$width\}\{|c|c|\@\{\\extracolsep\{\\fill\}\}r|\} \\hline \n";
-      print "\{\\bf Name\} & \{\\bf Scope\} & \{\\bf Type\} \\\\ \n";
-      print "\\hline \n";
-      print "$name & $$table{\"scope\"} & $$table{\"type\"} \\\\ \n";
-      print "\\hline \n";
+   # go through each group, then find all variables in the specific group type and generate the tables calling
+   # the function &CreateLatexTable 
+   foreach my $group_type (sort keys %{$thorn{"groups"}}) 
+   {
+      foreach my $variable_name (sort @{$thorn{"groups"}{$group_type}}) 
+      {
+         # send in the 'variable' hash, the name of the variable, and the longest variable in this thorn
+         $latex_output .= &CreateLatexTable($thorn{"variables"}{$variable_name}, $variable_name);
+      }
    }
 
-   print "\\end\{tabular*\} \n\n";
-
-   if ((($$table{"type"} ne "BOOLEAN") && ! $$table{"shared"}) && ($$table{"ranges"} > 0)) {
-
-      print "\\vspace\{1mm\} \n\n";
-
-      print "\\begin\{tabular*\}\{$width\}\{|c|l@\{\\extracolsep\{\\fill\}\}r|\} \\hline \n";
-      print "\{\\bf Range\} & & \\\\ \n";
-      print "\\hline\\hline \n";
-
-      for ($i=1; $i <= $$table{"ranges"}; $i++) {
-         $tempvar =  $$table{"range $i description"};
-         $tempvar =~  s/\_/\\\_/g;
+   print $latex_output;
+   ThornUtils::EndDocument($ofh, $document_type);
+}
 
-         $tempvar2 =  $$table{"range $i range"};
-         $tempvar2 =~  s/\_/\\\_/g;
+#/*@@
+#  @routine   CreateLatexTable
+#  @date      Sun Mar  3 01:54:37 CET 2002
+#  @author    Ian Kelley
+#  @desc 
+#     Creates a latex table for a given variable, returns the latex code to output
+#        &CreateLatexTable(<variable hash>, <variable name>);
+#
+#  @enddesc 
+#  @version 
+#@@*/
+sub CreateLatexTable 
+{
+   # get the stuff passed in, first is a hash of the given variable, second is the name of the variable,
+   # and third is the to-date longest variable in the thorn (for latex column formatting)
+   my %variable      = %{$_[0]};
+
+   # get the different properties of the variable, and clean then up so we can output good latex
+   my $variable_name = ThornUtils::CleanForLatex($_[1]);
+   my $scope         = ThornUtils::CleanForLatex($variable{"scope"});
+   my $default       = ThornUtils::AddQuotes(ThornUtils::CleanForLatex($variable{"default"}));
+   my $description   = ThornUtils::AddQuotes(ThornUtils::CleanForLatex($variable{"description"}));
+
+   # set some vars to hold the output we create
+   my $latex_output  = "";
+   my $range_output  = "";
+   my $extra_content = "";
+
+   # go through each range, check to see if we can find a longer variable for latex formatting,
+   # also compile the latex output for the ranges
+   for (my $i = 1; $i <= $variable{"ranges"}; $i++) 
+   {
+      my $over_range = 1;
+      my $range      = ThornUtils::AddQuotes(ThornUtils::CleanForLatex($variable{"range $i range"}));
+      my $range_desc = ThornUtils::AddQuotes(ThornUtils::CleanForLatex(ThornUtils::ChopVariable($variable{"range $i description"}, $MAX_VAR_LENGTH)));
 
-         # new addition 4/2001
-         $tempvar2 =~ s/\^/\\\^/g;
-         $tempvar2 =~ s/\$/\\\$/g;
+      # generate latex output for this range
+      if (length($range) > $MAX_VAR_LENGTH) 
+      {
+         $range_output .= "\\multicolumn{1}{|p{\\maxVarWidth}|}{see [$over_range] below} & \\multicolumn{2}{p{\\paraWidth}|}{$range_desc} \\\\";
+         $extra_content .= "\\noindent {\\bf [$over_range]} \\noindent \\begin{verbatim}". ThornUtils::ChopVariable($range, ($TABLE_WIDTH-10)/2)."\\end{verbatim}";
 
-         print "$tempvar2 & $tempvar & \\\\ \\hline \n";
+         $over_range++;
+      } else {
+         $range_output .= "\\multicolumn{1}{|p{\\maxVarWidth}|}{$range} & \\multicolumn{2}{p{\\paraWidth}|}{$range_desc} \\\\";
       }
-      print "\\end\{tabular*\} \n\n";
    }
 
-   print "\\vspace\{$spacing\} \n\n";
-} ## END :LatexTableElement:
+   # start the table (tabular) enviroment, printing out the 'name', 'scope' and 'type' of the variable
+   $latex_output .= "\\noindent \\begin{tabular*}{\\tableWidth}{|c|l\@{\\extracolsep{\\fill}}r|}\n\\hline\n\\multicolumn{1}{|p{\\maxVarWidth}}{$variable_name} & {\\bf Scope:} $scope & $variable{\"type\"} \\\\";
 
-#########################################################################
-# Find_Directories                                                      #
-#    Finds the current directories that are not CVS stuff contained w/in#
-#    the directory name that is sent to this function, used to find     #
-#    thorns and arrangements in this program.                           #
-#########################################################################
-sub Find_Directories {
-   my(@good_directories);
-   chdir ("$start_directory") || die "cannot chdir to $start_directory: $!";
-
-   chdir("$_[0]") || die "cannot change directory to $_[0] : $!";
-   open(LS, "ls -p|");
-   while(chomp($name = <LS>)) {
-      if ((($name =~ /\/$/) && ($name ne "History/")) && ($name ne "CVS/"))  {
-         $name =~ s#/##;
-         push(@good_directories, $name);
+   # print out the ranges, do nothing for shared variables
+   if ($scope =~ /shared from/) {
+      if ($variable{"ranges"} >= 1) {
+         $latex_output .= "\\hline\n\\multicolumn{3}{|l|}{\\bf Extends ranges:}\\\\ \n\\hline";
       }
-   }   
-   close(LS);
-   chdir ($start_directory);
-   return (@good_directories);
-} ## END :Find_Directories:
-
-#########################################################################
-# SortByType                                                            #
-#    Sorts the ouput by "type" within their respective thorns, as we can#
-#    have repetitive variable names within different thorns, currently  #
-#    output is restricted to internal (within thorn) sorting.           #
-#########################################################################
-sub SortByType {
-   if (lc($$a{"type"}) cmp lc($$b{"type"}) < 0) {
-      return -1;
-   } elsif (lc($$a{"type"}) cmp lc($$b{"type"}) > 0) {
-      return 1;
    } else {
-      return -1;
-   }
-} ## END :SortByType:
+      $latex_output .= "\\hline\n\\multicolumn{3}{|p{\\descWidth}|}{{\\bf Description:}   $description} \\\\\n\\hline";
 
-#########################################################################
-# SortByName                                                            #
-#    Sorts the ouput by "name" within their respective thorns, as we can#
-#    have repetitive variable names within different thorns, currently  #
-#    output is restricted to internal (within thorn) sorting.           #
-#########################################################################
-sub SortByName {
-   my ($first) = $$a{"name"};
-   my ($second) = $$b{"name"};
-
-   if (lc($first) cmp lc($second) < 0) {
-      print "\n$first : $second -1";
-      return -1;
-   } elsif (lc($$a{"name"}) cmp lc($$b{"name"}) > 0) {
-      print "\n$$a{\"name\"} : $$b{\"name\"} 0";
-      return 1;
-   } else {
-      print "\n$$a{\"name\"} : $$b{\"name\"} -1 (2)";
-      return -1;
-   }
-} ## END :SortByName:
+      if ($default !~ /\w/) {
+         $default = "(none)";
+      }
 
-#########################################################################
-# Dump                                                                  #
-#    Function to dump output to the screen rather than to a .tex file   #
-#    table, this does NOT create latex, simple provides an easy way to  #
-#    view the variables from the command line without use of Latex.     #
-#########################################################################
-sub Dump {
-  my (@cur_group) = @_;
- 
-  print "\n$thorn variables:\n";
-
-  foreach $value (@cur_group) {
-    if (lc($$value{"thorn"}) eq lc($thorn)) { 
-      print "\t$value:\n";
-      foreach $key (keys %$value) {
-	  print "\t\t$key -> $$value{$key}\n";
+      # print out the range headings if we have any ranges, otherwise just print a box for the default value
+      if ($variable{"ranges"} >= 1) {
+         $latex_output .= "{\\bf Range} & &  {\\bf Default:} $default \\\\";
+      } else {
+         $latex_output .= " & & {\\bf Default:} $default \\\\";
       }
-    }
-  }
-} ## END :Dump:
+   }
 
-#########################################################################
-# Clean                                                                 #
-#    Function to perform any cleaning that may need to be done to       #
-#    variables before they are put into a hash of their name.           #
-#########################################################################
-sub Clean {
-} ## END :Clean:
+   # insert the range data compiled earlier in a foreach loop
+   $latex_output .= $range_output;
 
+   # end the table
+   $latex_output .= "\\hline\n\\end{tabular*}\n\n\\vspace{1cm}";
 
-##########################
-# Reads in the thornlist #
-##########################
-sub Read_ThornList 
+   # return the output, tacking on the $extra_content, which will be any variable ranges that exceeded 
+   # the MAX_VAR_LENGTH restriction (for fitting into the boxes correctly)
+   return $latex_output . $extra_content;
+}
+
+#/*@@
+#  @routine   FindMaxVarLen
+#  @date      Sun Mar  3 01:54:37 CET 2002
+#  @author    Ian Kelley
+#  @desc 
+#     Finds the maximum length of all the ranges and variable names, to be used for setting the
+#     length of the different table cells.
+#        &FindMaxVarLen(<thorn hash>);
+#
+#  @enddesc 
+#  @version 
+#@@*/
+sub FindMaxVarLen 
 {
-   my ($thornlist) = shift;
+   my %thorn   = %{$_[0]};
+   my $max_len = "";
+#   my $temp    = "";
+
+   # we are going to go through each variable name and range name to see where
+   # the largest text is, then we will use this for later formatting of our 
+   # latex tables (so we do not get paragraph run-off
+   foreach my $variable (keys %thorn)
+   {
+      # we will always take the variable length as the standard maximum length,
+      # regardless of if it is longer than MAX_VAR_LENGTH
+      $max_len = length($variable) > length($max_len) ? $variable : $max_len;
 
-   chomp($directory);
+      for (my $i = 1; $i <= $thorn{$variable}{"ranges"}; $i++)
+      {
+         my $range = $thorn{$variable}{"range $i range"};
 
-   open (TL, "$thornlist") 
-      || die "cannot open thornlist ($thornlist) for reading: $!";
+         $range =~ s/^\s*(.*?)\s*$/$1/;
 
-   while (<TL>) 
-   {
-      s/(.*?)#.*/\1/;            # read up to the first "#"
-      s/\s+//g;                  # replace any spaces with nothing
-      if (/\w+/) {               
-         $thornlist{$_} = 1;
+         # if this new length is greater than the last one, but less than the max allowed
+         # length, then we asign the maximum variable length to this new length
+         if ((length($range) > length($max_len)) && (length($range) < $MAX_VAR_LENGTH)) {
+            $max_len = $range;
+         }
       }
    }
-   close TL;     
+
+   return $max_len;
 }