Contents 
 Index 
 "Perl Program Reference" 
 < Previous 
 Next > 

globe.pm

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 globe;
00018 
00019 //#############################################################################
00020 /** @file
00021  ** @brief Defines global variables that can be used by other programs.
00022  ** 
00023  ** Most of the variables refer to tags that we expect to find in the 
00024  ** HTML files. Others define variables that we want to use in a global way.
00025  **
00026  ** Tag names that are used in the master template files, all HTML files of
00027  ** the system, Mif2Go mif2htm.ini files, and Doxgyen header/footer files
00028  ** are defined here for all programs. They are in one place to facilitate
00029  ** their editing and maintenance.
00030  **
00031  ** @ingroup tp_tools
00032  **
00033  ** @author Glenn C. Maxey
00034  **
00035  **/
00036 // #    $Id: globe.pm,v 1.26 2002/11/21 17:17:57 gmaxe Exp $
00037 //#
00038 //# 2002 Created by Voyant Technologies, Inc., Westminster, Colorado, USA.
00039 //#
00040 //# Permission to use, copy, modify, and distribute this software and its 
00041 //# documentation under the terms of the GNU General Public License is hereby 
00042 //# granted. No representations are made about the suitability of this software 
00043 //# for any purpose. It is provided "as is" without express or implied warranty. 
00044 //# See the GNU General Public License (http://www.gnu.org/copyleft/gpl.html) 
00045 //# for more details.
00046 //# 
00047 //# Documents produced by this script are derivative works derived from the 
00048 //# input used in their production; they are not affected by this license.
00049 //#
00050 //#    Revision Information:
00051 //#
00052 //#       $Log: globe.pm,v $
00053 //#       Revision 1.26  2002/11/21 17:17:57  gmaxe
00054 //#       Tools to automatically update version and date in an HTML file.
00055 //#       Important when SCM runs our tool.
00056 //#
00057 //#       Revision 1.25  2002/10/11 20:20:05  gmaxe
00058 //#       Minor changes to condition for target testing.
00059 //#
00060 //#       Revision 1.24  2002/08/08 21:37:57  gmaxe
00061 //#       Further enhancements for debugging and to get the man pages
00062 //#       generated properly.
00063 //#
00064 //#       Revision 1.23  2002/08/07 01:27:11  gmaxe
00065 //#       Changed the {comment} to a {comment_full} where appropriate.
00066 //#       Enhanced the ini gen as appropriate to get the desired output.
00067 //#
00068 //#       Revision 1.22  2002/08/05 21:46:17  gmaxe
00069 //#       Added more debugging; fixed problems with levels; added output file
00070 //#       that is a tagged sample of what came in for ease in converting data.
00071 //#
00072 //#       Revision 1.21  2002/08/03 00:58:24  gmaxe
00073 //#       Updates before the weekend. Now it parses target files better;
00074 //#       had problems with scoping for variables.
00075 //#
00076 //#       Revision 1.19  2002/07/26 18:56:09  gmaxe
00077 //#       Got rid of old definitions and migrated new structures into all;
00078 //#       enhanced xhelp output file names and format; now everything is
00079 //#       alphebetized.
00080 //#
00081 //#       Revision 1.18  2002/07/26 00:28:44  gmaxe
00082 //#       Added support for xscope::sapi and other sapi data structures so
00083 //#       that its unique generation requirements are handled properly.
00084 //#       Output also sorts things alphebetically, a requirement for doxygen.
00085 //#
00086 //#       Revision 1.17  2002/07/22 21:51:29  gmaxe
00087 //#       Created separate configuration file; allow for two inputs to
00088 //#       the voyant_latex.pl. commented out old variables in globe.pm.
00089 //#
00090 //#       Revision 1.16  2002/07/03 23:07:22  gmaxe
00091 //#       Added support for mif2go index tokens. Later, remove the old
00092 //#       style index tokens and objects.
00093 //#
00094 //#############################################################################
00095 
00096 //#############################################################################
00097 /** @fn int BEGIN
00098  ** @brief Code to execute when first entered.
00099  **
00100  ** @param None. 
00101  **
00102  ** @return None.
00103  **
00104  ** @lim None
00105  ** @ingroup tp_tools
00106  **/
00107 // #############################################################################
00108 int BEGIN  ( ) {
00109    if (0) {
00110 //       print "globe.pm BEGIN routine.\n";
00111    }
00112 } //  BEGIN
00113 
00114 //#############################################################################
00115 /** @fn int main
00116  ** @brief Main routine.
00117  **
00118  ** @param None. 
00119  **
00120  ** @return None.
00121  **
00122  ** @lim None
00123  ** @ingroup tp_tools
00124  **/
00125 // #############################################################################
00126 // sub main {
00127 {
00128    // #####
00129    // # Main Subroutine doesn't do anything
00130    // #####
00131    if (0) {
00132 //       print "globe.pm main routine.\n";
00133    }
00134    
00135    if (0){
00136 //       print "=== Definitions 1 \n";
00137 //       print "=== voy header defb ==== $globe::m_define{header}[0]\n";
00138 //       print "=== voy header defb ==== $globe::m_define{header}[0]\n";
00139    }
00140    
00141    //  Needed in order for the package to work correctly from other perl programs.
00142    return(1);
00143 }
00144 
00145 //#############################################################################
00146 /** @fn int declare_variables
00147  ** @brief Allocates memory for all globally used variables.
00148  **
00149  ** @param None. 
00150  **
00151  ** @return None.
00152  **
00153  ** @lim None
00154  ** @ingroup tp_tools
00155  **/
00156 // #############################################################################
00157 int declare_variables  ( ) {
00158 
00159    // #############################################################################
00160    // # Declarations: all variables are global.
00161    // # All of the following are used in voyant_nav.pl (the first program).
00162    // # Some are used in other programs.
00163    // #############################################################################
00164    @valid_f_type = ("htm");
00165    @special_files = ("index.html", "tree.html", "topper.html", "side.html");
00166    @exclude_prefix = ("_start_");
00167    $path = "./";
00168    $master_nav_file = "none";
00169    $master_nav = "";
00170    // ####
00171    //  structure to define common tags in files.
00172    //  Array element [0] is the start tag.
00173    //  Array element [1] is the end tag.
00174    // ####
00175    @{$globe::m_define{date}} = ("<!-- voy_date -->", "<!-- end -->");
00176    @{$globe::m_define{version}} = ("<!-- voy_version -->", "<!-- end -->");
00177    @{$globe::m_define{header}} = ("<!-- begin voy_header -->", "<!-- end voy_header -->");
00178    @{$globe::m_define{nav_common}} = ("<!-- begin voy_common_top -->", "<!-- end voy_common_top -->");
00179    @{$globe::m_define{nav_doxygen}} = ("<!-- begin voy_dox -->", "<!-- end voy_dox -->");
00180    @{$globe::m_define{nav_book}} = ("<!-- begin voy_fm_book -->", "<!-- end voy_fm_book -->");
00181    @{$globe::m_define{footer}} = ("<!-- begin voy_footer -->", "<!-- end voy_footer -->");
00182    @{$globe::m_define{variable}} = ("<!-- begin voyant_variables", "// # -->");  # watchout! Not complete!
00183    @{$globe::m_define{html_zap}} = ("<!-- begin voy_html_zap -->", "<!-- end voy_html_zap -->");
00184    @{$globe::m_define{order}} = ("<!-- begin voy_order --", "!-- end voy_order -->");
00185    @{$globe::m_define{topic_list}} = ("<!-- begin voy_topic_list -->", "<!-- end voy_topic_list -->");
00186    @{$globe::m_define{title}} = ("<title>", "</title>");
00187    // ####
00188    //  07/03/2002 Will eventually no longer be needed.
00189    // ####
00190    @{$globe::m_define{index_token}} = ("<!-- index_token \"", "\" !-->");
00191    // ####
00192    //  07/03/2002 Newly supported Mif2Go index tokens that I export as:
00193    //  <a name="zzzz" class="v_index" value="token text">
00194    //  I'll keep the old structure around until the new can be completely implemented.
00195    //  Eventually, I'll no longer be generating the old style <!-- index_token !--> comments.
00196    // ####
00197    @{$globe::m_define{index_token2}} = ("<a name=\"", ">", "class=\"v_index", "\"", "value=\"", "\"");
00198    //  @{$globe::m_define{index_token2}} = ("<a ", ">", "class=\"v_index", "\"", "value=\"", "\"");
00199    
00200    //  used in voyant indexer
00201    @{$globe::m_define{structure}} = ("<!-- begin voy_structure -->", "<!-- end voy_structure -->");
00202    //  used in voyant latex
00203    @{$globe::m_define{latex}} = ("<!-- begin voy_latex --", "!-- end voy_latex -->");  
00204    @{$globe::m_define{latex_header}} = ("<!-- begin voy_latex_head --", "!-- end voy_latex_head -->");
00205 
00206    @{$globe::x_define{logmsg}} = ("<logmsg", ">", "</logmsg>");  
00207    @{$globe::x_define{initag}} = ("<initag", ">", "</initag>");  
00208    //  07/31/2002 @{$globe::x_define{isect}} = ("\[", "\]", "\[\]");  
00209    @{$globe::x_define{comment}} = ("\/\/\!", "\/\/", "\/\*\*", "\/\*", "\*\*", "\// \#\!", "\#\#", "\#");  
00210    @{$globe::x_define{comment}} = ("\/\/\!", "\/\/", "\// \#\!", "\#\#", "\#");  
00211  
00212 
00213    $m_var{define}{curr} = "// #curr##";
00214    $m_var{define}{curr2} = "// #curr2##";  # needed to separate header needs from mif2go.
00215    $m_var{define}{prev} = "// #prev##";
00216    $m_var{define}{next} = "// #next##";
00217    $m_var{define}{firstlast} = "// #firstlast##";
00218    $m_var{define}{end} = "// #";
00219    
00220    // ####
00221    $voy_curr = "";
00222    $voy_prev = "";
00223    $voy_next = "";
00224    $voy_variable = "";
00225    $rel_path_to_start_point_def = "// #rp2start##";
00226    $rel_path_to_start_point = "./";
00227 //    $pdf_dir = "print_pdf/";
00228    $this_pdf_flag = "// #this_pdf##";
00229    $fix_path_flag = "..";
00230    $fix_path_to = "..";
00231    $voy_variable_prev_dox = "// #prev_dox##";
00232    $voy_variable_next_dox = "// #next_dox##";
00233 
00234    // ####
00235    //  The following are variables containing HTML syntax observed in
00236    //  Doxygen output. This is text that I don't want so that it can
00237    //  be replaced with the navigation I do want from the master files.
00238    //  If Doxygen changes, this syntax can also change and would
00239    //  need to be updated.
00240    // ####
00241    $dox_nav_defb1 = "<center>\n<a class\=\"qindex\" href\=\"main.html\">Main Page<\/a>";
00242    $dox_nav_defb2 = "<center>\n<a class\=\"qindex\" href\=\"index.html\">Main Page<\/a>";
00243    $dox_nav_defe = "<\/center>\n<hr>";
00244    $dox_nav_defb3 = "<a class\=\"qindex\"";
00245    $dox_nav_defe3 = "<\/a>";
00246 
00247    $xmanual = "// #xmanual##";
00248    $xgroup = "// #xgroup##";
00249    // undef (%book_topics);         //  key is html file name, <Title> is stored
00250    // undef (%book_topic_order);    //  key is html file name, next html file is stored
00251    // undef (@book_first_topic);    //  ea ch in dir has own first/last
00252    // undef (@book_last_topic);     //  ea ch in dir has own first/last
00253    // undef (@file_errors);
00254    // undef (%book_topic_level);    //  key is html file name, <Headn> is stored
00255    // undef (@fm_format_levels);    //  ("TitleChapter", "Head1", "Head2", "Head3");  
00256    $last_book_level = 0;
00257    // ######################
00258 
00259    // ####
00260    //  CAREFUL: The index numbers are explicitly referenced... In particular,
00261    //  a fake out to equate [4] with [0] is done later in this program
00262    //  If you add other formats to watch, be careful about this.
00263    // 
00264    //  These use FrameMaker format names that are specific to our implementation.
00265    //  If you use other format names, they need to changed here.
00266    // ####
00267    $fm_format_levels[0] = "NONE"; //  Top Level
00268    $fm_format_levels[1] = "TitleChapter"; //  This comes from FM and mif2go.ini
00269    $fm_format_levels[2] = "Head1";
00270    $fm_format_levels[3] = "Head2";
00271    $fm_format_levels[4] = "Head3";
00272    $fm_format_levels[5] = "TitleAppendix"; //  This comes from mif2go.ini
00273    $fm_format_levels[6] = "TitleFront"; //  This comes from mif2go.ini
00274    $fm_format_levels[7] = "Indexhead"; //  This comes from mif2go.ini
00275    $fm_format_levels[8] = "TitleIndex"; //  This comes from mif2go.ini
00276    $fm_format_levels[9] = "TitleIntro"; //  This comes from mif2go.ini
00277    $fm_format_levels[10] = "TitleNoPrefix"; //  This comes from mif2go.ini
00278 
00279    $empty_html = "// #empty_html##";
00280    // undef (@voy_html_zap);
00281    $voy_variable_next_chapter = "// #next_chapter##";
00282    $voy_variable_prev_chapter = "// #prev_chapter##";
00283 
00284    $voy_variable_doc_num = "// #doc_number##";
00285    // undef (@master_order);  //  key is an index, short dir name is stored
00286    // undef (@master_order_title);  //  key is an index, short dir name is stored
00287    // undef (@master_order_pdf);  //  key is an index, pdf file is stored
00288    // undef (@master_order_doc_num);  //  key is an index, doc number is stored
00289    $master_order_key = "0"; //  key into the other master order items
00290 
00291    $voy_h1_b = "<h1";
00292    $voy_h1_e = "</h1>";
00293    // undef (@index_info);
00294    // ####
00295    //  Index tokens are passed from FM using Mif2Go and its MS-HTML output.
00296    //  Tokens are placed in an object tag.
00297    //  07/03/2002 object tag support is going away; these will be removed soon
00298    // ####
00299    $ms_object_b = "<object";  //  careful... does not contain closing ">"
00300    $ms_object_e = "</object>";  
00301    $ms_value_b = "value\=\"";
00302    $ms_value_e = "\">";
00303    //  07/03/2002 above
00304    
00305    
00306    $word_c_boundary = "\:\;\:";
00307    $word_url_boundary = "\:\,\:";
00308 
00309    // ####
00310    //  The following are variables containing HTML syntax observed in
00311    //  Doxygen output. 
00312    //  If Doxygen changes, this syntax can also change and would
00313    //  need to be updated.
00314    // ####
00315    $gi_filename_clue = "group";  //  clue that files beginning with "group" need additional parsing.
00316    $gi_name = "<a name\=";  //  gi: first clue to look for for index
00317    $gi_dox = "doxytag\="; //  gi: second clue to look for for index
00318    $gi_group_separator = "\:\:"; //  gi: separator from group and code item; code item is indexed
00319    
00320    // ####
00321    //  Used to create additional index tokens so that
00322    //  we can cross reference an packet to the calling functions in the index
00323    // ####
00324    $ack_used_by = "Used by "; //  Reference to who uses it.
00325    $ack_text_flag = "Acknowledgement Packets\:";  //  what to look for in for 
00326    @ack_ignore = ("_TBD_", "None");
00327    $ack_end = "<\/dl>";  //  delimiter for end of reference
00328    $ack_or = "or";
00329 
00330    $chapter_division = "<!--voy_LEV";
00331    $chapter_division_e = "-->";
00332 
00333    // #############################################################################
00334    // # All of the following are used in voyant_indexer.pl.
00335    // # Some are used in other programs following.
00336    // #############################################################################
00337    $master_index_html = "";
00338    $master_raw = "";   //  master list coming from all files
00339    // undef (%master_index);  //  key is title, title and url are stored
00340    // undef (@ignore_terms);
00341    $ignore_terms_file = "";
00342 
00343    $relative_path = "";
00344    $total_entry_in = 0;
00345    $total_entry_out = 0;
00346    $division_mult_entry = "\:\;\;\;\:";
00347 
00348    // #############################################################################
00349    // # All of the following are used in voyant_latex.pl.
00350    // # Some are used in other programs following.
00351    // #############################################################################
00352    $flag_title = "zz-doctitle-zz";
00353    $flag_doc_num = "zz-docnum-zz";
00354    $flag_date = "zz-doxgendate-zz";
00355 
00356    // undef (%latex_flags);
00357 
00358    $master_header_tex = "// #master_header_tex##";  # Has flag, then filename, then the entire master input file
00359    $master_doxygen_sty = "// #master_doxygen_sty##"; # Has flag, then filename, then the entire master input file
00360    $output_header_tex = "// #output_header_tex##";  # Has flag, then filename, then the entire output file
00361    $output_doxygen_sty = "// #output_doxygen_sty##"; # Has flag, then filename, then the entire output file
00362 
00363    // undef (@latex_title);  //  The first elements is file, second is latex start, third is latex stop
00364    $latex_title_page = "";
00365 
00366    // #############################################################################
00367    // # All of the following are used in voyant_mt_nav.pl, voyant_mt_app.pl
00368    // # Some are used in other programs following.
00369    // #############################################################################
00370    $pdf_name_from_dir = "book_cit_dtoss.pdf";
00371    $master_tree_html = "";
00372    $mt_empty_html = "m_tree_master.html";
00373    $topic_division = "</pre>";
00374    $nav_doc = "nav_doc.gif";
00375    $nav_folderopen = "nav_folderopen.gif";
00376 //    $nav_folderclosed = "nav_folderclosed.gif";
00377    $script_prefix = "tree_";
00378    $script_master = "m_tree.script";
00379    $script_master_prefix = "m_";
00380 
00381    // #############################################################################
00382    // # All of the following are used in voyant_gen_nav.pl.
00383    // # Some are used in other programs following.
00384    // #############################################################################
00385    $comment_b = "<\!\-\-";
00386    $comment_e = "\-\->";
00387    @toc_level = ("L1", "L2", "L3", "L4", "L5", "L6", "L7", "L8", "L9", "L10");
00388    $anchor_b = "<a";
00389    $anchor_e = ">";
00390    $href_b = "href\=";
00391 
00392    if (0){
00393 //       print "=== Definitions 2 \n";
00394 //       print "=== header ==== $globe::m_define{header}[0]\n";
00395    }
00396    // #############################################################################
00397    // # All of the following are used in tree_js_2_script.pl.
00398    // # Some are used in other programs following.
00399    // #############################################################################
00400    //  Name changing for Doxygen Output
00401    $dox_name_change{Modules} = "Groups";
00402    $dox_name_change{"File Members"} = "Globals \[C\+\+, IVE\] Functions, Enum Struct, Class, Define, etc.";
00403    $dox_name_change{"Compound List"} = "Classes (annotated)";
00404    //  $dox_name_change{Classes} = "Classes (listed)";
00405    $dox_name_change{Hierarchy} = "Class Hierarchy";
00406    $dox_name_change{"Compound Members"} = "Class Member Functions";
00407    $dox_name_change{FileList} = "Files in Project";
00408    
00409 
00410    return (1);
00411 
00412 } //  declare_variables
00413 
00414 //#############################################################################
00415 /** @fn int memory_clean_up
00416  ** @brief Cleans up after all variables that were defined.
00417  **
00418  ** @param None. 
00419  **
00420  ** @return None.
00421  **
00422  ** @lim None
00423  ** @ingroup tp_nav
00424  **/
00425 // #############################################################################
00426 int memory_clean_up  ( ) {
00427    // undef (@valid_f_type);     //  ("htm");;
00428    // undef (@special_files);     //  ("index.html", "main.html", "tree.html");
00429    // undef ($path);     //  "./";
00430    // undef ($master_nav_file);     //  "none";
00431    // undef ($master_nav);     //  "";
00432    // undef ($voy_curr);     //  "";
00433    // undef ($voy_prev);     //  "";
00434    // undef ($voy_next);     //  "";
00435    // undef ($voy_variable);     //  "";
00436    // undef ($rel_path_to_start_point_def);     //  "../";
00437    // undef ($rel_path_to_start_point);     //  "./";
00438    // undef ($pdf_dir);     //  "print_pdf/";
00439    // undef ($this_pdf_flag);     //  "../print_pdf/tpt-perl-crf.pdf";
00440    // undef ($fix_path_flag);     //  "..";
00441    // undef ($fix_path_to);     //  "..";
00442    // undef ($dox_nav_defb1);     //  "<center>\n<a class\=\"qindex\" href\=\"main.html\">Main Page<\/a>";
00443    // undef ($dox_nav_defb2);     //  "<center>\n<a class\=\"qindex\" href\=\"index.html\">Main Page<\/a>";
00444    // undef ($dox_nav_defe);     //  "<\/center>\n<hr>";
00445    // undef ($dox_nav_defb3);   //  = "\"qindex\"\";
00446    // undef ($dox_nav_defe3);   //  = "<\/a>";
00447 
00448    // undef ($xmanual);     //  "Perl Program Reference";
00449    // undef ($xgroup);     //  "Perl Program Reference";
00450    // undef (%book_topics);         //  key is html file name, <Title> is stored
00451    // undef (%book_topic_order);    //  key is html file name, next html file is stored
00452    // undef (@book_first_topic);    //  ea ch in dir has own first/last
00453    // undef (@book_last_topic);     //  ea ch in dir has own first/last
00454    // undef (@file_errors);
00455    // undef (%book_topic_level);    //  key is html file name, <Headn> is stored
00456    // undef (@fm_format_levels);    //  = ("TitleChapter", "Head1", "Head2", "Head3");  # This comes from mif2go.ini
00457    // undef ($last_book_level);     //  = 0;
00458    // undef ($voy_master_topic_orderb);   //  = "<!-- begin voy_master_topic_order -->";
00459    // undef ($voy_master_topic_ordere);   //  = "<!-- end voy_master_topic_order -->";
00460    // undef (@voy_master_topic_order);
00461    // undef ($empty_html);           //  = "##empty_html##";
00462    // undef (@voy_html_zap);
00463    // undef ($voy_variable_next_chapter);           //  = "##next_chapter##";
00464    // undef ($voy_variable_prev_chapter);           //  = "##prev_chapter##";
00465    // undef ($voy_variable_doc_num);           //  = "tpt-perl-hcr-02";
00466    // undef (@master_order);  //  key is an index, short dir name is stored
00467    // undef (@master_order_title);  //  key is an index, short dir name is stored
00468    // undef (@master_order_pdf);  //  key is an index, pdf file is stored
00469    // undef (@master_order_doc_num);  //  key is an index, doc number is stored
00470    // undef ($master_order_key);           //  = "0"; # key into the other master order items
00471    // undef ($voy_h1_b); //   = "<h1";
00472    // undef ($voy_h1_e); //   = "</h1>";
00473 
00474    // undef ($ms_object_b); //    = "<object";  # careful... does not contain closing ">"
00475    // undef ($ms_object_e); //    = "</object>";  
00476    // undef ($ms_value_b); //    = "value\=\"";
00477    // undef ($ms_value_e); //    = "\">";
00478 
00479    // undef ($gi_filename_clue); //  = "group";  # clue that files beginning with "group" need additional parsing.
00480    // undef ($gi_name); //  = "<a name\=";  # gi: first clue to look for for index
00481    // undef ($gi_dox); //  = "doxytag\="; # gi: second clue to look for for index
00482    // undef ($gi_group_separator); //  = "\:\:"; # gi: separator from group and code item; code item is indexed
00483    // undef ($chapter_division); //  = "<!-- chapter_chunk -->\n";
00484    
00485    // #############################################################################
00486    // # All of the following are used in voyant_indexer.pl.
00487    // # Some are used in other programs appearing later in file.
00488    // #############################################################################
00489    // undef ($master_index_html); //  = "";
00490    // undef ($master_raw); //  = "";   # master list coming from all files
00491    // undef (%master_index);  //  key is title, title and url are stored
00492    // undef (@ignore_terms);
00493    // undef ($ignore_terms_file); //  = "";
00494 
00495    // undef ($relative_path); //  = "";
00496    // undef ($total_entry_in); //  = 0;
00497    // undef ($total_entry_out); //  = 0;
00498    // undef ($division_mult_entry); //  = "\:\;\;\;\:";
00499 
00500    // #############################################################################
00501    // # All of the following are used in voyant_latex.pl.
00502    // # Some are used in other programs following.
00503    // #############################################################################
00504    // undef ($flag_title); //  = "zz-doctitle-zz";
00505    // undef ($flag_doc_num); //  = "zz-docnum-zz";
00506    // undef ($flag_date); //  = "zz-doxgendate-zz";
00507 
00508    // undef (%latex_flags);
00509 
00510    // undef ($master_header_tex); //  = "##master_header_tex##";  # Has flag, then filename, then the entire master input file
00511    // undef ($master_doxygen_sty); //  = "##master_doxygen_sty##"; # Has flag, then filename, then the entire master input file
00512    // undef ($output_header_tex); //  = "##output_header_tex##";  # Has flag, then filename, then the entire output file
00513    // undef ($output_doxygen_sty); //  = "##output_doxygen_sty##"; # Has flag, then filename, then the entire output file
00514 
00515    // undef (@latex_title);  //  The first elements is file, second is latex start, third is latex stop
00516    // undef ($latex_title_page); //  = "";
00517 
00518    // #############################################################################
00519    // # All of the following are used in voyant_mt_nav.pl.
00520    // # Some are used in other programs following.
00521    // #############################################################################
00522    // undef ($pdf_name_from_dir); //  = "book_cit_dtoss.pdf";
00523    // undef ($master_tree_html); //  = "";
00524    // undef ($mt_empty_html); //  = "m_tree_master.html";
00525    // undef ($topic_division); //  = "</pre>";
00526    // undef ($nav_doc); //  = "nav_doc.gif";
00527    // undef ($nav_folderopen); //  = "nav_folderopen.gif";
00528    // undef ($nav_folderclosed); //  = "nav_folderclosed.gif";
00529    
00530    return (1);
00531 }
00532 
00533 
00534 
00535 //#############################################################################
00536 /** New
00537  ** @fn int get_master_nav_info  ( )
00538  ** @brief Gets the ordering out of the master file.
00539  ** @param None.
00540  ** @return Stores information into global variables for use in updating variables
00541  ** and other parts of the topic HTML files..
00542  ** 
00543  ** This routine looks for paired HTML comments containing a
00544  ** tag name and "begin" or "end". Whatever is between these paired comments
00545  ** is the updated information to be placed in the individual HTML files.
00546  ** This reads in the entire master navigation file at one time and parses
00547  ** out the pieces of information that are important. Important tags are: <ul>
00548  **
00549  ** <li> Paired $globe::m_define{header}[0] & $globe::m_define{header}[1] for the
00550  ** header.</li>
00551  **
00552  ** <li> Paired $globe::m_define{footer}[0] & $globe::m_define{footer}[1] for the
00553  ** footer.</li>
00554  **
00555  ** <li> Paired $globe::m_define{nav_common}[0] & $globe::m_define{nav_common}[1] for the
00556  ** common navigation bar.</li>
00557  **
00558  ** <li> Paired $globe::m_define{nav_doxygen}[0] & $globe::m_define{nav_doxygen}[1] for the
00559  ** Doxygen navigation bar.</li>
00560  **
00561  ** <li> Paired $globe::m_define{nav_book}[0] & $globe::m_define{nav_book}[1] for the
00562  ** FM navigation bar.</li>
00563  **
00564  ** <li>Sometimes HTML is generated by Doxygen or Mif2Go that hard-codes fonts
00565  ** or styles that cannot be controlled by a CSS. 
00566  ** One of the lists that can be defined in the master file is a "zap"
00567  ** list. This is read into @globe::voy_html_zap hash. Each item in the zap list has
00568  ** three elements:<ol>
00569  ** <li>start of the offending tag but incomplete.</li>
00570  ** <li>end of first offending tag.</li>
00571  ** <li>end of tag pairs.</li></ol>
00572  ** The HTML tags defined in the zap list get taken out of the HTML document.</li>
00573  ** </ul>
00574  **
00575  ** This also extracts from the master file the order that the directories are 
00576  ** to be processed in. This establishes a hash table with the order of the
00577  ** sections in the HTML system, their associated PDF file names, their
00578  ** associated document numbers.
00579  ** 
00580  ** @lim None.
00581  ** @ingroup tp_nav
00582  **/
00583 // #############################################################################
00584 int get_master_nav_info  ( ) {
00585    // undef(@pre_chunks);
00586    // undef(@post_chunks);
00587    $value_2_return = 0;
00588    
00589    // # $globe::master_nav has to be available.
00590    if (0){
00591 //       print "=== master nav ====\n$globe::master_nav\n";
00592 //       print "=== Definitions 4\n";
00593 //       print "=== header ==== $globe::m_define{header}[0]\n";
00594    }
00595 
00596 
00597    foreach $def_type (keys %{globe::m_define}) {
00598       if (0) {
00599 //          print "$def_type... $globe::m_define{$def_type}[0] and $globe::m_define{$def_type}[1]\n";
00600       }
00601       //  Non-critical items that we don't need to record error messages
00602       $very_critical = 0;
00603       if ((0) && ($def_type =~ /order/)) {
00604          //  Critical items that we want to record error messages
00605          //  Needed later in voyant_nav.pl, because we want the doc-numbers.
00606          $very_critical = 1;
00607       }
00608       ($before, $piece, $after) = &globe::get_tag_chunk( $globe::master_nav,
00609                                   $globe::m_define{$def_type}[0], 
00610                                   $globe::m_define{$def_type}[1], 
00611                                   $very_critical);
00612       if ($piece) {
00613          if (($def_type =~ /order/) || ($def_type =~ /html_zap/)) {
00614             //  Special case does not need to have tags back.
00615             $globe::m_info{$def_type} .= "$piece";
00616          } else {
00617             //  Normal cases need to have tags placed back in.
00618             $globe::m_info{$def_type} = "$globe::m_define{$def_type}[0]";
00619             $globe::m_info{$def_type} .= "$piece";
00620             $globe::m_info{$def_type} .= "$globe::m_define{$def_type}[1]";
00621          }
00622       } elsif ($very_critical) {
00623          $value_2_return++;
00624       }
00625    }
00626 
00627    // #################
00628    //  Handling the HTML zap tags, things we don't want.
00629    // #################
00630    if (exists ($globe::m_info{html_zap})) {
00631       @{$globe::m_info{_array_html_zap}} = split (/\n/, $globe::m_info{html_zap});
00632       if (0){
00633 //          print "HTML zapping ===\n";
00634 //          //  print "$piece\n";
00635          for ($i=0; $i <= $// {$globe::m_info{_array_html_zap}}; $i++){
00636 //             print "$i $globe::m_info{_array_html_zap}[$i]\n";
00637          }
00638       }
00639    }
00640    // #################
00641    //  Handling the ordering of the subdirectories in the structure
00642    // #################
00643    if (exists ($globe::m_info{order})) {
00644       @pre_chunks = split ( /\n/, $globe::m_info{order});
00645       for ($i=0; $i <= $// pre_chunks; $i++){
00646          if ($pre_chunks[$i] =~ /[\w]+/) {
00647             @order_chunk = split ( /\,/, $pre_chunks[$i], 4);
00648             for ($j = 0; $j <= $// order_chunk; $j++){
00649                //  strip out quotation marks
00650                $order_chunk[$j] =~ s/[\s]*\"[\s]*//g;
00651             }
00652             // ####
00653             //  New structure
00654             // ####
00655             $globe::m_info{_array_order}[$i]{dir} = $order_chunk[0];
00656             $globe::m_info{_array_order}[$i]{title} = $order_chunk[1];
00657             $globe::m_info{_array_order}[$i]{pdf} = $order_chunk[2];
00658             $globe::m_info{_array_order}[$i]{num} = $order_chunk[3];
00659          }
00660       }  //  for $i
00661       if (0){
00662 //          print "Order ===\n";
00663 //          //  print "$piece\n";
00664          for ($i=0; $i <= $// {$globe::m_info{_array_order}}; $i++){
00665             foreach $k (keys %{$globe::m_info{_array_order}[$i]} ) {
00666 //                print "$i $k $globe::m_info{_array_order}[$i]{$k}\n";
00667             } //  each $k key
00668          } //  each $i
00669       } //  debug
00670    }
00671 
00672    
00673    // ####
00674    //  Support for the old
00675    // ####
00676    if (0) {
00677       if (exists ($globe::m_info{header})) {
00678          $globe::voy_header = $globe::m_info{header};
00679       }
00680       if (exists ($globe::m_info{nav_common})) {
00681          $globe::voy_common_top = $globe::m_info{nav_common};
00682       }
00683       if (exists ($globe::m_info{nav_doxygen})) {
00684          $globe::voy_dox = $globe::m_info{nav_doxygen};
00685       }
00686       if (exists ($globe::m_info{nav_book})) {
00687          $globe::voy_fm_book = $globe::m_info{nav_book};
00688       }
00689       if (exists ($globe::m_info{title})) {
00690          $globe::m_default_title = $globe::m_info{title};
00691       }
00692    }
00693    if (1) {
00694       if (exists ($globe::m_info{footer})) {
00695          $globe::voy_footer = $globe::m_info{footer};
00696       }
00697       if (exists ($globe::m_info{html_zap})) {
00698          @globe::voy_html_zap = @{$globe::m_info{_array_html_zap}}
00699       } else {
00700          push (@globe::voy_html_zap, "_none_");
00701       }
00702       if (exists ($globe::m_info{order})) {
00703          for ($i=0; $i <= $// {$globe::m_info{_array_order}}; $i++){
00704             $globe::master_order[$i] = $globe::m_info{_array_order}[$i]{dir};
00705             $globe::master_order_title[$i] = $globe::m_info{_array_order}[$i]{title};
00706             $globe::master_order_pdf[$i] = $globe::m_info{_array_order}[$i]{pdf};
00707             $globe::master_order_doc_num[$i] = $globe::m_info{_array_order}[$i]{num};
00708          } //  each $i
00709       }
00710 
00711    }
00712 
00713    //  Successful Return
00714    return($value_2_return);
00715    
00716 } //  get_master_nav_info
00717 
00718 //#############################################################################
00719 /** @fn int get_tag_chunk
00720  ** @brief Gets the information between two tags.
00721  **
00722  ** @param input_chunk Text to parse for tags.
00723  ** @param start_flag starting tag to look for.
00724  ** @param end_flag ending flag to look for.
00725  ** @param critical specifies whether or not to record error messages.
00726  **
00727  ** @retval before the information before the starting tag, 0 if one of tags is missing.
00728  ** @retval info the information between the tags,  0 if one of tags is missing.
00729  ** @retval after the information after the ending tag,  0 if one of tags is missing.
00730  ** 
00731  ** @lim Does not return the tags.
00732  ** @ingroup tp_toc
00733  **/
00734 // #############################################################################
00735 int get_tag_chunk  ( ) {
00736    $input_chunk = $_[0];
00737    $start_flag = $_[1];
00738    $end_flag = $_[2];
00739    $critical = $_[3];
00740    $case_insensitive = $_[4];
00741    
00742    if (0) {
00743 //       print "get_tag_chunk...\n";
00744 //       print "start = \"$start_flag\"\n";
00745 //       print "end   = \"$end_flag\"\n";
00746    }
00747 
00748    if ($case_insensitive) {
00749       //  Case insensitive
00750       if ($input_chunk !~ /$start_flag/i) {
00751          if ($critical) {
00752 //             print "Input does not contain $start_flag\n";
00753             push (@globe::file_errors, "ERROR: Missing $start_flag.");
00754          }
00755          return (0, 0, 0);
00756       }   
00757       if ($input_chunk !~ /$end_flag/i) {
00758          if ($critical) {
00759 //             print "Input does not contain $end_flag\n";
00760             push (@globe::file_errors, "ERROR: Missing $end_flag.");
00761          }
00762          return (0, 0, 0);
00763       }
00764       @sm_chunk1 = split (/$start_flag/i, $input_chunk, 2);
00765       @sm_chunk2 = split (/$end_flag/i, $sm_chunk1[1], 2);
00766    } else {
00767       //  Case sensitive
00768       if ($input_chunk !~ /$start_flag/) {
00769          if ($critical) {
00770 //             print "Input does not contain $start_flag\n";
00771             push (@globe::file_errors, "ERROR: Missing $start_flag.");
00772          }
00773          return (0, 0, 0);
00774       }   
00775       if ($input_chunk !~ /$end_flag/) {
00776          if ($critical) {
00777 //             print "Input does not contain $end_flag\n";
00778             push (@globe::file_errors, "ERROR: Missing $end_flag.");
00779          }
00780          return (0, 0, 0);
00781       }
00782       @sm_chunk1 = split (/$start_flag/, $input_chunk, 2);
00783       @sm_chunk2 = split (/$end_flag/, $sm_chunk1[1], 2);
00784    }
00785    
00786    // undef ($input_chunk);
00787    // undef ($start_flag);
00788    // undef ($end_flag);
00789    //  // undef (@sm_chunk1);
00790    return ($sm_chunk1[0], $sm_chunk2[0], $sm_chunk2[1]);   
00791 
00792    
00793 } //  get_tag_chunk
00794 
00795 
00796 //#############################################################################
00797 /** @fn int replace_tag_chunk
00798  ** @brief Replaces the information in between the tags with the supplied
00799  ** information.
00800  ** 
00801  ** @param input_chunk Text to parse for tags.
00802  ** @param start_flag starting tag to look for.
00803  ** @param end_flag ending flag to look for.
00804  ** @param replacement_text Text to put between tags.
00805  ** @param reinsert_tags specifies whether or not tags should be reinserted
00806  ** @param critical specifies whether or not to record error messages.
00807  **
00808  ** @retval success 1 if found tags, 0 if one of tags is missing.
00809  ** @retval output with replacement text and tags if found tags, 
00810  ** the original input text if one of tags is missing.
00811  ** 
00812  ** @lim None.
00813  ** @ingroup tp_toc
00814  **/
00815 // #############################################################################
00816 int replace_tag_chunk  ( ) {
00817    $input_chunk = $_[0];
00818    $start_flag = $_[1];
00819    $end_flag = $_[2];
00820    $replacement_text = $_[3];
00821    $reinsert_tags = $_[4];
00822    $critical = $_[5];
00823    $output = "";
00824 
00825    if (0) {
00826 //       print "replace_tag_chunk...\n";
00827    }
00828 
00829 
00830 
00831    if ($input_chunk !~ /$start_flag/) {
00832       if ($critical) {
00833 //          print "Input does not contain $start_flag\n";
00834          push (@globe::file_errors, "ERROR: Master file does not have proper $where definition.");
00835          push (@globe::file_errors, "Missing $start_flag.");
00836       }
00837       return (0, $input_chunk);
00838    }   
00839    if ($input_chunk !~ /$end_flag/) {
00840       if ($critical) {
00841 //          print "Input does not contain $end_flag\n";
00842          push (@globe::file_errors, "ERROR: Master file does not have proper $where definition.");
00843          push (@globe::file_errors, "Missing $end_flag.");
00844       }
00845       if (0) {
00846 //          print "replace_tag_chunk... 0\n";
00847       }
00848 
00849       return (0, $input_chunk);
00850    }
00851    @sm_chunk1 = split (/$start_flag/, $input_chunk, 2);
00852    @sm_chunk2 = split (/$end_flag/, $sm_chunk1[1], 2);
00853    
00854    if ($reinsert_tags) {
00855       $output = $sm_chunk1[0];
00856       $output .= $start_flag;
00857       $output .= $replacement_text;
00858       $output .= $end_flag;
00859       $output .= $sm_chunk2[1];
00860    } else {
00861       $output = $sm_chunk1[0];
00862       $output .= $replacement_text;
00863       $output .= $sm_chunk2[1];
00864    }
00865    
00866    // undef (@sm_chunk1);
00867    // undef (@sm_chunk2);
00868    if (0) {
00869 //       print "replace_tag_chunk... 1\n";
00870    }
00871    
00872    return (1, $output);   
00873 
00874    
00875 } //  replace_tag_chunk
00876 
00877 
00878 
00879 //#############################################################################
00880 /** @brief Reads in the entire file but separates code from comments in two
00881  ** different structures.
00882  ** 
00883  ** @param src_file The file to open and read in.
00884  ** @param separate_comments 0 puts it all into $entire_file; 1 puts all
00885  ** of the comments into $comment_file and everything else into
00886  ** $entire_file.
00887  ** 
00888  ** @lim 
00889  **/
00890 // #############################################################################
00891 int read_code_n_comment  ( ) {
00892    #define $src_file  $_[0]
00893    #define $separate_comments  $_[1]
00894    $ret_val = 1;
00895    #define $rcnc_debug  0
00896    
00897    if ($rcnc_debug) {
00898 //       print "rcnc:src_file $src_file\n";
00899 //       print "rcnc:separate_comments $separate_comments\n";
00900    }
00901 
00902    // undef ($globe::entire_file);
00903    // undef ($globe::comment_file);
00904    unless (open ( IN_SRC, $src_file)) {
00905 //       print "1 Cannot open file \"$src_file\"\n";
00906       push (@file_errors, "1 Cannot open file \"$src_file\"\n");
00907       $ret_val = 0;
00908       return (0);
00909    }
00910    if ($separate_comments) {
00911       while (<IN_SRC>) {
00912          //  The only time we need to separate comments from
00913          //  text is when the input file is the message text file
00914          //  and we are picking up areas that have tags and
00915          //  areas that are the log lines.
00916          if (($_ =~ /^[\s]*\/\//)
00917             || ($_ =~ /^[\s]*\/\*/)
00918             || ($_ =~ /^[\s]*\*\*/)
00919             || ($_ =~ /^[\s]*\*/)
00920             ){
00921             //  Only read in comment lines.
00922             if ((0) && ($rcnc_debug)) {
00923 //                print "rcnc:Comment... $_";  //  no \n needed
00924             }
00925             $globe::comment_file .= $_;
00926          } elsif ($_ =~ /^[\s]+$/) {
00927             //  Not interested in blank lines at all.
00928          } else {
00929             //  Only read in non-comment lines.
00930             $globe::entire_file .= $_;
00931          }
00932       }
00933    } else {
00934       while (<IN_SRC>) {
00935          //  XML files or other text files don't need to
00936          //  separate code comments out from regular text.
00937          //  For that matter, code files don't really need to
00938          //  separate things.
00939          $globe::comment_file .= $_;
00940       }
00941    }
00942 //    close (IN_SRC);
00943    if ($rcnc_debug) {
00944 //       print "=====\nrcnc:entire_file\n=====\n$globe::entire_file";
00945 //       print "=====\nrcnc:comment_file\n=====\n $globe::comment_file";
00946 //       //  exit;
00947    }
00948    return ($ret_val);
00949 } //  read_code_n_comment
00950 
00951 
00952 //#############################################################################
00953 /** @brief Processes the comment lines from the file that may have tags 
00954  ** in them.
00955  **
00956  ** @param src_file is the file associated with the comments.
00957  **
00958  ** @param tag_name defines the tag identifier to look for.
00959  **
00960  ** This calls another routine that puts $tag_name name tags into a data structure.
00961  ** When this routine is done, we no longer need globe::comment_file.
00962  ** 
00963  ** @lim Does not test the tag_name is valid or has been defined.
00964  **/
00965 // #############################################################################
00966 int process_comments_from_file  ( ) {
00967    #define $src_file  $_[0]
00968    #define $tag_name  $_[1]
00969    #define $debug_pcff  0
00970 
00971    if ((0) && ($debug_pcff)) {
00972 //       //  print "pcff:entire_file $globe::entire_file\n";
00973 //       print "pcff:These are the comments:\n";
00974 //       print "pcff:comment_file $globe::comment_file\n";
00975 //       print "pcff:========== $tag_name \n";
00976       for ($i=0; $i <= $// {$globe::x_define{$tag_name}}; $i++) {
00977 //          print "$i: $globe::x_define{$tag_name}[$i]\n"
00978       }
00979 //       print "pcff:shrink $shrinking_chunk\n";
00980 //       //  exit;
00981    }
00982 
00983    
00984    if ($globe::comment_file =~ /$globe::x_define{$tag_name}[0]/) {
00985       $shrinking_chunk = $globe::comment_file;
00986       if ($debug_pcff) {
00987 //          print "pcff:shrink $shrinking_chunk\n";
00988 //          print "pcff:x_define $globe::x_define{$tag_name}[0]\n";
00989       }
00990       while ($shrinking_chunk =~ /$globe::x_define{$tag_name}[0]/) {
00991          $shrinking_chunk = &globe::piece_btn_tag($shrinking_chunk, 
00992                             "name", $src_file, $tag_name);
00993       }
00994       if ($debug_pcff) {
00995 //          print "pcff:tag_mess1...\n";
00996          foreach $f (sort keys %{$globe::tag_mess{file}}) {
00997             foreach $t (sort keys %{$globe::tag_mess{file}{$f}}){
00998 //                print "pcff:file\"$f\":tag \"$t\":\n$globe::tag_mess{file}{$f}{$t}\n";
00999             }
01000          }
01001 //          print "pcff:tag_mess2...\n";
01002          foreach $t (sort keys %{$globe::tag_mess{name}}) {
01003             foreach $i (@{$globe::tag_mess{name}{$t}}){
01004 //                print "pcff:name \"$t\":file $globe::tag_mess{name}{$t}[$i]\n";
01005             }
01006          }
01007 //          print "pcff:tag_mess3...\n";
01008       }
01009    } else {
01010       // ###
01011       //  08/07/2002 We may not have found any tags, but we still processed the
01012       //  file; mark it as such
01013       // ###
01014       $globe::tag_mess{file}{$src_file} = $src_file;
01015 //       print "pcff: Not an error; found no \"$globe::x_define{$tag_name}[0] ";
01016 //       print "$globe::x_define{$tag_name}[1]\"  named targets in comments ";
01017 //       print "from \"$src_file\".\n";
01018       if ($debug_pcff) {
01019 //          print "pcff:tag_mess4...\n";
01020          foreach $f (sort keys %{$globe::tag_mess{file}}) {
01021             foreach $t (sort keys %{$globe::tag_mess{file}{$f}}){
01022 //                print "pcff:file\"$f\":tag \"$t\":\n$globe::tag_mess{file}{$f}{$t}\n";
01023             }
01024          }
01025       }
01026       return (0);
01027    }
01028    return (1);
01029    
01030 } //  process_comments_from_file
01031 
01032 
01033 
01034 
01035 
01036 //#############################################################################
01037 /** @brief Creates a data structure from each line in the message file.
01038  ** This builds a data structure:
01039  ** 
01040  **  $globe::tag_mess{file}{$file_name}{$name} = $data;
01041  **  $globe::tag_mess{name}{$name}[$i] = $file_name;
01042  ** 
01043  **       $hname = created name for hash made from actual names of parents and
01044  **                children 
01045  **       $globe::xtag_struct{$hname}{name} = actual item name
01046  **       $globe::xtag_struct{$hname}{parent} = owning section
01047  **       $globe::xtag_struct{$hname}{child}[] = array of associated children
01048  **       $globe::xtag_struct{$hname}{comment} = comment flag
01049  **       $globe::xtag_struct{$hname}{desc_html} = description in html
01050  **       $globe::xtag_struct{$hname}{desc_man} = description in man
01051  ** 
01052  **       $name = name associated with number
01053  **       $msg_struct{$name}{severity} = severity associated with number
01054  **       $msg_struct{$name}{message} = message associated with number
01055  **       $msg_struct{$name}{comment} = comment associated with number
01056  ** 
01057  ** 
01058  ** @lim 
01059  **/
01060 // #############################################################################
01061 int xtag_into_mess_structure  ( ) {
01062    #define $src_file  $_[0]
01063    #define $tag_xml  $_[1]
01064    #define $debug_xims  0
01065    
01066 
01067    foreach $name (sort keys %{xtag_struct}){
01068       if ($debug_xims) {
01069 //          print "xims:org ===\n$globe::xtag_struct{$name}{comment}\n";
01070       }
01071       $changing_chunk = $globe::xtag_struct{$name}{comment};
01072       while ($changing_chunk =~ /target\=/i) {
01073          $changing_chunk = &globe::xml_tag_target ($changing_chunk, $src_file, $tag_xml);
01074       }
01075       if ($debug_xims) {
01076 //          print "xims:new ===\n$changing_chunk\n++++++++++++++\n";
01077       }
01078       $globe::xtag_struct{$name}{comment_full} = $changing_chunk;
01079    }
01080 
01081    return (1);
01082 } //  xtag_into_mess_structure
01083 
01084 
01085 
01086 
01087 //#############################################################################
01088 /** @brief Gets the data associated with a target in the chunk
01089  ** and passes the chunk back.
01090  **
01091  ** @param chunk_to_parse A chunk with a target inside of it.
01092  ** @param src_file_name The file associated with the target.
01093  **
01094  ** @return The chunk with the target expanded into what it is after
01095  ** hunting it down. The $tag_name tag with the target in it is removed
01096  ** whether or not any associated data could be hunted down.
01097  **
01098  ** This calls the validate_and_fetch routine, which in turn
01099  ** calls the globe::read_code_n_comment and process_..._file that were called
01100  ** earlier at a higher level. They are reused in hunting down targets
01101  ** and the targets' data.
01102  **
01103  ** @lim This does no error checking if the the chunk has the 
01104  ** the target in it or if the $tag_name (xml identifier) is defined
01105  ** in the globe.pm file under $globe::m_define{$tag_name}.
01106  ** 
01107  **/
01108 // #############################################################################
01109 int xml_tag_target  ( ) {
01110    #define $chunk_to_parse  $_[0]
01111    #define $src_file_name  $_[1]
01112    #define $tag_name  $_[2]
01113    #define $name  0
01114    #define $targ_f_name  0
01115    #define $data  0
01116    #define $before  ""
01117    #define $after  ""
01118    #define $debug_xtt  0
01119    
01120    if ($debug_xtt) {
01121 //       print "x_t_t:chunk_to_parse \"$chunk_to_parse\"\n";
01122 //       print "x_t_t:src_file_name \"$src_file_name\"\n";
01123 //       print "x_t_t:tag_name \"$tag_name\"\n";
01124    }
01125    
01126    ($before, $lm_label, $after) = &globe::get_tag_chunk( $chunk_to_parse,
01127               $globe::x_define{$tag_name}[0], 
01128               $globe::x_define{$tag_name}[1], 
01129               0);
01130    // ####
01131    //  Get the xml target to look for
01132    // ####
01133    #define $tag_param  "target"
01134    if ((0) && ($debug_xtt)) {
01135 //       print "x_t_t:tag_param \"$tag_param\"\n";
01136 //       print "x_t_t:lm_label \"$lm_label\"\n";
01137    }
01138    if ($lm_label =~ /$tag_param/i) {
01139       // ####
01140       //  Get the name of the $tag_name tag for the database
01141       // ####
01142       @name_chunk = split (/$tag_param[\s]*\=/, $lm_label, 2);
01143       ($g1, $target, $g2) = &globe::get_tag_chunk( $name_chunk[1], "\"", "\"", 0);
01144       if ($debug_xtt) {
01145 //          print "we got a target: \"$target\"\n";
01146 //          //  exit;
01147       }
01148    } else {
01149       //  There is no target, but let's rebuild without $tag_name tag and return
01150       $chunk_to_parse = join ("", $before, $after);
01151       return ($chunk_to_parse, 0, $src_file_name);
01152    }
01153    
01154    // ####
01155    //  Get the file to look for
01156    // ####
01157    $tag_param = "file";
01158    if ($lm_label =~ /$tag_param[\s]*\=/i) {
01159       //  updated conditional to not catch any "file" that might be part
01160       //  of an item name.
01161       // ####
01162       //  Get the name of the $tag_name tag for the database
01163       // ####
01164       @name_chunk = split (/$tag_param[\s]*\=/, $lm_label, 2);
01165       ($g1, $targ_f_name, $g2) = &globe::get_tag_chunk( $name_chunk[1], "\"", "\"", 0);
01166       if ((0) && ($debug_xtt)) {
01167 //          print "x_t_t:label chunk: \"$lm_label\"\n";
01168 //          print "x_t_t:we got a file: \"$targ_f_name\"\n";
01169 //          //  exit;
01170       }
01171       @in_file = split (/\//, $src_file_name);
01172       pop (@in_file); //  removes the old file name from the array
01173       if ($targ_f_name =~ /^\//) {
01174          //  if $targ_f_name begins with a slash, then we have an absolute path;
01175          //  use this name as is.
01176          $src_file_name = $targ_f_name;
01177       } elsif ($targ_f_name =~ /^\.\//) {
01178          //  The file is located in the same directory.
01179          //  strip off file from input file name;
01180          //  strip of ./ from this target file.
01181          //  combine the two.
01182          $targ_f_name =~ s/^\.\///;
01183          $src_file_name = join ("/", @in_file, $targ_f_name);
01184       } elsif ($targ_f_name =~ /^\.\.\//) {
01185          //  The file is located a relative directory.
01186          //  strip off file from input file name;
01187          //  for every ../ from this target file, pop off something.
01188          //  combine what's left.
01189          while ($targ_f_name =~ /^\.\.\//) {
01190             $targ_f_name =~ s/^\.\.\///;
01191             pop (@in_file);
01192          }
01193          $src_file_name = join ("/", @in_file, $targ_f_name);
01194       } else {
01195          //  The file is okay to append as is.
01196          $src_file_name = join ("/", @in_file, $targ_f_name);
01197       }
01198       if ($debug_xtt) {
01199 //          print "x_t_t:src_file_name $src_file_name\n";
01200       }
01201    } else {
01202       //  There is no target to catch
01203       if ($debug_xtt) {
01204 //          print "x_t_t:src_file_name $src_file_name\n";
01205       }
01206    }  //  $tag_param = "file";
01207    
01208    // ####
01209    //  Now it is time to see if that file is valid and to get
01210    //  information out of it.
01211    // ####
01212    $data = &globe::validate_and_fetch ($src_file_name, $tag_name, $target);
01213    if ($debug_xtt) {
01214 //       print "x_t_t:target=$target; $data \n+++++++\n";
01215    }
01216    if ($data) {
01217       // ####
01218       //  If validate_and_fetch returned something other than
01219       //  0, append this to the $before stuff. This effectively
01220       //  will replace the $tag_name tag with the data
01221       //  when the comment gets rebuilt.
01222       // ####
01223       //  08/02/2002 cludge
01224       //  return ($data);
01225       //  08/02/2002 was
01226       $before .= $data;
01227    }
01228    if ((0) && ($debug_xtt)) {
01229 //       print "x_t_t:target=$target; file=$src_file_name\n";
01230    }
01231    if ((0) && ($debug_xtt)) {
01232 //       print "x_t_t:before $before\n";
01233 //       print "x_t_t:data $data\n";
01234 //       print "x_t_t:after $after\n";
01235    }
01236    
01237    
01238    // ####
01239    //  Rebuild the chunk without the information that was parsed out.
01240    //  This means either we've removed just the erroneous beginning
01241    //  $tag_name tag,
01242    //  or the beginning/ending tags and the data in between.
01243    //  Either way, we're removing the conditions that keep this
01244    //  routine from being called.
01245    // ####
01246    $chunk_to_parse = join ("", $before, $after);
01247 
01248    return ($chunk_to_parse);
01249 } //  xml_tag_target
01250 
01251 //#############################################################################
01252 /** @brief Removes the tags and associated data
01253  ** from the data chunk that is passed in.
01254  ** 
01255  ** @param chunk_to_parse A piece of text that has at least one beginning
01256  ** $tag_name tag.
01257  ** @param file_name The name of the file to which the $tag_name tag is associated.
01258  **
01259  ** This builds a data structure:
01260  ** 
01261  **  $globe::tag_mess{file}{$file_name}{$name} = $data;
01262  **  $globe::tag_mess{name}{$name}[$i] = $file_name;
01263  ** 
01264  ** It allows us to be efficient in the future, whereby we won't have to
01265  ** open a file that we've already visited, because we'll already have acquired
01266  ** all associated $tag_name item for that file. Also, we'll know later if
01267  ** a $tag_name name has been defined in more than one file.
01268  ** 
01269  ** @lim Error checking for the existence of a file name in the structure
01270  ** needs to happen before this routine is called. 
01271  **/
01272 // #############################################################################
01273 int piece_btn_tag  ( ) {
01274    #define $chunk_to_parse  $_[0]
01275    #define $tag_param  $_[1]
01276    #define $file_name  $_[2]
01277    #define $tag_name  $_[3]
01278    #define $before  ""
01279    #define $after  ""
01280    #define $lm_label  ""
01281    #define $data  ""
01282    #define $debug_pbt  0
01283 
01284    if ($debug_pbt) {
01285 //       print "pbt:chunk_to_parse $chunk_to_parse\n";
01286 //       print "pbt:tag_param $tag_param\n";
01287 //       print "pbt:file_name $file_name\n";
01288 //       print "pbt:tag_name $tag_name\n";
01289 //       print "pbt:globe::x_define{$tag_name}[0] $globe::x_define{$tag_name}[0]\n";
01290 //       print "pbt:globe::x_define{$tag_name}[1] $globe::x_define{$tag_name}[1]\n";
01291    }
01292    ($before, $lm_label, $after) = &globe::get_tag_chunk( $chunk_to_parse,
01293               $globe::x_define{$tag_name}[0], 
01294               $globe::x_define{$tag_name}[1], 
01295               0);
01296    if ($debug_pbt) {
01297 //       print "pbt:lm_label $lm_label\n";
01298    }
01299    // ####
01300    //  Get the name target for the given tag
01301    // ####
01302    if ($lm_label =~ /$tag_param/i) {
01303       // ####
01304       //  Get the name of the $tag_name tag for the database
01305       // ####
01306       //  @name_chunk = split (/name[\s]*\=/, $lm_label, 2);
01307       @name_chunk = split (/$tag_param[\s]*\=/, $lm_label, 2);
01308       ($g1, $name, $g2) = &globe::get_tag_chunk( $name_chunk[1], "\"", "\"", 0);
01309       if ($debug_pbt) {
01310 //          print "we got a name: \"$name\"\n";
01311 //          //  exit;
01312       }
01313       // ####
01314       //  Look for the ending $tag_name tag
01315       // ####
01316       if ($after =~ /$globe::x_define{$tag_name}[2]/) {
01317          // ####
01318          //  Everything up to this chunk is of interest to us.
01319          //  At this point we know there's an opening and closing
01320          //  $tag_name tag with information inbetween
01321          // ####
01322          @lm_data = split (/$globe::x_define{$tag_name}[2]/, $after, 2);
01323          @lm_data2 = split (/\n/, $lm_data[0]);
01324          for ($j=0; $j <= $// lm_data2; $j++) {
01325             for ($k=0; $k <= $// {$globe::x_define{comment}}; $k++){
01326                if ($debug_pbt) {
01327 //                   print "comment type: $globe::x_define{comment}[$k]\n";
01328                }
01329                if ($lm_data2[$j] =~ /[\s]*$globe::x_define{comment}[$k]/) {
01330                   $lm_data2[$j] =~ s/[\s]*$globe::x_define{comment}[$k]//;
01331                }
01332             }
01333             // ####
01334             //  Special case comment lines that are C style with *'s.
01335             // ####
01336             if ($lm_data2[$j] =~ /^[\s]*\/\*\*/) {
01337                $lm_data2[$j] =~ s/^[\s]*\/\*\*//;
01338             } elsif ($lm_data2[$j] =~ /^[\s]*\/\*/) {
01339                $lm_data2[$j] =~ s/^[\s]*\/\*//;
01340             } elsif ($lm_data2[$j] =~ /^[\s]*\*\*/) {
01341                $lm_data2[$j] =~ s/^[\s]*\*\*//;
01342             } elsif ($lm_data2[$j] =~ /^[\s]*\*/) {
01343                $lm_data2[$j] =~ s/^[\s]*\*//;
01344             }
01345             $lm_data2[$j] =~ s/^[\s]*//;
01346          }
01347          $data = join ("\n", @lm_data2);
01348          if ($debug_pbt) {
01349 //             print "we got stripped data====\n$data\n=====\n";
01350          }
01351 
01352          // ####
01353          //  Put the name that we found, the file name, and
01354          //  the associated data into the data structure.
01355          // ####
01356          if (exists ($globe::tag_mess{file}{$file_name}{$name})) {
01357             //  if it exists, append it so that we get everything.
01358             $globe::tag_mess{file}{$file_name}{$name} .= $data;
01359          } else {
01360             $globe::tag_mess{file}{$file_name}{$name} = $data;
01361             if ((0) || ($debug_pbt)) {
01362 //                print "pbt:new file \"$file_name\" or new tag \"$name\"\n";
01363             }
01364          }
01365          push (@{$globe::tag_mess{name}{$name}}, $file_name);
01366 
01367          // ####
01368          //  We partial rebuild and remove data.
01369          //  A full rebuild happens as the default fall through.
01370          // ####
01371          $after = $lm_data[1];
01372       } else {
01373          //  This is not well formed and there is no ending $tag_name tag.
01374          //  remove the $tag_name, rebuild, and return.
01375          //  This is the default fall through
01376       }
01377    } elsif ($lm_label =~ /[\w]+/) {
01378      //  The name is not composed of white space, but also isn't completely
01379      //  what we want; it might be a $tag_name target;
01380      //  remove the tag, though, so loop will stop.
01381      //  This is the default fall through.
01382    } else {
01383       //  name is composed of white space
01384       //  Remove the $tag_name tag, rebuild and return.
01385       //  If this has a problem, it might be leaving a closing
01386       //  $tag_name tag.
01387       if ($debug_pbt) {
01388 //         print "Hola 2\n";
01389       }
01390    }
01391    // ####
01392    //  Rebuild the chunk without the information that was parsed out.
01393    //  This means either we've removed just the erroneous beginning
01394    //  $tag_name tag,
01395    //  or the beginning/ending tags and the data in between.
01396    //  Either way, we're removing the conditions that keep this
01397    //  routine from being called.
01398    // ####
01399    $chunk_to_parse = join ("", $before, $after);
01400    
01401    //  08/07/2002 Put an entry into the hash that says we processed
01402    //  the file.
01403    if (exists ($globe::tag_mess{file}{$file_name})) {
01404       //  We're okay, no need to do anything.
01405    } else {
01406       //  The file was processed, but no entries found.
01407       //  Put file into hash.
01408       //  $globe::tag_mess{file}{$file_name}{$name}
01409       $globe::tag_mess{file}{$file_name} = $file_name;
01410    }
01411 
01412    return ($chunk_to_parse);
01413 } //  piece_btn_tag
01414 
01415 //#############################################################################
01416 /** @brief Determines if we have already processed the file for the tag and
01417  ** does the processing.
01418  ** 
01419  ** @param f_name The path and name of the file.
01420  **
01421  ** @param tag_xml The name of the xml tag to look for in the file.
01422  **  
01423  ** @param targ_xml_tag The name of the target within the xml tag to look for.
01424  ** 
01425  ** If the file and tag have not been processes, this performs the processing
01426  ** on the file for that specific tag.
01427  **
01428  ** The processing involves adding information to the data structure.
01429  ** 
01430  **  $globe::tag_mess{file}{$file_name}{$name} = $data;
01431  **  $globe::tag_mess{name}{$name}[$i] = $file_name;
01432  ** 
01433  ** @lim This overwrites globe::comment_file and globe::entire_file because
01434  ** it calls globe::read_code_n_comment. The information in these global
01435  ** variables is then immediately processed.
01436  **
01437  **/
01438 // #############################################################################
01439 int validate_and_fetch  ( ) {
01440    #define $f_name  $_[0]
01441    #define $tag_xml  $_[1]
01442    #define $targ_xml_tag  $_[2]
01443    #define $debug_v_n_f  0
01444    #define $temp_return  ""
01445    
01446    if ((0) && ($debug_v_n_f)) {
01447 //       print "v_n_f:f_name $f_name\n";
01448 //       print "v_n_f:tag_xml $tag_xml\n";
01449 //       print "v_n_f:targ_xml_tag $targ_xml_tag\n";
01450    }
01451    if ($debug_v_n_f) {
01452 //       print "v_n_f:targ_xml_tag $targ_xml_tag\n";
01453 //       print "v_n_f:return $globe::tag_mess{file}{$f_name}{$targ_xml_tag}\n";
01454    }
01455    
01456    if (exists ($globe::tag_mess{file}{$f_name})) {
01457       // ####
01458       //  Then we have already parsed the file for information.
01459       //  08/07/2002 However, the tags should be cummulative over many
01460       //  files. No longer such a thing as the same tag being unique
01461       //  just because it is in its own file. If the file's been
01462       //  parsed, the tag gets put into the pool.
01463       // ####
01464       if (exists ($globe::tag_mess{name}{$targ_xml_tag})) {
01465          for ($j=0; $j <= $// {$globe::tag_mess{name}{$targ_xml_tag}}; $j++) {
01466             $f_name = $globe::tag_mess{name}{$targ_xml_tag}[$j];
01467             $temp_return .= $globe::tag_mess{file}{$f_name}{$targ_xml_tag};
01468          }
01469          return ($temp_return);
01470       } else {
01471          //  File has been processed previously, but no tags exist.
01472          //  Hence, we should return with a zero.
01473          if ($debug_v_n_f) {
01474 //             print "v_n_f:targ_xml_tag $targ_xml_tag\n";
01475 //             print "v_n_f:2a Did not find tag\n";
01476          }
01477          return (0);
01478       }
01479    } else {
01480       // ####
01481       //  Then we have to see if that file is even valid and information
01482       //  out of it and into our data structure.
01483       // ####
01484       if ($debug_v_n_f) {
01485 //          print "v_n_f and pre-rcnc: $f_name\n";
01486       }
01487 
01488       if ((1) && (!(&globe::read_code_n_comment($f_name, 0)))){
01489          //  The 0 passed in means that we don't care what's in the file;
01490          //  we're going to find our tags no matter what.
01491          //  If this returns 0 and fails, it means that the file could not be
01492          //  found or opened.
01493          //  Hence, we should return with a zero.
01494          if ($debug_v_n_f) {
01495 //             print "v_n_f:targ_xml_tag $targ_xml_tag\n";
01496 //             print "v_n_f:return $globe::tag_mess{file}{$f_name}{$targ_xml_tag}\n";
01497 //             print "v_n_f:2 Did not find tag\n";
01498          }
01499          return (0);
01500       }   
01501       //  At this point, $globe::comment_file was created and populated,
01502       //  which is what we care about.
01503       //  $globe::entire_file was also created, but we don't care about it.
01504 
01505       if ((1) && (!(&globe::process_comments_from_file($f_name, $tag_xml)))){
01506 //          print "2 Processing comments from \"$f_name\" failed some things.\n";
01507       } 
01508       // ####
01509       //  At this point, $globe::comment_file has been parsed and
01510       //  can be overwritten.
01511       //  Also at this point, we have more things in the data structure.
01512       //  Supposedly, our target and data are there.
01513       // ####
01514 
01515       if (exists ($globe::tag_mess{file}{$f_name})) {
01516          //  Then we have already parsed the file for information.
01517          if (exists ($globe::tag_mess{file}{$f_name}{$targ_xml_tag})) {
01518             //  Then the tag name is valid and we can return what we
01519             //  have already stored. We need to return all occurrences
01520             //  in the data base, not just the one for this file.
01521             for ($j=0; $j <= $// {$globe::tag_mess{name}{$targ_xml_tag}}; $j++) {
01522                $f_name = $globe::tag_mess{name}{$targ_xml_tag}[$j];
01523                $temp_return .= $globe::tag_mess{file}{$f_name}{$targ_xml_tag};
01524             }
01525             return ($temp_return);
01526          } else {
01527             //  Then we did not find the desired tag name when we
01528             //  parsed the file. Return a 0.
01529             if ($debug_v_n_f) {
01530 //                print "v_n_f:targ_xml_tag $targ_xml_tag\n";
01531 //                print "v_n_f:3Did not find tag\n";
01532             }
01533             return (0);
01534          }
01535       } else {
01536          //  Maybe the file had no entries to merit an
01537          //  entry into our data structure. At this point, we
01538          //  tried our best to get the data and had none.
01539          return (0);
01540       }
01541    }
01542 } //  validate_and_fetch
01543 
01544 
01545 
01546 
01547 //#############################################################################
01548 /** @fn int do_errors  ( )
01549  ** @brief Prints out all accumulated error messages.
01550  ** @param None
01551  ** @return None
01552  ** 
01553  ** @lim None
01554  ** @ingroup tp_nav
01555  **/
01556 // #############################################################################
01557 int do_errors  ( ) {
01558    if (@globe::file_errors) {
01559 //       print "\n============  Summary of errors =============================globe\n";
01560       for ($i=0; $i<@globe::file_errors; $i++){
01561 //          print "$i = $globe::file_errors[$i]\n";
01562       }
01563    }
01564 }
01565 
01566 
01567 
01568 //#############################################################################
01569 /** @fn int END
01570  ** @brief Code to run at the end of this routine.
01571  **
01572  ** @param None. 
01573  **
01574  ** @return None.
01575  **
01576  ** @lim None
01577  ** @ingroup tp_tools
01578  **/
01579 // #############################################################################
01580 int END  ( ) {
01581    if (0) {
01582 //       print "globe.pm END routine.\n";
01583    }
01584 }
01585 
01586 


 "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