Contents 
 Index 
 "Perl Program Reference" 
 < Previous 
 Next > 

ini_html_gen.pl

Go to the documentation of this file.
00001 // This file has been modified on-the-fly with an input filter
00002 // to change it from Perl syntax to C++ strictly for the purposes
00003 // of faking out Doxygen. Modifications include:
00004 
00005 // - changing local() definitions to C++ #define statements.
00006 // - commenting out undef statements.
00007 // - changing $globe'... variable names to $globe_...
00008 // - changing sub statements to look like C++ functions.
00009 // - changing # comments to C++ comments.
00010 // - ...
00011 
00012 // If you see other strangeness in the HTML version of the Perl file,
00013 // it comes from getting it to look more C++ like.
00014 
00015 
00016 // #!/usr/#define/bin/perl
00017 package scheck;
00018 //#############################################################################
00019 /** @file
00020  ** @brief Generates one or more HTML files based upon what is found in
00021  ** the ini file.
00022  **
00023  ** ../perl/ini_html_gen.pl 
00024  ** @param root_dir something like doc_publish/cref_sysxini/ 
00025  ** @param src_ini source file to parse ./z_include/sysx.ini 
00026  ** @param html_tmpl template for generated files voyant_master_nav.html 
00027  ** @param org_title optional title for the example file.
00028  ** @param a_header optional additional source file with tag information.
00029  ** 
00030  ** 
00031  ** @ingroup tp_tools tp_xhelp
00032  **
00033  ** @author Glenn C. Maxey
00034  **/
00035 // #
00036 //#    $Id: ini_html_gen.pl,v 1.9 2002/11/20 15:23:02 gmaxe Exp $
00037 //#
00038 //# Copyright 2002 Created by Voyant Technologies, Inc., Westminster, Colorado, USA.
00039 //#
00040 //# Revision Information:
00041 //#
00042 //# $Log: ini_html_gen.pl,v $
00043 //# Revision 1.9  2002/11/20 15:23:02  gmaxe
00044 // //# Added exit codes so that wrapper scripts can catch errors properly.
00045 //#
00046 //# Revision 1.8  2002/11/14 00:36:51  gmaxe
00047 //# Added creation of doc and tag files while outputting sample.txt file.
00048 //#
00049 //# Revision 1.7  2002/10/11 20:20:06  gmaxe
00050 //# Minor changes to condition for target testing.
00051 //#
00052 //# Revision 1.6  2002/08/08 21:37:58  gmaxe
00053 //# Further enhancements for debugging and to get the man pages
00054 //# generated properly.
00055 //#
00056 //# Revision 1.3  2002/08/03 00:58:25  gmaxe
00057 //# Updates before the weekend. Now it parses target files better;
00058 //# had problems with scoping for variables.
00059 //#
00060 //# Revision 1.3  2002/07/02 23:10:53  gmaxe
00061 //# Tweaked to get rid of extra expanding line feeds in voyant_nav.pl.
00062 //# Added topper.html and other files to skip list in globe.pm.
00063 //# Enhanced ini_html_gen.gl to handle new format of message.txt;
00064 //# it now has a flatter data structure and no enums numbers.
00065 //#
00066 //# Revision 1.2  2002/04/22 17:53:33  gmaxe
00067 //# Minor enhancements to sorting order and TOC display.
00068 //# Also support an additional argument for a title.
00069 //#
00070 //# Revision 1.1  2002/04/20 11:31:22  gmaxe
00071 //# Added support for a tool that generates HTML for the log
00072 //# messages. This is one step away from a tool that does
00073 //# XML parsing to generate HTML. Some comments are still
00074 //# lacking.
00075 //#
00076 //# Revision 1.1  2002/04/12 22:52:25  gmaxe
00077 //# New tool to check on whether or not all SAPI commands are present.
00078 //# Uses the files generated by the vproto_gen.pl tool.
00079 //#
00080 //#
00081 //#############################################################################
00082 
00083 //#############################################################################
00084 /** @fn int BEGIN
00085  ** @brief Code to execute when first entered.
00086  **
00087  ** @param None. 
00088  **
00089  ** @return None.
00090  **
00091  ** @lim None
00092  ** @ingroup tp_xhelp
00093  **/
00094 // #############################################################################
00095 int BEGIN  ( ) {
00096 //    print "\n============  Starting ini_html_gen.pl ==================================\n";
00097    $_file_list = "_file_list";
00098    $in_file = "";
00099    $root_path = "./";
00100    $scope_pm = "globe.pm";
00101    $tag_xml = "initag";            //  used globally within this file.
00102    $globe::struct_start = "__";    //  used as the starting key into the xtag_struct.
00103    $globe::start_name = "INI";     //  used as the default name for the starting element
00104    $globe::pre_class = "Level1IX"; //  used to indicate what class to assign the HTML element
00105    $debug_verbose = 0;
00106    $copyright = "Created by Voyant Technologies, Inc.";
00107    
00108    $no_scope_file = 0;
00109    $arg_cnt=0;
00110    $yes_output = 1;  //  turns on and off whether html, script, and man pages are output
00111    $yes_output_man = 1; //  turns on and off man pages
00112    
00113    use POSIX 'strftime';   //  Use a selected function from POSIX library
00114    $date  strftime "%m/%d/%Y", #definetime
00115    
00116    
00117    push (@INC, `pwd`);
00118    push (@INC, '../perl');
00119    if (0){
00120 //       print (@INC, "\n");
00121    }
00122    
00123 
00124    
00125    //  Get scope files if there is one.
00126    if (1) { //  used
00127       //  $scope_pm = @ARGV[$arg_cnt];
00128       // ####
00129       //  All global variables are defined in the following file
00130       // ####
00131       
00132       unless (open ( IN_LIST, $scope_pm)) {
00133          unless (open ( IN_LIST, "../perl/$scope_pm")) {
00134             push (@file_errors, "Cannot open file \"$scope_pm\"");
00135             $no_scope_file++;
00136          }
00137       }
00138 //       close (IN_LIST);
00139       push (@INC, $scope_pm);
00140       
00141       if (!@file_errors) {
00142          // ####
00143          //  All global variables are defined in the following file
00144          // ####
00145          require $scope_pm;
00146    
00147          if (&globe::declare_variables()) {
00148 //             print "Variables initialized from $scope_pm.\n";
00149          } else {
00150             push (@file_errors, "Could not initialize variables from $scope_pm.");
00151          }
00152       } //  if not @file_errors
00153    } else {
00154       push (@file_errors, "Need to provide a scope file as first argument.");
00155    } //  if 1 or more arguments
00156 
00157  
00158  if (0) { //  commented out because not used
00159    //  Get scope files if there is one.
00160    if (@ARGV > $arg_cnt) {
00161       $scope_pm = @ARGV[$arg_cnt];
00162       
00163       unless (open ( IN_LIST, $scope_pm)) {
00164          push (@file_errors, "Cannot open file \"$scope_pm\"");
00165          $no_scope_file++;
00166       }
00167 //       close (IN_LIST);
00168       push (@INC, $scope_pm);
00169       
00170       if (!@file_errors) {
00171          // ####
00172          //  All global variables are defined in the following file
00173          // ####
00174          require $scope_pm;
00175    
00176          if (&globe::declare_variables()) {
00177 //             print "Variables initialized from $scope_pm.\n";
00178          } else {
00179             push (@file_errors, "Could not initialize variables from $scope_pm.");
00180          }
00181       } //  if not @file_errors
00182    } else {
00183       push (@file_errors, "Need to provide a scope file as first argument.");
00184    } //  if 1 or more arguments
00185    $arg_cnt++;
00186  } //  commented out because not used  
00187  
00188  
00189    if (!(exists ($globe::x_define{$tag_xml}))) {
00190       push (@file_errors, "\"$tag_xml\" does not exist in the global definitions (\"$scope_pm\").");
00191    }
00192 
00193 
00194    //  Get path to code files 
00195    if (@ARGV > $arg_cnt) {
00196       $root_path = @ARGV[$arg_cnt];
00197       $globe::path = @ARGV[$arg_cnt];
00198       if ($root_path =~ /\/$/) {
00199 //          print "The path specified is $root_path\n";
00200       } else {
00201          push (@file_errors, "The input argument \"$root_path\" requires a forward slash (\/) at the end.\n");
00202       }
00203    } //  if 1 or more arguments
00204    $arg_cnt++;
00205 
00206 
00207    if (@ARGV > $arg_cnt) {
00208       $org_ini = @ARGV[$arg_cnt];
00209 //       print "The message input file is $org_ini \n";
00210    } else {
00211       push (@file_errors, "Need to have the input message file.");
00212    } //  if 3 or more arguments
00213    $arg_cnt++;
00214 
00215    if (@ARGV > $arg_cnt) {
00216       $globe::master_nav_file = @ARGV[$arg_cnt];
00217 //       print "The master HTML input file is $globe::master_nav_file \n";
00218       unless (open ( IN_MASTER, $globe::master_nav_file)) {
00219          push (@file_errors, "Cannot open file \"$globe::master_nav_file\"\n");
00220       }
00221    } else {
00222       push (@file_errors, "Need to have the input master HTML file.");
00223    } //  if 3 or more arguments
00224    $arg_cnt++;
00225 
00226 
00227    if (@ARGV > $arg_cnt) {
00228       $org_title = @ARGV[$arg_cnt];
00229 //       print "The title for output is \"$org_title\" \n";
00230    } else {
00231       $org_title = "Sample INI File";
00232 //       print "The title for output is \"$org_title\" \n";
00233    } //  if 3 or more arguments
00234    $arg_cnt++;
00235 
00236 
00237    if (@ARGV > $arg_cnt) {
00238       $a_header = @ARGV[$arg_cnt];
00239 //       print "The additional header input file is $a_header \n";
00240       unless (open ( IN_HEADER, $a_header)) {
00241          push (@file_errors, "Cannot open file \"$a_header\"\n");
00242       }
00243    } else {
00244       // undef ($a_header);
00245    } //  if 3 or more arguments
00246    $arg_cnt++;
00247 
00248 } //  BEGIN
00249    
00250    
00251    
00252 
00253 //#############################################################################
00254 /** @fn int main
00255  ** @brief The main program.
00256  **
00257  ** @param file_errors If file errors are encountered before the main
00258 //  ** routine is hit, it prints them out and exits. 
00259  **
00260  ** @return None.
00261  **
00262  ** If the needed data structures in $scope_pm have not been enabled,
00263  ** this program errors out immediately.
00264  ** 
00265  ** Controls the program flow. It creates a temporary file with the
00266  ** error results.
00267  **
00268  ** @lim None
00269  ** @ingroup tp_xhelp
00270  **/
00271 // #############################################################################
00272 // sub main {
00273 {
00274    // #############################################################################
00275    // # Start of Main Program
00276    // #############################################################################
00277    if (@file_errors) {
00278       //  Makes no sense to go on if input parameters are off.
00279 //       print "\n============  Summary of errors ==================================\n";
00280       for ($i=0; $i<= $// file_errors; $i++){
00281 //          print "$i = $file_errors[$i]\n";
00282       }
00283       &scheck::using_scheck();
00284 //       exit(1);
00285    }
00286 
00287 
00288    if ((1) && (!(&master_file))){
00289 //       print "Master file failed some things.\n";
00290    } 
00291    
00292    if ($debug_verbose) {
00293 //       print "main and pre-rcnc with \"$org_ini\"\n";
00294    }
00295    
00296    if ((1) && (!(&globe::read_code_n_comment($org_ini, 1)))){
00297       //  The 1 means that we care about separating comments in the
00298       //  message.txt file from the lines that represent a log message.
00299 //       print "\"$org_ini\": INI file failed some things.\n";
00300    } 
00301    //  At this point, $globe::comment_file was created and populated,
00302    //  as was $globe::entire_file.
00303    if (0) {
00304 //       print $globe::entire_file;
00305 //       exit(1);
00306    }
00307    if (0) {
00308 //       print $globe::comment_file;
00309 //       exit(1);
00310    }
00311 
00312 
00313    if ((1) && (!(&create_data_structure))){
00314 //       print "Creating data structure failed some things.\n";
00315    } 
00316    //  At this point, the $globe::entire_file, which had the
00317    //  INI data in it, has been processed into a data structure.
00318    //     $globe::xtag_struct{$hname}{name}
00319    //  Hence, $globe::entire_file is no longer needed.
00320    //  However the $globe::comment_file is still needed.
00321    
00322 
00323    if ((1) && (!(&globe::process_comments_from_file($org_ini, $tag_xml)))){
00324 //       print "1 Processing comments from \"$org_ini\" failed some things.\n";
00325    } 
00326    if ($debug_verbose) {
00327 //       print "Processed comments from \"$org_ini\" with \"$tag_xml\"\n";
00328    }
00329    //  At this point, $globe::comment_file has been parsed and
00330    //  can be overwritten.
00331 
00332 
00333    // ####
00334    //  Do something dirty here by immediately reading in another
00335    //  file that we want to use as data as well.
00336    // ####
00337    if ($debug_verbose) {
00338 //       print "main and pre-rcnc with \"$a_header\"\n";
00339    }
00340    if ($a_header =~ /[\w]+/) {
00341       //  if the name is not empty then
00342 //       print "Processing \"$a_header\" as an additional file...\n";
00343       if ((1) && (!(&globe::read_code_n_comment($a_header, 0)))){
00344          //  The 0 means that we do not care about separating comments in the
00345          //  message.txt file from the lines that represent a log message.
00346 //          print "Getting additional information from \"$a_header\" failed some things.\n";
00347       }
00348       if ($debug_verbose) {
00349 //          print "Finished reading into the comment_file from \"$a_header\"\n";
00350       }
00351       if ((1) && (!(&globe::process_comments_from_file($a_header, $tag_xml)))){
00352 //          print "1 Processing comment_file from \"$a_header\" failed some things.\n";
00353       } 
00354       if ($debug_verbose) {
00355 //          print "Processed comments from \"$a_header\" with \"$tag_xml\"\n";
00356       }
00357    } else {
00358       if ($debug_verbose) {
00359 //          print "We did not try to process \"$a_header\"\n";
00360       }
00361    }
00362 
00363    //  At this point, $globe::comment_file has been parsed and
00364    //  can be overwritten.
00365    // ####
00366    
00367    
00368    
00369    //  At this point it is safe to call &globe::read_code_n_comment again with
00370    //  another file, because $globe::comment_file and $globe::entire_file
00371    //  have both been placed into the data structure already.
00372    //  Deep down in the next routine it does get called.
00373 
00374    if ((0) && ($debug_verbose)) {
00375       foreach $name (sort keys %{globe::xtag_struct}){
00376          if ($debug_verbose) {
00377 //             print "d1 $name:$globe::xtag_struct{$name}{comment_full}\n";
00378 //             print "d2 $name:$globe::xtag_struct{$name}{comment}\n";
00379 //             print "d3 $name:$globe::xtag_struct{$name}{html}\n";
00380          }
00381       }
00382 //       exit(1);
00383    }
00384    
00385    if ($debug_verbose) {
00386 //       print "Converting xtag into mess for \"$org_ini\" with \"$tag_xml\"\n";
00387    }
00388    // ####
00389    //  Having two structures is important: xtag_struct and tag_mess.
00390    // 
00391    //  The xtag_struct is built based upon what is found when it is read it.
00392    //  It contains the complete list of what is important to worry about (rather
00393    //  than extra things it might have found). Moreover, the xtag_struct
00394    //  is designed for a heirarchy and tracing using children arrays and parent
00395    //  hashes. 
00396    //  Although the top-level name is the same, only a few of the elements
00397    //  actually overlap with implementation in other files (globe.pm). 
00398    //  Additional hash structures are created here as needed.
00399    // 
00400    //    $hname = created name for hash made from actual names of parents and
00401    //             children 
00402    //    $globe::xtag_struct{$hname}{name} = actual item name
00403    //    $globe::xtag_struct{$hname}{parent} = owning section
00404    //    $globe::xtag_struct{$hname}{child}[] = array of associated children
00405    //    $globe::xtag_struct{$hname}{comment} = comment flag
00406    //    $globe::xtag_struct{$hname}{comment_full} = complete comments with no tags
00407    //    $globe::xtag_struct{$hname}{desc_html} = description in html
00408    //    $globe::xtag_struct{$hname}{desc_man} = description in man
00409    // 
00410    //  The tag_mess structure contains information found while chasing
00411    //  references in other files. It can ultimately contain much more information
00412    //  than what is truly needed for a given ini file.
00413    // 
00414    //  The tag_mess{file}{$file}{$identifier_tags}
00415    //  contains to information found for each.
00416    //  Its purpose is to quickly tell me if a referenced file has been
00417    //  processed for the $tag_xml items yet.
00418    //  The tag_mess{name}{$name} merely has an array with associated filenames.
00419    //  The filename is intended to allow you access to the complete data under
00420    //  tag_mess{file}. So the purpose is to see a complete list of what is
00421    //  available by tag.
00422    // 
00423    //  At this point, when need to get the xtag_struct into the tag_mess.
00424    // ####
00425    if ((1) && (!(&globe::xtag_into_mess_structure($org_ini, $tag_xml)))){
00426 //       print "Getting xtag into message structure failed some things; name \"$org_ini\".\n";
00427    } 
00428    if ($debug_verbose) {
00429 //       print "Converted xtag into mess for \"$org_ini\" with \"$tag_xml\"\n";
00430    }
00431 
00432    if ((0) && ($debug_verbose)) {
00433       foreach $name (sort keys %{globe::xtag_struct}){
00434          if ($debug_verbose) {
00435 //             print "d1 $name:$globe::xtag_struct{$name}{comment_full}\n";
00436 //             print "d2 $name:$globe::xtag_struct{$name}{comment}\n";
00437 //             print "d3 $name:$globe::xtag_struct{$name}{html}\n";
00438          }
00439       }
00440 //       exit(1);
00441    }
00442 
00443    // ####
00444    //  Comment zap... get rid of html that we don't like.
00445    // ####
00446    if (1) {
00447       foreach $name (sort keys %{globe::xtag_struct}){
00448          if ((0) && ($debug_verbose)) { //  debug
00449 //             //  print "$name:$globe::xtag_struct{$name}{comment_full}\n";
00450 //             //  print "======\n$globe::xtag_struct{$name}{html}\n";
00451 //             print "======\n$name\n";
00452          } //  debug
00453          $globe::xtag_struct{$name}{comment_full} = &comment_zap($globe::xtag_struct{$name}{comment_full});
00454          if ((0) && ($debug_verbose)) { //  debug
00455 //             print "$name:$globe::xtag_struct{$name}{comment_full}\n";
00456 //             //  print "$name:$globe::xtag_struct{$name}{html}\n";
00457          } //  debug
00458       }
00459 //       //  exit(1);
00460    }
00461    
00462 
00463    if ((0) && ($debug_verbose)) { //  debug
00464 //       print "Searching1 for stuff...\n";
00465       foreach $f (sort keys %{$globe::tag_mess{file}}) {
00466          foreach $t (sort keys %{$globe::tag_mess{file}{$f}}){
00467 //             print "\"$f\":\"$t\":\n$globe::tag_mess{file}{$f}{$t}\n";
00468          }
00469       }
00470 //       print "Searching2 for stuff...\n";
00471       foreach $t (sort keys %{$globe::tag_mess{name}}) {
00472          foreach $i (@{$globe::tag_mess{name}{$t}}){
00473 //             print "\"$t\":$globe::tag_mess{name}{$t}[$i]\n";
00474          }
00475       }
00476 //       print "Searching3 for stuff...\n";
00477 //       exit(1);
00478    } //  debug
00479    
00480    if ((1) && (!(&find_topic_order ($globe::struct_start, 0)))) {
00481 //       print "Finding topic order failed some things.\n";
00482    }
00483    
00484 
00485 
00486    if ((1) && (!(&topic_prev_next ($globe::struct_start, 0)))) {
00487 //       print "Topic prev_next failed some things.\n";
00488    }
00489    if ((1) && (!(&generate_desc_html ()))) {
00490 //       print "generate descriptive html failed some things.\n";
00491    }
00492 
00493    if ((0) && ($debug_verbose)) {
00494       foreach $name (sort keys %{globe::xtag_struct}){
00495          if (1) {
00496 //             //  print "$name:$globe::xtag_struct{$name}{comment_full}\n";
00497 //             print "$name:$globe::xtag_struct{$name}{desc_html}\n";
00498          }
00499       }
00500 //       exit(1);
00501    }
00502 
00503    
00504    // ####
00505    //  Error checking to make sure that things are complete
00506    //    $globe::xtag_struct{$hname}{name} = actual item name
00507    //    $globe::xtag_struct{$hname}{comment} = comment flag
00508    //    $globe::xtag_struct{$hname}{desc_html} = comment flag
00509    // ####
00510    if (1) { 
00511       &check_tbd ();
00512 //       //  exit(1);
00513    }
00514 
00515 
00516    
00517    // ####
00518    //  Output the individual HTML files.
00519    // ####
00520    if ($yes_output) {
00521       &write_output_html();
00522    }
00523    
00524    // ####
00525    //  The index is also generated in another step
00526    //  hence we don't have to waste time here, but could
00527    // ####
00528    if (0) {
00529       &generate_index;
00530    }
00531 
00532    if ($yes_output) {
00533       $file_out = "$globe::path";
00534       $file_out .= "tree.script";
00535       unless (open ( OUT_SCRIPT, ">$file_out")) {
00536          push (@file_errors, "2 Cannot open file \"$file_out\"\n");
00537 //          print "2 Cannot open file \"$file_out\"\n";
00538          return (0);
00539       }
00540       @path_piece = split (/\//, $globe::path);
00541       $strip_p = pop (@path_piece);
00542       $strip_p = pop (@path_piece);
00543       $strip_p .= "\/";
00544 
00545       // ####
00546       //  This top title is part of the master and does not need to be
00547       //  part of this.
00548       // ####
00549 //       print (OUT_SCRIPT "Item level=1 ");
00550 //       print (OUT_SCRIPT "image=nav_doc.gif ");
00551 //       print (OUT_SCRIPT "url=$globe::xtag_struct{$globe::struct_start}{html},basefrm ");
00552 //       print (OUT_SCRIPT "selected=YES ");
00553 //       print (OUT_SCRIPT "text=$globe::xtag_struct{$globe::struct_start}{name}");
00554 //       print (OUT_SCRIPT "\r\n");
00555 
00556       $out_string = "";
00557       &rec_generate_script ($globe::struct_start, 1);
00558 //       print (OUT_SCRIPT "$out_string\r\n");
00559 //       close (OUT_SCRIPT);
00560       if (1) {
00561 //          print "Creating $file_out...\n";
00562       }
00563    }
00564    if (0) { //  debug
00565 //       print "Topic ordering\n=====\n";
00566       for ($i=0; $i <= $// globe::topic_order; $i++) {
00567 //          print "$i:$globe::topic_order[$i]\n";
00568       }
00569 //       //  exit(1);
00570    }
00571 
00572    
00573    // ####
00574    //  This has to be place here well after the HTML is generated,
00575    //  because the first topic does not have the required {desc_html}
00576    //  until then.
00577    // ####
00578    if ((1) && (!(&generate_desc_man ()))) {
00579 //       print "Generating descriptive man failed some things.\n";
00580       $yes_output_man = 0;
00581    }
00582    
00583    // ####
00584    //  Generate the man pages. We'll aim for a [5]
00585    //    1    User commands that may be started by everyone.
00586    //    2    System calls, that is, functions provided by the kernel.
00587    //    3    Subroutines, that is, library functions.
00588    //    4    Devices, that is, special files in the /dev directory.
00589    //    5    File format descriptions, e.g. /etc/passwd.
00590    //    6    Games, self-explanatory.
00591    //    7    Miscellaneous, e.g. macro packages, conventions.
00592    //    8    System administration tools that only root can execute.
00593    //    9    Another (Linux specific) place for kernel routine documentation.
00594    //    n    (Deprecated) New documentation, that may be moved to a more appropriate section.
00595    //    o    (Deprecated) Old documentation, that may be kept for a grace period.
00596    //    l    (Deprecated) Local documentation referring to this particular system.
00597    // 
00598    // ####
00599    if ((1) && ($yes_output) && ($yes_output_man)) {
00600       $man_extension = "5";
00601       $mpath_out = "$globe::path";
00602       $mpath_out .= "man$man_extension/";
00603 //       print "$mpath_out\n";
00604       &rec_write_man($globe::struct_start);
00605    }
00606    
00607    
00608    // ####
00609    //  Output a sample file with tags.
00610    // ####
00611    if (1) {
00612 //       //  print "Here at the end.\n";
00613       &write_sample();
00614    }
00615     
00616    
00617    // #############################################################################
00618    // # Spit out errors
00619    // #############################################################################
00620    if ((1) && (@file_errors)) {
00621 //       print "\n============  Summary of errors ==================================main\n";
00622       for ($i=0; $i<@file_errors; $i++){
00623 //          print "$i = $file_errors[$i]\n";
00624       }
00625    }
00626 
00627    // #############################################################################
00628    // # End of most of work
00629    // #############################################################################
00630 //    exit(0);
00631 } //  main
00632 
00633 
00634 //#############################################################################
00635 /** @brief Reads in the entire master HTML file
00636  ** 
00637  ** @lim Fills up $globe::master variables.
00638  **/
00639 // #############################################################################
00640 int master_file  ( ) {
00641    #define $before  ""
00642    #define $after  ""
00643    #define $piece  ""
00644    #define $debug_master  0
00645    
00646    //  Get the master definitions
00647    while (<IN_MASTER>){    //  entire master file into memory.
00648       $globe::master_nav .= $_;
00649    }
00650 
00651    if (&globe::get_master_nav_info() >= 1){
00652 //       print "Master Navigation file \"$globe::master_nav_file\" has definition errors.\n";
00653       if (@file_errors) {
00654 //          print "\n============  Summary of errors ==================================master\n";
00655          for ($i=0; $i<@file_errors; $i++){
00656 //             print "$i = $file_errors[$i]\n";
00657          }
00658       }
00659       return (0);
00660    } else {
00661      
00662      //  Create special navigation in the footer that repeats buttons.
00663      $globe::voy_footer_fm = "$globe::m_define{footer}[0]\n<br><br>\n";
00664      $def_type = "nav_book";
00665      ($before, $piece, $after) = &globe::get_tag_chunk( $globe::m_info{$def_type},
00666                                  $globe::m_define{$def_type}[0], 
00667                                  $globe::m_define{$def_type}[1], 
00668                                  $very_critical);
00669 
00670      $globe::voy_footer_fm .= "$piece\n";
00671      
00672      $def_type = "footer";
00673      ($before, $piece, $after) = &globe::get_tag_chunk( $globe::m_info{$def_type},
00674                                  $globe::m_define{$def_type}[0], 
00675                                  $globe::m_define{$def_type}[1], 
00676                                  $very_critical);
00677      
00678      $globe::voy_footer_fm .= "$piece\n";
00679      $globe::voy_footer_fm .= "$globe::m_define{footer}[1]\n";
00680 
00681      
00682      $globe::master_order_key = @globe::master_order;  //  sets the default value
00683      for ($i=0; $i <= $// globe::master_order -1; $i++){
00684         //  does not go to the last one, because that is the default, already set
00685         if ($globe::path =~ /$globe::master_order[$i]/){
00686            $globe::master_order_key = $i;
00687            if ($debug_master) {
00688 //               print "$i = $globe::master_order[$globe::master_order_key]\n";
00689            }
00690         }
00691      }
00692      if ($debug_master) {
00693 //         print "=== Master Header ==\n$globe::m_info{header}\n";
00694 //         print "=== Master Common Top ==\n$globe::m_info{nav_common}\n";
00695 //         print "=== Master Doxygen ==\n$globe::m_info{nav_doxygen}\n";
00696 //         print "=== Master FM Book ==\n$globe::m_info{nav_book}\n";
00697 //         print "=== Master Footer ==\n$globe::m_info{footer}\n";
00698 //         print "=== Master Dox Footer ==\n$globe::voy_footer_dox\n";
00699 //         print "=== Master FM Footer ==\n$globe::voy_footer_fm\n";
00700 //         print "=== Master variables ==\n$globe::m_info{variable}\n";
00701         //  return (0);
00702      }
00703    }
00704    return (1);
00705 } //  master file
00706 
00707 
00708 //#############################################################################
00709 /** @brief Creates a data structure from each line in the message file.
00710  ** 
00711  **       $hname = created name for hash made from actual names of parents and
00712  **                children 
00713  **       $globe::xtag_struct{$hname}{name} = actual item name
00714  **       $globe::xtag_struct{$hname}{parent} = owning section
00715  **       $globe::xtag_struct{$hname}{child}[] = array of associated children
00716  **       $globe::xtag_struct{$hname}{comment} = comment flag
00717  **       $globe::xtag_struct{$hname}{comment_full} = complete comments with no tags
00718  **       $globe::xtag_struct{$hname}{desc_html} = description in html
00719  **       $globe::xtag_struct{$hname}{desc_man} = description in man
00720  ** 
00721  ** @lim 
00722  **/
00723 // #############################################################################
00724 int create_data_structure  ( ) {
00725 
00726    #define $debug_cds  0
00727    // undef (%globe::xtag_struct);
00728    
00729    $hname = $globe::struct_start;
00730    $globe::xtag_struct{$hname}{name} = "$org_title";
00731    $globe::xtag_struct{$hname}{parent} = "$globe::struct_start";
00732    
00733    @_input_line = split (/\n/, $globe::entire_file);
00734    
00735    $file_index = 0;
00736    
00737    while ($file_index <= $// _input_line) {
00738       if ($debug_cds) {
00739 //          print "$file_index parent: \"$hname\"\n";
00740       }
00741       $hname = &build_trace_xtag_struct ($hname, $file_index);
00742       $file_index++;
00743    }
00744    
00745    if (0) {
00746       //  &rec_trace_struct ($globe::struct_start);
00747       &rec_trace_struct2 ($globe::struct_start, 0);
00748 //       exit(1);
00749    }
00750    
00751    return (1);
00752 } //  create_data_structure
00753 
00754 //#############################################################################
00755 /** @brief Traces through the input and builds an xtag_struct for the INI file.
00756  **
00757  ** @param h_ind The name of the parent section as the hash index.
00758  ** @param file_line_index The index to the file array.
00759  **
00760  ** @return The hash index for the parent; that is either the parent
00761  ** already passed in, or itself if it is determined to have children
00762 //  ** based on whether or not it is enclosed in braces. In addition, the
00763  ** xtag_struct is built up for the element.
00764  **
00765  **  $name is the key into the hash made up of all previous levels
00766  ** and this level.
00767  **       $globe::xtag_struct{$name}{name} = Display name for item.
00768  **
00769  **/
00770 // #############################################################################
00771 int build_trace_xtag_struct  ( ) {
00772    $h_ind = $_[0];
00773    $file_line_index = $_[1];
00774    #define $debug_btxs  0
00775    // undef (@line_chunk);
00776    // undef (@line_chunk2);
00777    // undef (@line_chunk3);
00778    #define $plus  0
00779    
00780    $line = $_input_line[$file_line_index];
00781    $line =~ s/^\s*//;  //  strip out leading spaces
00782    $line =~ s/\s*$//;  //  strip out trailing spaces
00783    if ($debug_btxs) {
00784 //       print "line:$line\n";
00785    }
00786 
00787    //  08/12/2002 handle appending to a variable
00788    if ($line =~ /\/\//) {
00789       //  get to the components of the line
00790       @line_chunk = split (/\/\//, $line, 2);
00791       if ($line_chunk[0] =~ /\+\=/) {
00792          //  Then it has a default value
00793          @line_chunk2 = split (/\+\=/, $line_chunk[0], 2);
00794          $name = $line_chunk2[0];   //  name is in front of +=
00795          //  get default value which is after the ='s.
00796          $default = $line_chunk2[1];
00797          $plus = 1;
00798       } elsif ($line_chunk[0] =~ /\=/) {
00799          //  Then it has a default value
00800          @line_chunk2 = split (/\=/, $line_chunk[0], 2);
00801          $name = $line_chunk2[0];   //  name is in front of =
00802          //  get default value which is after the ='s.
00803          $default = $line_chunk2[1];
00804       } else {
00805          //  Then it does not a default value; probably a section
00806          $default = "";
00807          $name = $line_chunk[0];  //  name is in front of //
00808       }
00809    } else {
00810       //  Item has no comments
00811       if ($line =~ /\+\=/) {
00812          //  Then it has a default value
00813          @line_chunk2 = split (/\+\=/, $line, 2);
00814          $name = $line_chunk2[0];   //  name is in front of +=
00815          //  get default value which is after the +='s.
00816          $default = $line_chunk2[1];
00817          $plus = 1;
00818       } elsif ($line =~ /\=/) {
00819          //  Then it has a default value
00820          @line_chunk2 = split (/\=/, $line, 2);
00821          $name = $line_chunk2[0];   //  name is in front of =
00822          //  get default value which is after the ='s.
00823          $default = $line_chunk2[1];
00824       } else {
00825          //  Then it does not a default value; probably a section
00826          $default = "";
00827          $name = $line;  //  name is the line
00828       }
00829    }
00830    $name =~ s/^[\s]*//g;  //  get rid of leading space
00831    $name =~ s/[\s]*$//g;  //  get rid of trailing space
00832 
00833    if ($debug_btxs) {
00834 //       print "name1:$name\n";
00835    }
00836    $name =~ s/\s*$//;  //  strip out trailing spaces
00837    $bracket_flag = 0;
00838    if ($name =~ /\[/) {
00839       $name =~ s/\[//;    //  strip out brackets if section
00840       $name =~ s/\]//;    //  strip out brackets if section
00841       $bracket_flag = 1;
00842    }
00843    if ($debug_btxs) {
00844 //       print "name2:$name\n";
00845    }
00846    $default =~ s/^\s*//;  //  strip out leading spaces
00847    $default =~ s/\s*$//;  //  strip out trailing spaces
00848    if ($debug_btxs) {
00849 //       print "default:$default\n";
00850    }
00851    $new_h_ind = "$h_ind\-$name";
00852 
00853    //  We check for comments again because when we do it above,
00854    //  it is too detailed in a special case for defaults.
00855    if ($line =~ /\/\//) {
00856       //  redefine line_chunk; okay
00857       @line_chunk = split (/\/\//, $line, 2);
00858       $comment = $line_chunk[1];
00859       $comment =~ s/^[\s]*//;  //  strip out leading spaces
00860    } else {
00861       $comment = "";
00862    }
00863    
00864    // ####
00865    //  Create the data structure for messages.
00866    // ####
00867    if ($line =~ /^\[\]/) {
00868       // ####
00869       //  End of a section
00870       // ####
00871       if ($debug_btxs) {
00872 //          print "end   :\"$line\" with parent:\"$globe::xtag_struct{$h_ind}{parent}\"\n";
00873       }
00874       return ($globe::xtag_struct{$h_ind}{parent});
00875 
00876    } elsif ($line =~ /^\[/) {
00877       // ####
00878       //  Start of another section
00879       // ####
00880       if ($debug_btxs) {
00881 //          print "begin   :\"$name\" and \"$new_h_ind\"\n";
00882       }
00883       
00884       push (@{$globe::xtag_struct{$h_ind}{child}}, $new_h_ind);
00885       if ($comment) {
00886          $globe::xtag_struct{$new_h_ind}{comment} = $comment;
00887       }
00888       $globe::xtag_struct{$new_h_ind}{parent} = $h_ind;
00889       if ($bracket_flag) {
00890          $globe::xtag_struct{$new_h_ind}{name} = "\[$name\]";
00891       } else {
00892          $globe::xtag_struct{$new_h_ind}{name} = $name;
00893       }
00894       return ($new_h_ind);
00895 
00896    } else {
00897       // ####
00898       //  A child of the section
00899       // ####
00900       if ($debug_btxs) {
00901 //          print "middle1   :$name, default :$default\n";
00902       }
00903       
00904       push (@{$globe::xtag_struct{$h_ind}{child}}, $new_h_ind);
00905       if ($comment) {
00906          $globe::xtag_struct{$new_h_ind}{comment} = $comment;
00907       }
00908       //  $default =~ s/\(//g;
00909       //  $default =~ s/\)//g;
00910       if ($debug_btxs) {
00911 //          print "middle2   :$name, default :$default\n";
00912       }
00913       if ($default) {
00914          $globe::xtag_struct{$new_h_ind}{default} = "$default";
00915       }
00916       if ($plus) {
00917          $globe::xtag_struct{$new_h_ind}{plus} = "\+";
00918       }
00919       if ($debug_btxs) {
00920 //          print "middle3   :$name, default :$globe::xtag_struct{$new_h_ind}{default}\n";
00921       }
00922 
00923       $globe::xtag_struct{$new_h_ind}{parent} = $h_ind;
00924       if ($bracket_flag) {
00925          $globe::xtag_struct{$new_h_ind}{name} = "\[$name\]";
00926       } else {
00927          $globe::xtag_struct{$new_h_ind}{name} = $name;
00928       }
00929       return ($h_ind);
00930    } //  Create the data structure for messages.
00931    
00932 } //  build_trace_xtag_struct
00933 
00934 
00935 //#############################################################################
00936 /** @brief Used as an example to trace through the structure.
00937  **
00938  ** @param seed The current element in the structure.
00939 //  ** @param level The current level for the seed; used to print out
00940  ** the appropriate amount of leading spaces for indents.
00941  **
00942  ** This routine isn't used as is. However, it forms the basis for
00943 //  ** other specific routines for printing out HTML, script files,
00944  ** or other things. When in doubt about what is being built,
00945  ** this routine can be called.
00946  **
00947  ** @lim This routine is called recursively as it traces through the structure.
00948  ** It steps through the children array for a given item.
00949  **/
00950 // #############################################################################
00951 int rec_trace_struct2  ( ) {
00952    #define $seed  $_[0]
00953    #define $level  $_[1]
00954    
00955    if (0) {
00956 //       print "seed: \"$seed\"\n";
00957    }
00958    if (exists ($globe::xtag_struct{$seed}{child})) {
00959       //  means we need to trace down into it
00960       if ($globe::struct_start !~ /$seed/) {
00961          for ($i=1; $i<=$level; $i++){
00962 //             print "   ";
00963          }
00964 //          print "$globe::xtag_struct{$seed}{name}";
00965          if (exists ($globe::xtag_struct{$seed}{comment})) {
00966 //             print "\t      \/\/ $globe::xtag_struct{$seed}{comment}\n";
00967          } else {
00968 //             print "\n";
00969          }
00970          $level++;
00971       }
00972       foreach $child (@{$globe::xtag_struct{$seed}{child}}) { 
00973 //          //  print "name:  \"$hname\"\n";
00974          &rec_trace_struct2 ($child, $level);
00975          if (0) {
00976 //             print "seed: \"$seed\"\n";
00977          }
00978       }
00979       if ($globe::struct_start !~ /$seed/) {
00980          $level--;
00981          for ($i=1; $i<=$level; $i++){
00982 //             print "   ";
00983          }
00984 //          print "\[\]";
00985 //          print "\t      \/\/ $globe::xtag_struct{$seed}{name}\n";
00986       }
00987    } else {
00988       //  means we're at a child level with no children
00989 //       //  can print out and return
00990       if ($globe::struct_start !~ /$seed/) {
00991          for ($i=1; $i<=$level; $i++){
00992 //             print "   ";
00993          }
00994          if (1) {
00995 //             //  print "ddddefault :$globe::xtag_struct{$seed}{default}\n";
00996             if (exists ($globe::xtag_struct{$seed}{default})) {
00997                if (exists ($globe::xtag_struct{$seed}{comment})) {
00998 //                   print "$globe::xtag_struct{$seed}{name} ";
00999 //                   print "$globe::xtag_struct{$seed}{plus}\= ";
01000 //                   print "$globe::xtag_struct{$seed}{default}";
01001 //                   print "\t      \/\/ $globe::xtag_struct{$seed}{comment}\n";
01002                } else {
01003 //                   print "$globe::xtag_struct{$seed}{name} ";
01004 //                   print "$globe::xtag_struct{$seed}{plus}\= ";
01005 //                   print "$globe::xtag_struct{$seed}{default}";
01006 //                   //  print "\t      \/\/ no comment Dude!!!\n";
01007 //                   print "\n";
01008                }
01009             } else {
01010                if (exists ($globe::xtag_struct{$seed}{comment})) {
01011 //                   print "$globe::xtag_struct{$seed}{name}";
01012 //                   print "\t      \/\/ $globe::xtag_struct{$seed}{comment}\n";
01013                } else {
01014 //                   print "$globe::xtag_struct{$seed}{name}";
01015 //                   //  print "\t      \/\/ no comment Dude!!!\n";
01016 //                   print "\n";
01017                }
01018             }
01019          } //  if (1)
01020       }
01021    } 
01022 } //  rec_trace_struct2
01023 
01024 //#############################################################################
01025 /** @brief Returns a list of the owning sections for a given INI item.
01026  **
01027  ** @param pseed The point to start at in the structure.
01028  ** @param html Whether or not to output html for the list.
01029  **
01030  ** @return It returns a string that either is formatted as HTML or is
01031  ** formatted as simply text. The HTML version is fully hyperlinked.
01032  **
01033  ** From the initial starting point, this keeps asking for the parent
01034  ** until it reaches the top most level.
01035  **
01036  ** At each level, it appends the name information to a string.
01037  **       $globe::xtag_struct{$hname}{parent} = owning section
01038  **/
01039 // #############################################################################
01040 int parent_trace  ( ) {
01041    #define $pseed  $_[0]
01042    #define $html  $_[1]
01043    #define $org_seed  $pseed
01044    #define $outpath  "$globe::xtag_struct{$pseed}{name}"
01045    #define $before  ""
01046    #define $after  ""
01047    #define $piece  ""
01048    
01049    while ($globe::struct_start !~ /$pseed/) {
01050       $pseed = $globe::xtag_struct{$pseed}{parent};
01051       if ($globe::struct_start !~ /$pseed/) {
01052          $outpath = "<a href=\"$globe::xtag_struct{$pseed}{html}\">$globe::xtag_struct{$pseed}{name}</a>\.$outpath";
01053       } elsif ($html) {
01054          $outpath = "<a href=\"$globe::xtag_struct{$pseed}{html}\// $org_seed\">\{Context\}</a>\.$outpath";
01055       } else {
01056          //  for non-html, we don't need the top level context reference.
01057       }
01058    }
01059    if (!($html)) {
01060       //  strip out all html references
01061       while ((0) && ($outpath =~ /\</)) {
01062 //          //  print "yes1";
01063          ($before, $piece, $after) = &globe::get_tag_chunk( $outpath,
01064                                   "<", ">", 0);
01065          $outpath = join ("", $before, $after);
01066       }
01067       while ((1) && ($outpath =~ /<a href/)) {
01068 //          //  print "yes1";
01069          ($before, $piece, $after) = &globe::get_tag_chunk( $outpath,
01070                                   "<a href", ">", 0);
01071          $outpath = join ("", $before, $after);
01072       }
01073       while ((1) && ($outpath =~ /<\/a/)) {
01074 //          //  print "yes2";
01075          ($before, $piece, $after) = &globe::get_tag_chunk( $outpath,
01076                                   "<\/a", ">", 0);
01077          $outpath = join ("", $before, $after);
01078       }
01079    }
01080    return ($outpath);
01081 } //  parent_trace
01082 
01083 
01084 //#############################################################################
01085 /** @brief Creates an example INI file in HTML based on what is known.
01086  ** 
01087  ** @param seed Starting point in the structure.
01088  ** @param level Starting level in the structure. Used to control indenting in
01089  ** the output.
01090  **
01091  ** @retval out_string is a global variable holding the desired output. This
01092  ** output is fully hyperlinked.
01093  **
01094  ** This calls itself recursively as it steps through the xtag_struct for
01095  ** each parent and child array. It creates appropriate index tags
01096  ** for subsequent tool calls. Its purpose is to show the context of an INI
01097  ** item.
01098  **
01099  ** @lim This is called recursively. The $out_string is used in a global
01100  ** manner and exist from call-to-call.
01101  **
01102  **/
01103 //  &rec_example_topic ($globe::struct_start, 0);
01104 //#############################################################################
01105 int rec_example_topic  ( ) {
01106    #define $seed  $_[0]
01107    #define $level  $_[1]
01108    
01109    if (0) {
01110 //       print "seed: \"$seed\"\n";
01111    }
01112    if (exists ($globe::xtag_struct{$seed}{child})) {
01113       //  means we need to trace down into it
01114       if ($globe::struct_start !~ /$seed/) {
01115          $out_string .= "<pre class=\"$globe::pre_class\">";
01116          for ($i=1; $i<=$level; $i++){
01117             $out_string .= "   ";
01118          }
01119          // ####
01120          //  Puts in anchor/index/target to topic
01121          //  <a name="zzzz" class="v_index" value="token text">
01122          // ####
01123          $temp = $globe::xtag_struct{$seed}{name};
01124          $temp =~ s/\[//; //  strip out brackets
01125          $temp =~ s/\]//; //  strip out brackets
01126          $out_string .= "<a name=\"";
01127          $out_string .= "$seed";
01128          $out_string .= "\" class=\"v_index\" value=\"$temp\">";
01129          $out_string .= "</a>";
01130          // ####
01131          //  Puts in hyperlink to topic
01132          // ####
01133          $out_string .= "<a href=\"";
01134          $out_string .= "$globe::xtag_struct{$seed}{html}";
01135          $out_string .= "\">";
01136          $out_string .= "$globe::xtag_struct{$seed}{name}";
01137          $out_string .= "</a>";
01138          $out_string .= "</pre>\r\n";
01139          $level++;
01140       }
01141       foreach $child (@{$globe::xtag_struct{$seed}{child}}) { 
01142          &rec_example_topic ($child, $level);
01143       }
01144       if ($globe::struct_start !~ /$seed/) {
01145          $level--;
01146          $out_string .= "<pre class=\"$globe::pre_class\">";
01147          for ($i=1; $i<=$level; $i++){
01148             $out_string .= "   ";
01149          }
01150          $out_string .= "\[\]";
01151          $out_string .= "   \/\/ $globe::xtag_struct{$seed}{name}";
01152          $out_string .= "</pre>\r\n";
01153       }
01154    } else {
01155       //  means we're at a child level with no children
01156 //       //  can print out and return
01157       if ($globe::struct_start !~ /$seed/) {
01158          $out_string .= "<pre class=\"$globe::pre_class\">";
01159          for ($i=1; $i<=$level; $i++){
01160             $out_string .= "   ";
01161          }
01162          // ####
01163          //  Puts in anchor/index/target to topic
01164          //  <a name="zzzz" class="v_index" value="token text">
01165          // ####
01166          $temp = $globe::xtag_struct{$seed}{name};
01167          $temp =~ s/\[//; //  strip out brackets
01168          $temp =~ s/\]//; //  strip out brackets
01169          $out_string .= "<a name=\"";
01170          $out_string .= "$seed";
01171          $out_string .= "\" class=\"v_index\" value=\"$temp\">";
01172          $out_string .= "</a>";
01173          // ####
01174          //  Puts in hyperlink to topic
01175          // ####
01176          $out_string .= "<a href=\"";
01177          $out_string .= "$globe::xtag_struct{$seed}{html}";
01178          $out_string .= "\">";
01179          if (exists ($globe::xtag_struct{$seed}{default})) {
01180             $out_string .= "$globe::xtag_struct{$seed}{name}";
01181             $out_string .= "</a>";
01182             $out_string .= " $globe::xtag_struct{$seed}{plus}\=";
01183             $out_string .= " $globe::xtag_struct{$seed}{default}";
01184          } else {
01185             $out_string .= "$globe::xtag_struct{$seed}{name}";
01186             $out_string .= "</a>";
01187          }
01188         
01189          $out_string .= "</pre>\r\n";
01190          
01191          { //  indent brackets.
01192             //  for when a section is defined but has no children.
01193             if ($globe::xtag_struct{$seed}{name} =~ /^\[/) {
01194                if ($globe::struct_start !~ /$seed/) {
01195                   //  $level--;
01196                   $out_string .= "<pre class=\"$globe::pre_class\">";
01197                   for ($i=1; $i<=$level; $i++){
01198                      $out_string .= "   ";
01199                   }
01200                   $out_string .= "\[\]";
01201                   $out_string .= "   \/\/ $globe::xtag_struct{$seed}{name}";
01202                   $out_string .= "</pre>\r\n";
01203                }
01204             } //  when section has no children
01205          } //  indent brackets
01206         
01207          
01208       }
01209    } 
01210 } //  rec_example_topic
01211 
01212 
01213 //#############################################################################
01214 /** @brief Traces the xtag_struct recursively.
01215  ** 
01216  ** @param seed Starting point in the structure.
01217  **
01218  ** This is not used directly. However, it serves as an example for other
01219  ** operations that might need to recursively step through the data structure.
01220  ** Several other routines for generating output or manipulating navigation
01221  ** were based upon this routine.
01222  ** 
01223  ** @lim This is called recursively.
01224  **/
01225 // #############################################################################
01226 int rec_trace_struct  ( ) {
01227    #define $seed  $_[0]
01228    
01229    if (0) {
01230 //       print "seed: \"$seed\"\n";
01231    }
01232    if (exists ($globe::xtag_struct{$seed}{child})) {
01233       //  means we need to trace down into it
01234       if (1) {
01235 //          print "section:$globe::xtag_struct{$seed}{name}\n";
01236       }
01237       foreach $child (@{$globe::xtag_struct{$seed}{child}}) { 
01238 //          //  print "name:  \"$hname\"\n";
01239          &rec_trace_struct ($child);
01240       }
01241    } else {
01242       //  means we're at a child level with no children
01243 //       //  can print out and return
01244       if (1) {
01245 //          print "final child: \"$globe::xtag_struct{$seed}{name}\" with  \"$globe::xtag_struct{$seed}{parent}\" \n";
01246       }
01247    }
01248 } //  rec_trace_struct
01249 
01250 //#############################################################################
01251 /** @brief Steps through the xtag_struct to create a simple linear array
01252  ** with the topic order.
01253  ** 
01254  ** @param seed Starting point in the structure.
01255  ** @param level Starting level in the structure. Used to control indenting in
01256  ** the output.
01257  **
01258  ** @retval globe::topic_order is an array with just the hash keys into the
01259  ** xtag_struct in the order that they should appear.
01260  ** 
01261  ** The topic_order array can be more convenient for various operations, such
01262 //  ** as finding the previous/next elements and for printing out the output. It
01263  ** is simplier and easier to step through than the recursive algorithms.
01264  ** 
01265  ** @lim This is called recursively.
01266  **/
01267 // #############################################################################
01268 int find_topic_order  ( ) {
01269    #define $seed  $_[0]
01270    #define $level  $_[1]
01271    
01272    #define $html_name  $seed
01273    $html_name =~ s/^$globe::struct_start//;
01274    $html_name =~ s/^\-//;
01275    $html_name .= ".html";
01276    
01277    if (0) {
01278 //       print "hola seed: \"$seed\"\n";
01279 //       //  print "hola html: \"$html_name\"\n";
01280    }
01281    push (@globe::topic_order, $seed);
01282    if (exists ($globe::xtag_struct{$seed}{child})) {
01283       //  means we need to trace down into it
01284       if ($globe::struct_start !~ /$seed/) {
01285          if (0) {
01286 //             print "$globe::xtag_struct{$seed}{name}\n";
01287          }
01288          $level++;
01289       }
01290       
01291       foreach $child (@{$globe::xtag_struct{$seed}{child}}) { 
01292          &find_topic_order ($child, $level);
01293       }
01294       if ($globe::struct_start !~ /$seed/) {
01295          $level--;
01296       }
01297    } else {
01298       //  means we're at a child level with no children
01299 //       //  can print out and return
01300       
01301       if ($globe::struct_start !~ /$seed/) {
01302          if (0) {
01303 //             print "$globe::xtag_struct{$seed}{name}\n";
01304          } //  if (1)
01305       }
01306    }
01307    return (1); 
01308 } //  find_topic_order
01309 
01310 
01311 
01312 //#############################################################################
01313 /** @brief Creates the HTML descriptions for the hash elements.
01314  ** 
01315  ** @param None.
01316  **
01317  ** @retval Creates xtag_struct{$name}{desc_html} which is just a copy
01318  ** of the xtag_struct{$name}{comment_full}.
01319  ** 
01320  ** This doesn't do much, but could in the future.
01321  **/
01322 //  08/01/2002 This needs to be completed properly
01323 //#############################################################################
01324 int generate_desc_html  ( ) {
01325    if (1) {
01326       //  08/01/2002 This assumes that the comments in the INI file are
01327       //  already HTML tagged.
01328       for ($i=0; $i <= $// globe::topic_order; $i++) {
01329          $globe::xtag_struct{$globe::topic_order[$i]}{desc_html} = $globe::xtag_struct{$globe::topic_order[$i]}{comment_full};
01330 //          //  print "$i:$globe::topic_order[$i]\n";
01331       }
01332    }
01333    return (1);
01334 } //  generate_desc_html
01335 
01336 
01337 //#############################################################################
01338 // 08/06/2002 
01339 /** @brief Removes elements from the HTML in the comments that we don't
01340  ** want anymore.
01341  **
01342  ** @param zap_it_string The section containing things to eliminate.
01343  ** 
01344  ** @return The same string but with elements removed.
01345  ** 
01346  ** @lim This uses the $globe::m_info{_array_html_zap}[] array which gets
01347  ** defined by the master file read in. A trick is to use a different master
01348  ** file for creating the initial HTML than the one used by voyant_nav.pl
01349  ** to get a standard look and feel. More things can be uniquely zapped.
01350  **
01351  **/
01352 // #############################################################################
01353 int comment_zap  ( ) {
01354    #define $zap_it_string  $_[0]
01355    #define $debug_all  0  //  turns on/off debug for this whole routine
01356    
01357    if ((0) && ($debug_all)) {
01358 //       print "cz:HTML zapping ===\n";
01359 //       //  print "$piece\n";
01360       for ($i=0; $i <= $// {$globe::m_info{_array_html_zap}}; $i++){
01361 //          print "cz:$i $globe::m_info{_array_html_zap}[$i]\n";
01362       }
01363    }
01364    if ($debug_all) {
01365 //       print "cz:BEFORE:$zap_it_string\n";
01366    }
01367    
01368    // ################################
01369    //  Remove certain specified HTML tags
01370    // ################################
01371    if (($// {$globe::m_info{_array_html_zap}} == 0) || ($globe::m_info{_array_html_zap}[0] =~ /none/)){
01372       //  Do nothing
01373       if ($debug_all) {
01374 //          print "NO ZAP: \"$zap_it_string\" has no tags to zap.\n";
01375       }
01376    } else {
01377       //  Remove the tags in question
01378       for ($i=0; $i<= $// {$globe::m_info{_array_html_zap}}; $i++){
01379          //  Determine start and Stop tags
01380          @zap_tag = split ( /\,/, $globe::m_info{_array_html_zap}[$i]);
01381          //  clean up tag
01382          for ($j=0; $j <= $// zap_tag; $j++){
01383             $zap_tag[$j] =~ s/^[\s]*\"//;
01384             $zap_tag[$j] =~ s/\"[\s]*$//;
01385             if ((0) && ($debug_all)) {
01386 //                print "cz:Zap this =$zap_tag[$j]\n";
01387             }
01388          }
01389          $t_cnt=0;
01390          while ($zap_it_string =~ /$zap_tag[0]/i){  //  case insensitive test
01391              $t_cnt++;
01392              if ((1) && ($debug_all)) {
01393 //                 print "cz:$t_cnt: Removing everything between \"$zap_tag[0]\" and \"$zap_tag[1]\"\n";
01394              }
01395              //  First tag part A
01396              @pre_chunks = split ( /$zap_tag[0]/, $zap_it_string, 2);
01397              //  First tag part B
01398              @post_chunks = split ( /$zap_tag[1]/, $pre_chunks[1], 2);
01399              if ($// zap_tag > 1){
01400                 //  Second tag
01401                 //  Hit the first occurrence of the ending tag
01402                 $post_chunks[1] =~ s/$zap_tag[2]//i; //  do it only once, case insensitive
01403              }
01404              //  rebuild
01405              $zap_it_string = join ("", $pre_chunks[0], $post_chunks[1]);
01406          } //  while it still is infested with the tag
01407       } //  for all zap tags
01408       if ((0) && ($debug_all)) {
01409 //          print "cz:$zap_it_string was tested for tags to zap.\n";
01410       }
01411    } //  if zap tags to remove
01412    // undef(@pre_chunks);
01413    // undef(@post_chunks);
01414    // ################################
01415    
01416    if ($debug_all) {
01417 //       print "cz:AFTER:$zap_it_string\n";
01418    }
01419    
01420    return ($zap_it_string);
01421 } //  comment_zap
01422 
01423 //#############################################################################
01424 //#############################################################################
01425 int check_tbd  ( ) {
01426 
01427    if ((1) || ($debug_verbose)) { //  debug
01428 //       print "Topic ordering\n=====\n";
01429    } //  debug
01430    for ($i=0; $i <= $// globe::topic_order; $i++) {
01431       if ((0) || ($debug_verbose)) { //  debug
01432 //          print "$i:$globe::topic_order[$i]\n";
01433       }
01434       $hname = $globe::topic_order[$i];
01435       // ###
01436       //  Set up default error text
01437       // ###
01438       #define $ttt_error_out  "_TBD_: "
01439       $ttt_error_out .= "\"$globe::xtag_struct{$globe::xtag_struct{$hname}{parent}}{name}\.";
01440       $ttt_error_out .= "$globe::xtag_struct{$hname}{name}\" ";
01441       $ttt_error_out .= "is not commented.";
01442       // ###
01443       if (exists ($globe::xtag_struct{$hname}{comment})) {
01444         //  A single comment is better than nothing
01445         $ttt_out = $globe::xtag_struct{$hname}{desc_html};
01446         //  Strip out all html.
01447         while ($ttt_out =~ /</) {
01448             ($before, $piece, $after) = &globe::get_tag_chunk( $ttt_out,
01449                   "<", ">", 0);
01450             $ttt_out = join ("", $before, $after); 
01451          }
01452          $ttt_out =~ s/\r//g;  //  strip out Windows
01453          $ttt_out =~ s/\n//g;  //  strip out carriage return
01454          $ttt_out =~ s/^[\s]+//;  //  strip out leading white space
01455          $ttt_out =~ s/[\s]+$//;  //  strip out trailing white space
01456             
01457          //  If what is leftover is more than a word, we might have a true description.
01458          if ((0) || ($debug_verbose)) { //  debug
01459 //             print "ec:\"$globe::xtag_struct{$hname}{name}\" with:\n$ttt_out\n=====\n";
01460          }
01461          if ($ttt_out =~ /[\w]+/) {
01462             //  Means that we have some information and its probably documented.
01463             //  No further action required.
01464             @ttt_chunk = split (/[\s]+/, $ttt_out);
01465             if ($// ttt_chunk < 7) {
01466                //  Overwrite the default definition
01467                $ttt_error_out = "_TBD_: ";
01468                $ttt_error_out .= "$globe::xtag_struct{$globe::xtag_struct{$hname}{parent}}{name}\.";
01469                $ttt_error_out .= "$globe::xtag_struct{$hname}{name} ";
01470                $ttt_error_out .= "is weak \($// ttt_chunk words\) and probably not commented.";
01471             } else {
01472                // ###
01473                //  The only case where we feel it is adequately documented.
01474                // ###
01475                $ttt_error_out = "";
01476             }
01477          } else {
01478             //  Means that we have too little information.
01479             //  Use the default definition for $ttt_error_out
01480          }
01481       }
01482       if ($ttt_error_out) {
01483          if ($debug_verbose) {
01484 //             print "$ttt_error_out\n";
01485          }
01486          push (@file_errors, "$ttt_error_out");
01487       }
01488       // undef ($ttt_out);
01489       // undef ($ttt_error_out);
01490    }  //  for loop over array
01491    if ((0) || ($debug_verbose)) { //  debug
01492 //       print "Finished the cheap error checking routines.\n";
01493    } //  debug
01494 } //  check_tbd
01495 
01496 
01497 //#############################################################################
01498 /** @brief Steps through the topic_order array of keys into the hash
01499  ** xtag_struct to find the previous and next html topics.
01500  ** 
01501  ** @param None
01502  **
01503  ** @retval xtag_struct has elements filled in for:
01504  ** 
01505  **       $globe::xtag_struct{$name}{prev} = previous html file
01506  **       $globe::xtag_struct{$name}{next} = next html file
01507  **       $globe::xtag_struct{$name}{html} = associated html file
01508  ** 
01509  ** @globe::topic_order has the proper ordering of topics and represents
01510  ** the keys into the $globe::xtag_struct
01511  **/
01512 // #############################################################################
01513 int topic_prev_next  ( ) {
01514    #define $prev  "_TBD_"
01515    #define $next  "_TBD_"
01516    
01517    #define $html_name  "_TBD_"
01518 
01519    if (0) {
01520 //       print "topic_prev_next\n=====\n";
01521       for ($i=0; $i <= $// globe::topic_order; $i++) {
01522 //          print "$i:$globe::topic_order[$i]\n";
01523       }
01524    }
01525    // ####
01526    //  Assign names to the topics
01527    // ####
01528    for ($i=0; $i <= $// globe::topic_order; $i++) {
01529       $html_name = $globe::topic_order[$i];
01530       $html_name =~ s/^$globe::struct_start/$globe::start_name/;
01531       $html_name =~ s/^\-//;
01532       $html_name .= ".html";
01533 //       //  print "$i:$globe::topic_order[$i]\n";
01534 //       //  print "$i:$html_name\n";
01535       $globe::xtag_struct{$globe::topic_order[$i]}{html} = $html_name;
01536    }
01537    
01538    // ####
01539    //  Assign next file pointers to the topics
01540    //  go 1st to second from last
01541    // ####
01542    //  Avoid the seed value
01543    //  for ($i=1; $i < $#globe::topic_order; $i++) {
01544    for ($i=0; $i < $// globe::topic_order; $i++) {
01545       $globe::xtag_struct{$globe::topic_order[$i]}{next} = $globe::xtag_struct{$globe::topic_order[$i+1]}{html};
01546 //       //  print "$i:$globe::topic_order[$i]\n";
01547    }
01548    // ####
01549    //  Assign prev file pointers to the topics
01550    //  go 2nd to very last
01551    // ####
01552    //  Avoid the seed value
01553    //  for ($i=2; $i <= $#globe::topic_order; $i++) {
01554    for ($i=1; $i <= $// globe::topic_order; $i++) {
01555       $globe::xtag_struct{$globe::topic_order[$i]}{prev} = $globe::xtag_struct{$globe::topic_order[$i-1]}{html};
01556 //       //  print "$i:$globe::topic_order[$i]\n";
01557    }
01558    // ####
01559    //  Fix first and last previous/next pointers
01560    //  08/01/2002 You'll need to fix this if overview topics are created.
01561    // ####
01562    //  Avoid the seed value
01563    $globe::xtag_struct{$globe::topic_order[0]}{prev} = $globe::xtag_struct{$globe::topic_order[$// globe::topic_order]}{html};
01564    if (0) {
01565 //       print "Tweak to 1 prev: $globe::xtag_struct{$globe::topic_order[1]}{prev}\n";
01566    }
01567    $globe::xtag_struct{$globe::topic_order[$// globe::topic_order]}{next} = $globe::xtag_struct{$globe::topic_order[0]}{html};
01568    if (0) {
01569 //       print "Tweak to 1 next: $globe::xtag_struct{$globe::topic_order[$// globe::topic_order]}{next}\n";
01570    }
01571 
01572    // ####
01573    //  Check on assignment
01574    // ####
01575    if (0) {
01576       //  Avoid the seed value
01577       for ($i=0; $i <= $// globe::topic_order; $i++) {
01578 //          print "$i:<\t$globe::xtag_struct{$globe::topic_order[$i]}{prev}\n";
01579 //          print "$i:$globe::xtag_struct{$globe::topic_order[$i]}{html}\n";
01580 //          print "$i:>\t$globe::xtag_struct{$globe::topic_order[$i]}{next}\n";
01581       }  
01582       for ($i=0; $i <= 2; $i++) {
01583 //          print "$i:<\t$globe::xtag_struct{$globe::topic_order[$i]}{prev}\n";
01584 //          print "$i:$globe::xtag_struct{$globe::topic_order[$i]}{html}\n";
01585 //          print "$i:>\t$globe::xtag_struct{$globe::topic_order[$i]}{next}\n";
01586       }  
01587    }
01588    return (1);
01589 } //  topic_prev_next
01590 
01591 
01592 
01593 
01594 
01595 //#############################################################################
01596 /** @brief Creates an HTML file for each element in the topic_order array.
01597  **
01598  ** @param None.
01599  **
01600  ** @return Creates an HTML file in the globe::path directory.
01601  ** 
01602  ** This steps through each element in the topic_order array, which is a
01603  ** sorted list of keys into the xtag_struct hash.
01604  ** 
01605  ** Using the key into the hash, it creates an HTML topic based on information
01606  ** from the hash for the item.
01607  ** 
01608  ** Only the first topic -- the top-level array element and starting point
01609  ** for any recursive seed operation into the hash -- has something unique
01610  ** given for it. Instead of nothing, it produces a generic INI sample that
01611  ** is fully hyperlinked and index-marked. This way, users can see the elements
01612  ** in context.
01613  **/
01614 // # @param file_out The name of the file to output.
01615 //#       $globe::xtag_struct{$hname}{name} = actual item name
01616 //#       $globe::xtag_struct{$hname}{parent} = owning section
01617 //#       $globe::xtag_struct{$hname}{child}[] = array of associated children
01618 //#       $globe::xtag_struct{$hname}{comment} = comment flag
01619 //#       $globe::xtag_struct{$hname}{comment_full} = full comments w/o tags
01620 //#       $globe::xtag_struct{$hname}{desc_html} = description in html
01621 //#       $globe::xtag_struct{$hname}{desc_man} = description in man
01622 //#
01623 //#       $name = name associated with number
01624 //#       $globe::xtag_struct{$name}{prev} = previous html file
01625 //#       $globe::xtag_struct{$name}{next} = next html file
01626 //#       $globe::xtag_struct{$name}{html} = associated html file
01627 /**
01628  ** @ingroup tp_xhelp
01629  **/
01630 // #############################################################################
01631 int write_output_html  ( ) {
01632 
01633    $def_type = "variable";
01634    $total = $// globe::topic_order;
01635 
01636    OHTM: for ($i=0; $i <= $// globe::topic_order; $i++) {
01637       //  $globe::xtag_struct{$globe::topic_order[$i]}{prev}
01638       $name = $globe::topic_order[$i];
01639       $file_out = "$globe::path";
01640       $file_out .= "$globe::xtag_struct{$name}{html}";
01641 
01642       unless (open ( OUT_FILE, ">$file_out")) {
01643          push (@file_errors, "3 Cannot open file \"$file_out\"\n");
01644 //          print "3 Cannot open file \"$file_out\"\n";
01645          next OHTM;
01646       }
01647       if (1) {
01648 //          print "Creating $file_out...\n";
01649       }
01650 //       print (OUT_FILE "<html>\n <head>\r\n");
01651 //       //  print (OUT_FILE "<title>$name</title>\r\n");
01652 //       print (OUT_FILE "$globe::m_info{header}\r\n");
01653 
01654 //       print (OUT_FILE "$globe::m_define{$def_type}[0] ");
01655       
01656 //       print (OUT_FILE "$globe::m_var{define}{prev}$globe::xtag_struct{$name}{prev}");
01657 //       print (OUT_FILE "$globe::m_var{define}{next}$globe::xtag_struct{$name}{next}");
01658       if (0) {
01659 //          print "$globe::m_var{define}{prev}$globe::xtag_struct{$name}{prev}";
01660 //          print "$globe::m_var{define}{next}$globe::xtag_struct{$name}{next}\n";
01661 
01662       }
01663       if ($i == 0) {
01664 //          print (OUT_FILE "$globe::m_var{define}{firstlast}1\// 0");
01665       } elsif ($i == $total) {
01666 //          print (OUT_FILE "$globe::m_var{define}{firstlast}0\// 1");
01667       } else {
01668 //          print (OUT_FILE "$globe::m_var{define}{firstlast}0\// 0");
01669       }
01670       
01671 //       print (OUT_FILE "$globe::m_define{$def_type}[1] \r\n");
01672 //       print (OUT_FILE "</head>\n<body>\r\n");
01673       // ####
01674       //  Fix up the navigation
01675       // ####
01676       $nav_bars = $globe::m_info{nav_common};
01677       $nav_bars .= $globe::m_info{nav_book};
01678       $nav_bars =~ s/$globe::m_var{define}{prev}/$globe::xtag_struct{$name}{prev}/;
01679       $nav_bars =~ s/$globe::m_var{define}{next}/$globe::xtag_struct{$name}{next}/;
01680       $out_string = $nav_bars;
01681       $out_string .= "<h1>$globe::xtag_struct{$name}{name}</h1>\r\n";
01682       $trace_parent = &parent_trace ($name, 1);  //  the 1 says to do html
01683       $out_string .= "<p class=\"TitleChapterTOC\">Section: $trace_parent</p>\r\n";
01684       //  $out_string .= "<p class=\"TitleChapter\">Section: $trace_parent</p>\r\n";
01685       if (exists ($globe::xtag_struct{$name}{child})) {
01686          //  means that this is a section
01687          $out_string .= "<p class=\"TitleChapterTOC\">Syntax:</p>\r\n"; 
01688          //  $out_string .= "<p class=\"TitleChapter\">Syntax:</p>\r\n"; 
01689          $out_string .= "<p class=\"Head1TOC\">$globe::xtag_struct{$name}{name}</p>\r\n";
01690          //  $out_string .= "<p class=\"Head1\">$globe::xtag_struct{$name}{name}</p>\n";
01691          $out_string .= "<p class=\"TitleChapterTOC\">Items:</p>\n";
01692          //  $out_string .= "<p class=\"TitleChapter\">Items:</p>\n";
01693          $out_string .= "<ul>\n";
01694          for ($j=0; $j <= $// {$globe::xtag_struct{$name}{child}}; $j++) {
01695             $child = $globe::xtag_struct{$name}{child}[$j];
01696             $child_name = $globe::xtag_struct{$child}{name};
01697             $child_html = $globe::xtag_struct{$child}{html};
01698             $out_string .= "<li>";
01699             $out_string .= "<a href=\"$child_html\">";
01700             $out_string .= "$child_name";
01701             $out_string .= "</a>";
01702             $out_string .= "</li>\n";
01703          }
01704          $out_string .= "</ul>\n";
01705       } else {
01706          //  means that this is a child
01707          $out_string .= "<p class=\"TitleChapterTOC\">Syntax:</p>\n"; 
01708          //  $out_string .= "<p class=\"TitleChapter\">Syntax:</p>\n"; 
01709          $out_string .= "<p class=\"Head1TOC\">$globe::xtag_struct{$name}{name}";
01710          //  $out_string .= "<p class=\"Head1\">$globe::xtag_struct{$name}{name}";
01711          if (exists ($globe::xtag_struct{$name}{default})) {
01712             $out_string .= " $globe::xtag_struct{$name}{plus}\=";
01713             $out_string .= " $globe::xtag_struct{$name}{default}";
01714          }
01715          $out_string .= "</p>\n";
01716       }
01717       $out_string .= "<p class=\"TitleChapterTOC\">Details:</p>\n"; 
01718       //  $out_string .= "<p class=\"TitleChapter\">Details:</p>\n"; 
01719       if (exists ($globe::xtag_struct{$name}{desc_html})) {
01720          //  $out_string .= "<p class=\"Head1TOC\">$globe::xtag_struct{$name}{desc_html}</p>\n";
01721          //  $out_string .= "<p class=\"Head1\">$globe::xtag_struct{$name}{desc_html}</p>\n";
01722          $out_string .= "<p>$globe::xtag_struct{$name}{desc_html}</p>\n";
01723       } else {
01724          //  $out_string .= "<p class=\"Head1TOC\">No Information.</p>\n";
01725          //  $out_string .= "<p class=\"Head1\">No Information.</p>\n";
01726          $out_string .= "<p>No Information available.</p>\n";
01727       }
01728 
01729       $nav_bars = "$globe::m_info{nav_book}$globe::m_info{footer}";
01730       $nav_bars =~ s/$globe::m_var{define}{prev}/$globe::xtag_struct{$name}{prev}/;
01731       $nav_bars =~ s/$globe::m_var{define}{next}/$globe::xtag_struct{$name}{next}/;
01732       $out_string .= "$nav_bars\n";
01733 //       print (OUT_FILE "$out_string");
01734 //       print (OUT_FILE "</body>\n</html>\r\n");
01735 //       close (OUT_FILE);
01736    } //  $#globe::topic_order
01737    
01738    // ##############################################
01739    // ####
01740    //  Create a unique first topic
01741    // ####
01742    if (1) { //  unique first topic
01743       $i = 0;
01744       
01745       $name = $globe::topic_order[$i];
01746       $file_out = "$globe::path";
01747       $file_out .= "$globe::xtag_struct{$name}{html}";
01748 
01749       unless (open ( OUT_FILE, ">$file_out")) {
01750          push (@file_errors, "4 Cannot open file \"$file_out\"\n");
01751 //          print "4 Cannot open file \"$file_out\"\n";
01752          next OHTM;
01753       }
01754       if (1) {
01755 //          print "Creating $file_out...\n";
01756       }
01757 //       print (OUT_FILE "<html>\n <head>\r\n");
01758 //       //  print (OUT_FILE "<title>$name</title>\r\n");
01759 //       print (OUT_FILE "$globe::m_info{header}\r\n");
01760 
01761 //       print (OUT_FILE "$globe::m_define{$def_type}[0] ");
01762       
01763 //       print (OUT_FILE "$globe::m_var{define}{prev}$globe::xtag_struct{$name}{prev}");
01764 //       print (OUT_FILE "$globe::m_var{define}{next}$globe::xtag_struct{$name}{next}");
01765       if (0) {
01766 //          print "$globe::m_var{define}{prev}$globe::xtag_struct{$name}{prev}";
01767 //          print "$globe::m_var{define}{next}$globe::xtag_struct{$name}{next}\n";
01768 
01769       }
01770       if ($i == 0) {
01771 //          print (OUT_FILE "$globe::m_var{define}{firstlast}1\// 0");
01772       } elsif ($i == $total - 1) {
01773 //          print (OUT_FILE "$globe::m_var{define}{firstlast}0\// 1");
01774       } else {
01775 //          print (OUT_FILE "$globe::m_var{define}{firstlast}0\// 0");
01776       }
01777       
01778 //       print (OUT_FILE "$globe::m_define{$def_type}[1] \r\n");
01779 //       print (OUT_FILE "</head>\n<body>\r\n");
01780       // ####
01781       //  Fix up the navigation
01782       //  GCM still to do... with previous and next...
01783       // ####
01784       $nav_bars = $globe::m_info{nav_common};
01785       $nav_bars .= $globe::m_info{nav_book};
01786       $nav_bars =~ s/$globe::m_var{define}{prev}/$globe::xtag_struct{$name}{prev}/;
01787       $nav_bars =~ s/$globe::m_var{define}{next}/$globe::xtag_struct{$name}{next}/;
01788       $out_string = $nav_bars;
01789       $out_string .= "<h1>$globe::xtag_struct{$name}{name}</h1>\r\n";
01790       $out_string .= "<p align=\"center\" size=\"small\"><a href=\"\// overview\">\{Overview is below.\}</a></p>\r\n";
01791       
01792       // ####
01793       //  Go and recursively build a structure based on what is known.
01794       // ####
01795       &rec_example_topic ($globe::struct_start, 0);
01796 
01797       $out_string .= "<p></p><p></p><p></p>\r\n";
01798       
01799       // ####
01800       //  Add more information based on what is also in the data base.
01801       //  The first topic can't be as easily hyperlinked using the normal
01802       //  <initag name""> targets. However, we can fake it out by defining
01803       //  <initag name"$globe::struct_start"> in our file and tacking this
01804       //  information to the bottom of what we created.
01805       // ####
01806 
01807 
01808       $out_string .= "<a name=\"overview\"></a>\r\n";
01809       foreach $k (@{$globe::tag_mess{name}{$globe::struct_start}}){
01810          $tttemp_file = $globe::tag_mess{name}{$globe::struct_start}[$k];
01811          $out_string .= "$globe::tag_mess{file}{$tttemp_file}{$globe::struct_start}\n";
01812          if (0) {
01813 //             print "woh:file:$tttemp_file\n";
01814 //             print "woh:content:$globe::tag_mess{file}{$tttemp_file}{$globe::struct_start}\n"; 
01815          }
01816       }
01817       if (0) {
01818 //          print "burp\n";
01819 //          exit(1);
01820       }
01821 
01822       $nav_bars = "$globe::m_info{nav_book}$globe::m_info{footer}";
01823       $nav_bars =~ s/$globe::m_var{define}{prev}/$globe::xtag_struct{$name}{prev}/;
01824       $nav_bars =~ s/$globe::m_var{define}{next}/$globe::xtag_struct{$name}{next}/;
01825       $out_string .= "$nav_bars\r\n";
01826 //       print (OUT_FILE "$out_string");
01827 //       print (OUT_FILE "</body>\n</html>\r\n");
01828 //       close (OUT_FILE);
01829       
01830       // ###
01831       //  Cheap trick for the man output for the first topic
01832       // ###
01833       $globe::xtag_struct{$name}{desc_html} = $out_string;
01834    } //  unique first topic
01835 
01836 } //  write_output_html
01837 
01838 
01839 //#############################################################################
01840 /** @brief Creates an example/sample INI file based on what is known.
01841  ** 
01842  ** @param None.
01843  **
01844  ** @return Creates a file that ultimately is a sample INI file and
01845  ** is fully commented. The file is tagged appropriately with XML tags. 
01846  ** When the output_html flag is set, it will output two files:
01847  ** one is the sample INI file with only tags;
01848  ** the other is the corresponding HTML file with associated comments.
01849  ** In either event, these files can be round-tripped through this tool
01850  ** and produce equivalent output.
01851  ** 
01852  ** The purpose of this routine is to provide a marked-up starting point
01853  ** for generating a fully commented/documented INI file. It probably won't
01854  ** be used much. Later, it should end up being almost identical to the 
01855  ** original.
01856  ** 
01857  ** @lim Calls another routine that ends up calling itself recursively.
01858  **/
01859 // #############################################################################
01860 int write_sample  ( ) {
01861    #define $file_out
01862    #define $file_out2
01863    #define $file_out_tag
01864    #define $file_out_doc
01865    #define $out_string  ""
01866    #define $out_head  ""
01867    #define $output_html  0  //  Will output a HTML.
01868    #define $outtxt  ""
01869    #define $outhtm  ""
01870    #define $debug_ws  0
01871 
01872 
01873    // ####
01874    //  Create a unique first topic
01875    // ####
01876    if (1) { //  unique first topic
01877       $i = 0;
01878       
01879       $name = $globe::topic_order[$i];
01880       $file_out = "$globe::path";
01881       $file_out .= "$globe::xtag_struct{$name}{html}";
01882       $file_out =~ s/\.html/\_sample\.txt/;
01883       $file_out2 = $file_out;
01884       $file_out_tag = $file_out;
01885       $file_out_doc = $file_out;
01886       $file_out2 =~ s/\.txt/\._html/;  //  so it will almost be what we want.
01887       $file_out_tag =~ s/\_sample/\_sample\_tag/;  //  just the tags
01888       $file_out_doc =~ s/\_sample/\_sample\_doc/;  //  just the doc
01889 
01890       // ####
01891       //  Cheap-o error checking; not completely valid,
01892       //  but will save at least one file from getting overwritten.
01893       // ####
01894       unless (open ( OUT_FILE, ">$file_out")) {
01895          push (@file_errors, "5 Cannot open file \"$file_out\"\n");
01896 //          print "5a Cannot open file \"$file_out\"\n";
01897          return (0);
01898       }
01899       unless (open ( OUT_FILE2, ">$file_out2")) {
01900          push (@file_errors, "5 Cannot open file \"$file_out2\"\n");
01901 //          print "5b Cannot open file \"$file_out2\"\n";
01902          return (0);
01903       }
01904       unless (open ( OUT_FILE_TAG, ">$file_out_tag")) {
01905          push (@file_errors, "5 Cannot open file \"$file_out_tag\"\n");
01906 //          print "5c Cannot open file \"$file_out_tag\"\n";
01907          return (0);
01908       }
01909       unless (open ( OUT_FILE_DOC, ">$file_out_doc")) {
01910          push (@file_errors, "5 Cannot open file \"$file_out_doc\"\n");
01911 //          print "5d Cannot open file \"$file_out_doc\"\n";
01912          return (0);
01913       }
01914       if (1) {
01915 //          print "Creating $file_out...\n";
01916          if ($output_html) {
01917 //             print "Creating $file_out2...\n";
01918          }
01919       }
01920       &rec_sample ($globe::struct_start, 0, $output_html);
01921       $outtxt = "\/\/\/\/\/\/\/\/\/\/\r\n";
01922       $outtxt .= "\/\/ This is a commented INI file. \r\n";
01923       $outtxt .= "\/\/ Follow XML tag references to find comments. \r\n";
01924       $outtxt .= "\/\/\/\/\/\/\/\/\/\/\r\n";
01925       $outtxt .= $out_string;
01926 //       print (OUT_FILE_TAG $out_string);
01927       
01928       // ####
01929       //  This will overwrite $out_head with more complete information
01930       //  as it was originally.
01931       // ####
01932       foreach $tag (sort keys %{$globe::tag_mess{name}}) {
01933          if ($debug_ws) {
01934 //             print "ws:$tag\n";
01935          }
01936          foreach $i (@{$globe::tag_mess{name}{$tag}}){
01937             if ((0) && ($debug_ws)) {
01938 //                print "ws:\"$tag\":$globe::tag_mess{name}{$tag}[$i]\n";
01939             }
01940             $file = $globe::tag_mess{name}{$tag}[$i];
01941             if ($debug_ws) {
01942 //                //  print this is our information
01943 //                print "\"$file\":\"$tag\":\n$globe::tag_mess{file}{$file}{$tag}\n";
01944             }
01945             if ($output_html) {
01946                $out_head .= "<p class=\"Head1\">$tag</p>\r\n";
01947                $out_head .= "<$tag_xml name=\"";
01948             } else {
01949                $out_head .= "\/\/ <$tag_xml name=\"";
01950             }
01951             $out_head .= "$tag";
01952             //  $out_head .= "\">\r\n";
01953             $out_head .= "\">";
01954             //  This is the orginal comment.
01955             $ttt_html = $globe::tag_mess{file}{$file}{$tag};
01956             $ttt_html =~ s/\r//g; //  get rid of all windows line feeds
01957             if ($output_html) {
01958                $ttt_html =~ s/\n/\r\n/g; //  replace all returns with something for windows
01959             } else { 
01960                $ttt_html =~ s/\n/\r\n\/\/ /g; //  replace all returns with something for windows
01961             }
01962          
01963             //  $out_head .= "\/\/ $ttt_html";
01964             $out_head .= "$ttt_html";
01965             $out_head .= "</$tag_xml>\r\n\r\n";
01966          }
01967       }
01968 //       print (OUT_FILE_DOC $out_head);
01969 
01970       // ######
01971       if ($output_html) {
01972          $outhtm = "<html>\r\n";
01973          $outhtm .= "<!-- begin voy_header -->\r\n";
01974          $outhtm .= "   <meta http-equiv=\"Content-Type\" content=\"text/html;charset=iso-8859-1\">\r\n";
01975          $outhtm .= "   <title>$globe::xtag_struct{$name}{name}</title>\r\n";
01976          $outhtm .= "   <link rel=\"stylesheet\" href=\"voyant_fm.css\" type=\"text/css\">\r\n";
01977          $outhtm .= "   <body link=\"// 0000ff\" alink=\"#CC0000\" vlink=\"#0000ff\">\r\n";
01978          $outhtm .= "<!-- end voy_header -->\r\n";
01979          $outhtm .= "<\/head>\r\n";
01980          $outhtm .= "<body>\r\n";
01981       } else {
01982          $outtxt .= "\r\n\/\/\/\/\/\/\/\/\/\/\r\n";
01983          $outtxt .= "\/\/ HTML comments to the INI file entries.\r\n";
01984          $outtxt .= "\/\/\/\/\/\/\/\/\/\/\r\n";
01985       }
01986       if ($output_html) {
01987          $outhtm .= $out_head;
01988          $outhtm .= "<\/body>\r\n";
01989          $outhtm .= "<\/html>\r\n";
01990 //          print (OUT_FILE2 $outhtm);
01991       } else {
01992          $outtxt .= $out_head;
01993       }
01994 //       print (OUT_FILE $outtxt);
01995 
01996 //       close (OUT_FILE);
01997 //       close (OUT_FILE2);
01998 //       close (OUT_FILE_TAG);
01999 //       close (OUT_FILE_DOC);
02000    } //  unique first topic
02001 
02002 } //  write_sample
02003 
02004 
02005 //#############################################################################
02006 /** @brief Creates a sample INI without any HTML or hyperlinking.
02007  ** 
02008  ** @param seed Starting point in the structure.
02009  ** @param level Starting level in the structure. Used to control indenting in
02010  ** the output.
02011  **
02012  ** @retval out_string is a global variable holding the desired output. This
02013  ** output is XML tagged.
02014  ** 
02015  ** The purpose of this is to generate a sample INI file that can be used
02016  ** to copy information from other sources. It creates it with the information
02017  ** that it knows. It will require editing the first time. Later, this file
02018  ** won't be used except maybe to compare the input with the output.
02019  ** 
02020  ** @lim This is called recursively.
02021  ** This does not catch all xml tags that were used.
02022  **/
02023 //  &rec_sample ($globe::struct_start, 0);
02024 //#############################################################################
02025 int rec_sample  ( ) {
02026    #define $seed  $_[0]
02027    #define $level  $_[1]
02028    #define $html_out  $_[2]
02029    #define $debug_rs  0
02030    
02031    if (0) {
02032 //       print "seed: \"$seed\"\n";
02033    }
02034    // ####
02035    //  Creates a comment block to topic
02036    // ####
02037    $temp = $globe::xtag_struct{$seed}{name};
02038    $temp =~ s/\[//;
02039    $temp =~ s/\]//;
02040    if (exists ($globe::xtag_struct{$seed}{child})) {
02041       //  means we need to trace down into it
02042       if ($globe::struct_start !~ /$seed/) {
02043          for ($i=1; $i<=$level; $i++){
02044             $out_string .= "   ";
02045          }
02046          $out_string .= "$globe::xtag_struct{$seed}{name}";
02047          $out_string .= "   \/\/ ";
02048          if (exists ($globe::xtag_struct{$seed}{comment})) {
02049             $out_string .= "$globe::xtag_struct{$seed}{comment}";
02050          } else {
02051             $out_string .= "<$tag_xml target=\"";
02052             $out_string .= "$temp";
02053             $out_string .= "\">";
02054          }
02055          $out_string .= "\r\n";
02056          $level++;
02057       }
02058       foreach $child (@{$globe::xtag_struct{$seed}{child}}) { 
02059          &rec_sample ($child, $level, $html_out);
02060       }
02061       if ($globe::struct_start !~ /$seed/) {
02062          $level--;
02063          for ($i=1; $i<=$level; $i++){
02064             $out_string .= "   ";
02065          }
02066          $out_string .= "\[\]";
02067          $out_string .= "   \/\/ $globe::xtag_struct{$seed}{name}";
02068          $out_string .= "\r\n";
02069       }
02070    } else {
02071       //  means we're at a child level with no children
02072 //       //  can print out and return
02073       if ($globe::struct_start !~ /$seed/) {
02074          for ($i=1; $i<=$level; $i++){
02075             $out_string .= "   ";
02076          }
02077          // ####
02078          //  Puts in hyperlink to topic
02079          // ####
02080          if (exists ($globe::xtag_struct{$seed}{default})) {
02081             $out_string .= "$globe::xtag_struct{$seed}{name}";
02082             $out_string .= " $globe::xtag_struct{$seed}{plus}\=";
02083             $out_string .= " $globe::xtag_struct{$seed}{default}";
02084          } else {
02085             $out_string .= "$globe::xtag_struct{$seed}{name}";
02086          }
02087          $out_string .= "   \/\/ ";
02088          if (exists ($globe::xtag_struct{$seed}{comment})) {
02089             $out_string .= "$globe::xtag_struct{$seed}{comment}";
02090             if ($globe::xtag_struct{$seed}{comment} !~ /$tag_xml/) {
02091                //  Let's put in an empty tag anyway.
02092                $out_string .= "<$tag_xml target=\"";
02093                $out_string .= "$temp";
02094                $out_string .= "\">";
02095                //  08/07/2002 Add the name to the structure to be later output
02096                push (@{$globe::tag_mess{name}{$temp}}, $org_ini);
02097                $globe::tag_mess{file}{$org_ini}{$temp} .= "";
02098             }
02099          } else {
02100             $out_string .= "<$tag_xml target=\"";
02101             $out_string .= "$temp";
02102             $out_string .= "\">";
02103             //  08/07/2002 Add the name to the structure to be later output
02104             push (@{$globe::tag_mess{name}{$temp}}, $org_ini);
02105             $globe::tag_mess{file}{$org_ini}{$temp} .= "";
02106          }
02107          $out_string .= "\r\n";
02108          //  for when a section is defined but has no children.
02109          if ($globe::xtag_struct{$seed}{name} =~ /^\[/) {
02110             if ($globe::struct_start !~ /$seed/) {
02111                //  $level--;
02112                for ($i=1; $i<=$level; $i++){
02113                   $out_string .= "   ";
02114                }
02115                $out_string .= "\[\]";
02116                $out_string .= "   \/\/ $globe::xtag_struct{$seed}{name}";
02117                $out_string .= "\r\n";
02118             }
02119          } //  when section has no children
02120          
02121       }
02122    } 
02123 } //  rec_sample
02124 
02125 
02126 
02127 
02128 
02129 //#############################################################################
02130 /** @brief Creates man pages for each hash topic.
02131  ** 
02132  ** @param seed Starting point in the structure.
02133  **
02134  ** @return A file that represents the equivalent man information for a
02135  ** hash item.
02136  ** 
02137  ** The reason this is called recursively is that the topic order isn't
02138  ** important. Mostly that the man output is generated.
02139  ** 
02140  ** @lim This is called recursively.
02141  **/
02142 // #############################################################################
02143 int rec_write_man  ( ) {
02144    #define $seed  $_[0]
02145    #define $debug_rwm  0
02146    
02147    if ($debug_rwm) {
02148 //       print "rwm:seed: \"$seed\"\n";
02149    }
02150    &write_output_man($seed);
02151    if (exists ($globe::xtag_struct{$seed}{child})) {
02152       //  means we need to trace down into it
02153       if ($debug_rwm) {
02154 //          print "rwm:section:$globe::xtag_struct{$seed}{name}\n";
02155       }
02156       foreach $child (@{$globe::xtag_struct{$seed}{child}}) { 
02157 //          //  print "name:  \"$hname\"\n";
02158          &rec_write_man($child);
02159       }
02160    } else {
02161       //  means we're at a child level with no children
02162 //       //  can print out and return
02163       if ($debug_rwm) {
02164 //          print "rwm:final child: \"$globe::xtag_struct{$seed}{name}\" with  \"$globe::xtag_struct{$seed}{parent}\" \n";
02165       }
02166    }
02167 } //  rec_write_man
02168 
02169 //#############################################################################
02170 /** @fn int write_output_man
02171  ** @brief Formats and outputs a man page for the given key into the 
02172  ** the xtag_struct hash.
02173  ** 
02174  ** @param hname the key into the hash.
02175  **
02176  ** @retval out_string is a global variable holding the desired output. 
02177  **
02178  **
02179  ** @ingroup tp_xhelp
02180  **/
02181 // #       $globe::xtag_struct{$hname}{name} = actual item name
02182 //#       $globe::xtag_struct{$hnamee}{parent} = owning section
02183 //#       $globe::xtag_struct{$hname}{child}[] = array of associated children
02184 //#       $globe::xtag_struct{$hname}{comment} = comment flag
02185 //#       $globe::xtag_struct{$hname}{desc_html} = description in html
02186 //#       $globe::xtag_struct{$hname}{desc_man} = description in man
02187 //#       &write_output_man($globe::topic_order[$i], $mpath_out, $man_extension);
02188 //#############################################################################
02189 int write_output_man  ( ) {
02190    #define $hname  $_[0]
02191    #define $trace_parent
02192    #define $file_out
02193    #define $debug_wom  0
02194    
02195    if (0) { //  old
02196       $file_out = $globe::xtag_struct{$hname}{html};
02197       $file_out =~ s/\.html/\.$man_extension/;
02198       $file_out = "$mpath_out$file_out";
02199    }
02200    if (1) { //  new
02201       $file_out = $hname;
02202       @bogus = split (/\-/, $file_out);
02203       $file_out = pop (@bogus);   //  we only want the last element
02204       if ($file_out !~ /[\w]+/) {
02205          $file_out = $globe::xtag_struct{$hname}{html};
02206          $file_out =~ s/\.html//;
02207       }
02208       $temp_name = $file_out;
02209       $file_out .= "\.$man_extension";
02210       $file_out = "$mpath_out$file_out";
02211    }
02212 
02213    $trace_parent = &parent_trace ($hname, 0);  //  the 0 means no html output
02214 
02215    unless (open ( OUT_FILE, ">$file_out")) {
02216       push (@file_errors, "6 Cannot open file \"$file_out\"\n");
02217 //       print "6 Cannot open file \"$file_out\"\n";
02218       return (0);
02219    }
02220    if ((1) || ($debug_wom)) {
02221 //       print "Creating $file_out...\n";
02222 //       //  print "Again $date\n";
02223    }
02224 //    //  print (OUT_FILE ".TH \"$globe::xtag_struct{$hname}{name}\" $man_extension $date  \n");
02225 //    print (OUT_FILE ".TH \"$temp_name\" $man_extension $date  \n");
02226 //    //  print (OUT_FILE ".SH NAME\n$globe::xtag_struct{$hname}{name} \- ");
02227 //    print (OUT_FILE ".SH NAME\n$temp_name \- ");
02228    #define $temp  $globe::xtag_struct{$hname}{desc_man}
02229    if ((0) || ($debug_wom)) {
02230 //       print "=== getting one-liner:\n$temp\n====\n";
02231    }
02232    $temp =~ s/\.LP//g;  //  get rid of previous text.
02233    $temp =~ s/\n/ /g;  //  get rid of all carriage returns.
02234    @ttemp = split (/\.[\s]+/, $temp, 2);  //  $ttemp[0] is the one line summary.
02235    $ttemp[0] =~ s/\\fI//g;  //  get rid of previous text.
02236    $ttemp[0] =~ s/\\fB//g;  //  get rid of previous text.
02237    $ttemp[0] =~ s/\\fP//g;  //  get rid of previous text.
02238    $ttemp[0] =~ s/^[\s]+//;  //  get rid of previous text.
02239    if ((0) || ($debug_wom)) {
02240 //       print "=== one-liner:\n$ttemp[0].\n====\n";
02241    }
02242 //    print (OUT_FILE "$ttemp[0].\n\n");
02243    
02244 //    print (OUT_FILE ".SH SYNOPSIS\n\.B $trace_parent");
02245 
02246    if (exists ($globe::xtag_struct{$hname}{default})) {
02247 //        print (OUT_FILE " $globe::xtag_struct{$hname}{plus}\=");
02248 //        print (OUT_FILE " $globe::xtag_struct{$hname}{default}");
02249    }
02250 //    print (OUT_FILE "\n");
02251 
02252 //    print (OUT_FILE ".SH DESCRIPTION \n");
02253 //    print (OUT_FILE "$globe::xtag_struct{$hname}{desc_man}\n");
02254 //    //  print (OUT_FILE ".SH SEE ALSO \"$globe::xtag_struct{$globe::struct_start}{name}\"\n");
02255 //    print (OUT_FILE ".LP\n \n.LP\n$copyright\n");
02256 
02257 //    close (OUT_FILE);
02258    
02259 }
02260 
02261 //#############################################################################
02262 /** @brief Creates a MAN descriptions for the hash elements.
02263  ** 
02264  ** @param None.
02265  **
02266  ** @retval Creates xtag_struct{$name}{desc_man} which is just a copy
02267  ** of the xtag_struct{$name}{comment_full} without the HTML and marked up
02268  ** for MAN.
02269  ** 
02270  ** @lim This does not work yet. Needs to replace HTML with MAN mark-up.
02271  **/
02272 // #############################################################################
02273 int generate_desc_man  ( ) {
02274    #define $debug_gdm  0
02275    #define $b1  //  before html tag
02276    #define $a1  //  after html tag
02277    #define $p1  //  inbetween html < >
02278    #define $nada  "_n_a_d_a_"
02279    #define @start_tag      ("<br",    "<p",     "<font" ,  "<i",   "<b",  "<ul",  "<ol",  "<li",      "<" )
02280    #define @end_tag        ($nada,    "<\/p",   "<\/font", "</i",  "</b", "</ul", "</ol", "</li",     $nada)
02281    #define @replace_start  ("\.LP\n", "\.LP\n", "\\fI",    "\\fI", "\\fB", "",    "",     "\.HP\n\- ", "" )
02282    #define @replace_end    ("",       "",       "\\fR",    "\\fR", "\\fR", "",    "",     "\n\.RE\n", "" )
02283    #define $close_tag      ">"
02284    
02285    if ( ($// start_tag < $#end_tag) || ($#start_tag > $#end_tag) 
02286      || ($// start_tag < $#replace_start) || ($#start_tag > $#replace_start)
02287      || ($// start_tag < $#replace_end) || ($#start_tag > $#replace_end)) {
02288 //       print "gdm:start_tag, end_tag, and replace_tag arrays mush be of equal length.\n";
02289       foreach $tag (@start_tag) {
02290 //          print "start:$tag\n";
02291       }
02292       foreach $tag (@end_tag) {
02293 //          print "end:$tag\n";
02294       }
02295       foreach $tag (@replace_tag) {
02296 //          print "replace:$tag\n";
02297       }
02298       return (0);
02299    }
02300    
02301    for ($i=0; $i <= $// globe::topic_order; $i++) {
02302 //       //  print "$i:$globe::topic_order[$i]\n";
02303       $shrink = $globe::xtag_struct{$globe::topic_order[$i]}{comment_full};
02304       if ((1) && ($debug_gdm)) {
02305 //          print "IN>>>>\n$shrink";
02306       }
02307       for ($k=0; $k <= $// start_tag; $k++) {
02308          if ($shrink =~ /$start_tag[$k]/) {
02309             while ($shrink =~ /$start_tag[$k]/) {
02310                ($b1, $p1, $a1) = &globe::get_tag_chunk( $shrink, 
02311 //                     $start_tag[$k], $close_tag, 0);
02312                if ((0) && ($debug_gdm)) {
02313 //                   print "start_tag=>\"$start_tag[$k]\"\n";
02314 //                   print "close_tag=>\"$close_tag\"\n";
02315 //                   print "b1=>$b1\np1=>$p1\na1=>$a1\n";
02316                }
02317                if ($a1 =~ $end_tag[$k]) {
02318                   ($b2, $p2, $a2) = &globe::get_tag_chunk( $a1, 
02319 //                        $end_tag[$k], $close_tag, 0);
02320                   $shrink = join ("", $b1, $replace_start[$k], $b2, $replace_end[$k], $a2);
02321                } else {
02322                   $shrink = join ("", $b1, $replace_start[$k], $a1, $replace_end[$k]);
02323                }
02324                if ((0) && ($debug_gdm)) {
02325 //                   print "end_tag=>\"$end_tag[$k]\"\n";
02326 //                   print "close_tag=>\"$close_tag\"\n";
02327 //                   print "b2=>$b2\np2=>$p2\na2=>$a2\n";
02328                }
02329             }  //  while shrink
02330          }  //  if $start_tag
02331       } //  for $k $#start_tag
02332       for ($k=0; $k <= $// end_tag; $k++) {
02333          //  Make sure that there aren't any spurious end tags at that level
02334          if ($shrink =~ /$end_tag[$k]/) {
02335             while ($shrink =~ /$end_tag[$k]/) {
02336                ($b1, $p1, $a1) = &globe::get_tag_chunk( $shrink, 
02337 //                     $end_tag[$k], $close_tag, 0);
02338                $shrink = join ("", $b1, $a1);
02339             }  //  while shrink
02340          }  //  if $end_tag
02341       } //  for $k $#end_tag
02342       if ((1) && ($debug_gdm)) {
02343 //          print "\nOUT<<<<<\n$shrink\n";
02344       }
02345       $shrink =~ s/\r//g;  //  strip out Windows
02346       $globe::xtag_struct{$globe::topic_order[$i]}{desc_man} = $shrink;
02347    }
02348 //    //  exit(1);
02349    return (1);
02350 } //  generate_desc_man
02351 
02352 
02353 
02354 
02355 //#############################################################################
02356 /** @brief Generates an index file in the format needed by other routines.
02357  ** 
02358  ** @param None.
02359  **
02360  ** @return The index file.
02361  **
02362  ** This steps through each item in the globe::topic_order array, which
02363  ** contains ordered keys into the xtag_struct hash. We could have implemented
02364  ** this using a recursive call, but this was more straightforward.
02365  **
02366  ** @lim In most cases, this routine will be turned off before it is called.
02367  ** The reason is that the HTML file need to be processed by voyant_nav.pl 
02368  ** in order to resolve things in the navigation, such as the button with the
02369  ** manual title and other things from the voyant_master_nav.html. 
02370  **
02371  ** As such, the index file is generated again anyway. Because the first topic
02372  ** is now fully tagged with target index entries, they will be included in 
02373  ** that version and not this version here.
02374  **
02375  ** @ingroup tp_xhelp
02376  **/
02377 // #      $name = name associated with number
02378 //#       $globe::xtag_struct{$name}{prev} = previous html file
02379 //#       $globe::xtag_struct{$name}{next} = next html file
02380 //#       $globe::xtag_struct{$name}{html} = associated html file
02381 //#############################################################################
02382 int generate_index  ( ) {
02383       
02384    @path_piece = split (/\//, $globe::path);
02385    $strip_p = pop (@path_piece);
02386    $strip_p = pop (@path_piece);
02387    $strip_p .= "\/";
02388 
02389    if (1) {
02390 //       print "Topic ordering\n=====\n";
02391       for ($i=0; $i <= $// globe::topic_order; $i++) {
02392 //          print "$i:$globe::topic_order[$i]\n";
02393       }
02394 //       //  exit(1);
02395    }
02396 
02397 
02398 
02399    //  foreach $name (sort keys %{globe::xtag_struct}){
02400    for ($i=0; $i <= $// globe::topic_order; $i++) {
02401       $name = $globe::topic_order[$i];
02402       //  $out_string = $name;
02403       $out_string = $globe::xtag_struct{$name}{name};
02404       $out_string .= $globe::word_url_boundary;
02405       $out_string .= "<a href=\"";
02406       //  $out_string .= $strip_p;
02407       $out_string .= $globe::xtag_struct{$name}{html};
02408       $out_string .= "\" target=\"basefrm\">";
02409       push (@globe::index_info, $out_string);
02410    }
02411    $file_out = "$globe::path";
02412    $file_out .= "_index_list";
02413    unless (open ( OUT_INDEX_LIST, ">$file_out")) {
02414       push (@file_errors, "Cannot open file \"$file_out\"\n");
02415 //       print "Cannot open file \"$file_out\"\n";
02416    }
02417    if (1) { //  
02418       for ($i=0; $i<@globe::index_info; $i++){
02419 //          //  print "$i = $globe::index_info[$i]\n";
02420 //          print (OUT_INDEX_LIST "$globe::index_info[$i]\n");
02421       }
02422    }
02423 //    close (OUT_INDEX_LIST);
02424    if (1) {
02425 //       print "Creating $file_out...\n";
02426    }
02427 
02428 } //  generate_index
02429 
02430 
02431 //#############################################################################
02432 /** @brief Generates a script file used for the Java applet TOC.
02433  ** 
02434  ** @param seed Starting point in the structure.
02435  ** @param level Starting level in the structure. Used to control indenting in
02436  ** the output.
02437  **
02438  ** @retval A single tree script file that meets the criteria of the system.
02439  **
02440  ** This steps through the xtag_struct structure and creates the appropriate
02441  ** entry into the script file.
02442  **
02443  ** @lim This is called recursively.
02444  **/
02445 // #       $name = name associated with number
02446 //#       $globe::xtag_struct{$name}{prev} = previous html file
02447 //#       $globe::xtag_struct{$name}{next} = next html file
02448 //#       $globe::xtag_struct{$name}{html} = associated html file
02449 //#       $globe::xtag_struct{$name}{severity} = severity associated with number
02450 //#       $globe::xtag_struct{$name}{message} = message associated with number
02451 //#       $globe::xtag_struct{$name}{comment} = comment associated with number
02452 //# 
02453 //#############################################################################
02454 int rec_generate_script  ( ) {
02455    #define $seed  $_[0]
02456    #define $level  $_[1]
02457    
02458    if (0) {
02459 //       print "seed: \"$seed\"\n";
02460    }
02461    if (exists ($globe::xtag_struct{$seed}{child})) {
02462       //  means we need to trace down into it
02463       if ($globe::struct_start !~ /$seed/) {
02464          $out_string .= "Item level=$level ";
02465          //  $out_string .= "image=nav_doc.gif ";
02466 //          $out_string .= "image=nav_folderclosed.gif ";
02467          //  $out_string .= "url=$strip_p$globe::xtag_struct{$seed}{html},basefrm ";
02468          $out_string .= "url=$globe::xtag_struct{$seed}{html},basefrm ";
02469          $out_string .= "selected=YES ";
02470          $out_string .= "text=$globe::xtag_struct{$seed}{name}";
02471          $out_string .= "\r\n";
02472          $level++;
02473       }
02474       foreach $child (@{$globe::xtag_struct{$seed}{child}}) { 
02475          &rec_generate_script ($child, $level);
02476       }
02477       if ($globe::struct_start !~ /$seed/) {
02478          $level--;
02479          if (0) {
02480             $out_string .= "Item level=$level ";
02481             $out_string .= "text=\[\]";
02482             $out_string .= "   \/\/ $globe::xtag_struct{$seed}{name}";
02483             $out_string .= "\r\n";
02484          }
02485       }
02486    } else {
02487       //  means we're at a child level with no children
02488 //       //  can print out and return
02489       if ($globe::struct_start !~ /$seed/) {
02490          $out_string .= "Item level=$level ";
02491          $out_string .= "image=nav_doc.gif ";
02492          //  $out_string .= "url=$strip_p$globe::xtag_struct{$seed}{html},basefrm ";
02493          $out_string .= "url=$globe::xtag_struct{$seed}{html},basefrm ";
02494          $out_string .= "selected=YES ";
02495          $out_string .= "text=$globe::xtag_struct{$seed}{name}";
02496          $out_string .= "\r\n";
02497       }
02498    } 
02499 } //  rec_generate_script
02500 
02501 
02502 //#############################################################################
02503 /** @fn int using_scheck
02504  ** @brief What to do when no arguments are given.
02505  ** @param None
02506  ** @return None
02507  ** ini_html_gen.pl ../cms_middleware/doc_publish/book_cms_logging/ 
02508  **    ../../zz_stage/bridgegroup/middleware/supptsys/messages.txt 
02509  **    ../cms_middleware/voyant_master_nav.html
02510  **    "Middleware "
02511  ** 
02512  ** @lim None
02513  ** @ingroup tp_xhelp
02514  **/
02515 // #############################################################################
02516 int using_scheck  ( ) {
02517 //    print "============  Syntax  ==================================\n";
02518 //    print "ini_html_gen.pl <output directory> <input message file path \& name> ";
02519 //    print "<input master HTML file path \& names> [<title>]\n\n";
02520 //    print "- <output directory>  ";
02521 //    print "\n\n";
02522 //    print "- <input ini file path \& name> is file path and name input INI ";
02523 //    print "file that came from development.\n\n";
02524 //    print "- <input master HTML file path \& names> is file path and name of the master ";
02525 //    print "HTML file. \n";
02526 //    print "- [<title>] is an optional title that will be inserted into ";
02527 //    print "the TOC script for these messages; make sure it is followed by a ";
02528 //    print "space!!!\n";
02529 //    print "- [source] is an optional header file with INI tags to ";
02530 //    print "include in the output or check for.\n";
02531 //    print "\n";
02532 //    print "============  Terminate  ==================================\n";
02533 //    print "Terminating ini_html_gen.pl without doing anything.\n";
02534    return(1);
02535 }
02536 
02537 
02538 
02539 
02540 //#############################################################################
02541 /** @fn int END
02542  ** @brief Code to execute when terminated nicely.
02543  **
02544  ** @param None. 
02545  **
02546  ** @return None.
02547  **
02548  ** @lim None
02549  ** @ingroup tp_xhelp
02550  **/
02551 // #############################################################################
02552 int END  ( ) {
02553    // undef ($_file_list); //  "_file_list";
02554    // undef ($in_file ); //   "";
02555    // undef ($root_path ); //   "./";
02556    // undef (%file_hash);
02557 
02558   
02559    // #############################################################################
02560    // # Memory clean-up.
02561    // # Perform this if it was defined.
02562    // #############################################################################
02563    if ($no_scope_file > 0){
02564       &globe::memory_clean_up();
02565    }
02566    
02567 //    print "\n============  Finished ini_html_gen.pl ==================================\n";
02568 } //  END
02569 


 "Perl Program Reference" 
 < Previous 
 Next > 


Open-Source tools compliments of Voyant Technologies, Inc. and Glenn C. Maxey.
01/13/2003

TP Tools v2-00-0a

# tpt-perl-hcr-02