Contents 
 Index 
 "Perl Program Reference" 
 < Previous 
 Next > 

Navigation Tools

Swaps out navigation, creates temporary TOC files and index_ files. More...

Files

Functions


Detailed Description

Swaps out navigation, creates temporary TOC files and index_ files.


Function Documentation

int END  
 

Code to execute when first entered.

Parameters:
None. 
Returns:
None.
Limitations and Caveats:
None

Definition at line 689 of file asn_bapitypes.pl.

int change_nav  
 

Opens up an HTML file and replaces information between known tags.

Parameters:
in_file  is the HTML file to edit.
Returns:
Effectively writes back out to the same HTML file.
This function performs all tasks associated with updating the individual HTML file. It reads the entire HTML file into memory.

In general, this routine looks for paired HTML comments containing a tag name and "begin" or "end". Whatever is between these paired comments is replaced with the updated information extracted from the master. The sequence of replacements is:

  • If the HTML file has $globe::m_define{variable}[0], it means that it came from a FrameMaker book. As such, these variables contain information regarding the previous topic, next topic, whether or not it is a first topic or last topic for the chapter, etc. This information is extracted from the HTML file and placed into variables to be used by this topic.

  • Info in the file header is swapped out. If the tags aren't found, an appropriate spot for the new tags is created before the terminating head tag.

  • Info in the file footer is swapped out. If the tags aren't found, an appropriate spot for the new tags is created before the terminating body tag.

  • If the HTML file came from a FM book, replace the navigation bar associated with the book (the second navigation bar.) Although this navigation bar appears below the common navigation bar, it is swapped out first, because if the location tags aren't found, this routine finds an appropriate spot for the new tags immediately following the body tag. This is easy to spot.

  • If the HTML file came from Doxygen, replace the navigation bar associated with Doxygen topics (the second navigation bar.) Although this navigation bar appears below the common navigation bar, it is swapped out first, because if the location tags aren't found, this routine finds an appropriate spot for the new tags immediately following the body tag. This is easy to spot.

  • Replace the navigation bar common to all topics in the system. If the location tags aren't found, this routine finds an appropriate spot for the new tags immediately following the body tag. This is why this needs to happen after inserting either the FM navigation or the Doxygen navigation.

  • Sometimes HTML is generated by Doxygen or Mif2Go that hard-codes fonts or styles that cannot be controlled by a CSS. One of the lists that can be defined in the master file is a "zap" list. This is read into @globe::voy_html_zap hash. Each item in the zap list has three elements:
    1. start of the offending tag but incomplete.
    2. end of first offending tag.
    3. end of tag pairs.
    The HTML tags defined in the zap list get taken out of the HTML document.

  • Items in the header, footer, or navigation have items coming from the master that were not fully defined. Part of the voy_order provides the complete description. The HTML document gets the complete definition of these items. This includes:
    • PDF file name.
    • The name of the manual or group.
    • The document number.
    • Document title is changed to match the first heading.
  • The title is extracted into the index token list.

  • The headings are added to the index token list as well as the topic order list.

  • Object tags are how FM index tokens are passed to MS-HTML using Mif2Go. These are converted into special HTML comments. They are also extracted into the index token list.

  • If the file came from Doxygen, this parses out interesting items to add to the index token list.

    While processing the file, hash tables are created:

    • @globe::book_topics: key is html file name, <Title> is stored
    • @globe::book_topic_order: key is html file name, next html file is stored
    • @globe::book_topic_level: key is html file name, <Headn> is stored
    This is important in order to handle subsequent creation of the mini-TOC file (tree.html) in another routine.
    Limitations and Caveats:
    This is a big routine that accomplishes many different tasks while it has the HTML file in memory. Some of the items have to be handled in the order given for them to be swapped and positioned properly.

    Definition at line 720 of file voyant_nav.pl.

  • int do_dox_prev_next  
     

    Does a cheap previous/next for Doxygen files.

    Parameters:
    None 
    Returns:
    None
    Limitations and Caveats:
    None

    Definition at line 565 of file voyant_nav.pl.

    int generate_and_step_through_list  
     

    Generates list of files to look at.

    Parameters:
    None 
    Returns:
    None
    Limitations and Caveats:
    None

    Definition at line 508 of file voyant_nav.pl.

    int get_hyperlinks  
     

    Parses through the information in the globe::entire_file buffer for anchors.

    Parameters:
    _file_4_links  contains the fully qualified name of the file.
    _level  contains the level, or distance from, the root for use in assigning to the hyperlinks discovered.
    All qualified anchors represent children of the _file_4_links. This routine creates the children's url, display text, and level.

    This routine calls the routine verify_link, which has criteria to test against. The criteria is intended to make the qualification of the link fail. In other words, when it returns from verify_link with a failed (0) criteria, this get_hyperlinks routine knows that it should not add a child for that hyperlink.

    Limitations and Caveats:
    Assumes that $globe::entire_file has an HTML file in it.

    Definition at line 699 of file html_look_integrate.pl.

    int get_input_file  
     

    Grabs the information from the input file and puts into an array of hash elements.

    Parameters:
    file_incoming  This is the file to open.
    Reads in the file into memory for later processing to find anchors. While it's here, it tries to find the title for the file for later display and file naming purposes.

    Definition at line 590 of file html_look_integrate.pl.

    int handle_index_tokens  
     

    Traces through the data structure and outputs appropriate entries for the index.

    Parameters:
    begin_file  The starting point in the structure.
    Note:
    This is a RECURSIVE routine. It creates appropriate entries for each of the children into the globe::index_info data structure, which later gets output to a file.
    Limitations and Caveats:
    Does a convoluted thing to get the path to be truly integrated into the system. Also, it creates a helluva lot of entries for BSP (4022) before any word-chunking might be considered.

    Definition at line 1733 of file html_look_integrate.pl.

    Referenced by globe_file_cnt().

    int output_structure_script  
     

    The starting point for outputting the TOC script files.

    Parameters:
    _in_file  / htree_file the prefix of the name of the script file to output.
    trace_start_file  starting point in the data structure that has children to trace through.
    globe_path_purge  the key into the $globe::nav_path_purge hash, which contains paths to purge from the output hyperlinks in the TOC, etc.
    Note:
    This calls script_structure which is a recursive routine that traces through the data structure.

    Definition at line 1454 of file html_look_integrate.pl.

    int purge_full_path  
     

    Changes the file name by purging a portion of its path.

    Parameters:
    _filename  original filename.
    part2rm  portion of the path in the filename to remove.
    Returns:
    1 and the updated filename if successful; 0 and the unmodified filename if unsuccessful.

    Definition at line 1529 of file html_look_integrate.pl.

    int script_structure  
     

    Traces through the data structure following the children and creates entries into the script file for the TOC.

    Parameters:
    begin_file  is the point to start in the data structure.
    For every begin_file, this outputs entries into the already open OUTSCRIPT file for each of its children.

    Whenever a child is encountered, it is tested (using globe_found_files) to see if it has already been processed. This prevents it looping forever.

    If a given child has not been traced, this calls itself with that child.

    It was deemed desireable to still print out children entries even if we weren't going to trace them (because they already had been traced.)

    Note:
    This is a RECURSIVE routine. It stops when all children at that level have had appropriate entries made and none have been flagged to be traced.
    Limitations and Caveats:
    $globe_found_files{$begin_file} is used in a global way. $globe::nav_purge_path is also a global hash. The key into the hash ($globe_path_purge) was defined a level higher and used globally.

    Definition at line 1658 of file html_look_integrate.pl.

    int spider_trace  
     

    Traces the child hyperlinks of a starting file and places them into the data structure.

    Parameters:
    start_file  The starting HTML file to trace.
    This calls routines to open and read the children HTML files and to locate the appropriate hyperlinks within those files.
    Limitations and Caveats:
    This assumes that the data structure has already been started by having a root file, by having already opened it and acquired its children.

    Definition at line 1216 of file html_look_integrate.pl.

    int starting_point_script  
     

    Creates the top level TOC script that uses subscript references.

    Parameters:
    htree_file  The prefix of the script file to be output.
    which_script  The key into the hash for whether we're creating a "script_::define" or "script_master" script. This had the appropriate file names.
    which_purge_path  The key into the hash for the appropriate purge path depending upon whether or not this is a "define" or "master" version.
    This knows about the top level entries and what they should be named. The names have been added to the appropriate hash. It can generate the master script that calls subscripts depending upon which version we're doing.

    The difference between a define and master version are the paths for links. Normally, the other tools would handle this for me. However, because this is starting out already as a nested version, it does not integrate well. It is better to have this take care of all entries appropriately so that the other tools only has to integrate the top level script (through a master_nav file).

    Definition at line 1567 of file html_look_integrate.pl.

    int testing_structure  
     

    Traces through the created data structure.

    Parameters:
    begin_file  is the starting point to begin tracing.
    This assumes that the begin_file is present in the data structure and has children to trace through.

    Note:
    This is a RECURSIVE algorithm and can be used as a template for other recursive things involving the same data structure.

    Definition at line 1379 of file html_look_integrate.pl.

    int using_voy_nav  
     

    What to do when no arguments are given.

    Parameters:
    None 
    Returns:
    None
    Limitations and Caveats:
    None

    Definition at line 563 of file html_look_integrate.pl.

    Referenced by _arg_inc().

    int verify_link  
     

    Tests the potential link against various criteria to validate whether the link is of value.

    Parameters:
    potential_link  Contains a fully qualified hyperlink.
    contains  the owning file.
    Returns:
    If a criteria is matched, this routine returns 0 (meaning uninteresting link. If not of the criteria sets off a flag, this then returns the potential link as validated.
    Criteria that makes the link uninteresting are things like: linking to itself, up linking to a top-level entity, linking to an html topic that we want to exclude as being a child, linking to other children at the same level, etc.

    Definition at line 1014 of file html_look_integrate.pl.



     "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