home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / p2demo21.exe / PEL / NDXHELP.PEL < prev    next >
Text File  |  1995-03-31  |  17KB  |  636 lines
  1. # $Header:   P:\source\wmacros\ndxhelp.pev   1.19   31 Mar 1995 15:34:46   NOBLE  $
  2. # $Tabs:4 7$
  3.  
  4. ##############################################################################
  5. #
  6. #       Compuware Corporation
  7. #         31440 Northwestern Highway
  8. #           Farmington Hills, Michigan 48334-2564
  9. #
  10. #   This source code listing contains information that is
  11. #   proprietary to Compuware Corporation and may not be copied
  12. #   duplicated, translated, transmitted, stored, retrieved
  13. #   or in any manner or by any method conveyed or disclosed
  14. #   to a third party or parties without express written
  15. #   permission from Compuware Corporation.
  16. #
  17. #  
  18. ##############################################################################
  19.  
  20. #### $Workfile:   ndxhelp.pel  $: help stuff
  21.  
  22. global fast_help  = 0 # If this is not set to 0, the topic is not searched
  23.                       # for until after the user selects a help file from all
  24.                       # of the possible help files for that extension.
  25.                       # if it is 0, then the topic is searched for in each
  26.                       # ndx file to see if it is actually contained in the
  27.                       # help file before it is added to the list for the
  28.                       # user to choose from.
  29.  
  30. global first_help = 0 # If this is not set to 0 and fast_help is set to 0,
  31.                       # then the first ndx file that has an entry that
  32.                       # matches the desired topic is used and no other
  33.                       # ndx files are searched.
  34.  
  35. global function gui_help_index()
  36. {
  37.    if(isWindows())
  38.       display_help("Table Of Contents")
  39.    else
  40.       display_help("HelpIndex")
  41. }
  42.  
  43. global function gui_general_help()
  44. {
  45.    if(isWindows())
  46.       display_help("Table Of Contents");
  47.    else
  48.       display_help("introduction")
  49. }
  50.  
  51. global function gui_using()
  52. {
  53.    if(isWindows())
  54.       display_help("Help On Help");
  55.    else
  56.       display_help("HelpOnHelp")
  57. }
  58.  
  59. global function gui_tutorial()
  60. {
  61.    gui_nyi()
  62. }
  63.  
  64. global function gui_cobolhelp()
  65. {
  66.    display_help("verbs")
  67. }
  68.  
  69. #
  70. # display help on word that cursor is in or parameter
  71. #
  72.  
  73. global function display_help_item(item) 
  74. {
  75.    local symbol
  76.  
  77.    if ( !helpndx )
  78.       load_ndx_help()
  79.  
  80.    if (item)
  81.       symbol = item
  82.    else
  83.    {
  84.       symbol = left_symbol_under_cursor();
  85.       if(!symbol)
  86.       {
  87.          warning("No symbol under cursor.")
  88.          return
  89.       }
  90.    }
  91.  
  92.    if (!ndx_help(symbol))
  93.       display_help(symbol)
  94. }
  95.  
  96. local helpndx = 0
  97. local helporder
  98.  
  99. # this function will load all the .ndx files specified in the 
  100. # HELPNDX environment variable.  The DPATH, BOOKSHELF, HELP, PATH
  101. # and CPE environment variables are searched to locate the .ndx files
  102.  
  103. global function load_ndx_help(ndx, bookshelf, clear)
  104. {
  105.    local str, fn, i
  106.    local old_buf, buf
  107.    local locate_help_file
  108.    local index = 0
  109.    local sf    = SEARCH_FORWARD+SEARCH_REGEX
  110.  
  111.    if (argcount() >= 3 && clear)
  112.       delete helpndx
  113.    else
  114.    {
  115.       clear = 0
  116.       for (i in helporder)
  117.          index = max(index, i)
  118.    }
  119.  
  120.    if (argcount() >= 2 && length(ndx))
  121.    {
  122.       if (!clear && length(ENV ["HELPNDX"]))
  123.          ENV ["HELPNDX"] = ENV ["HELPNDX"] "+" ndx
  124.       else
  125.          ENV ["HELPNDX"] = ndx
  126.    }
  127.  
  128.    if (argcount() >= 1 && length(bookshelf))
  129.    {
  130.       if (!clear && length(ENV ["BOOKSHELF"]))
  131.         ENV ["BOOKSHELF"] = ENV ["BOOKSHELF"] ";" bookshelf
  132.       else
  133.         ENV ["BOOKSHELF"] = bookshelf
  134.    }
  135.  
  136.    if ( "HELPNDX" in ENV )
  137.    {
  138.       old_buf = current_buffer
  139.  
  140.       for (fn = strtok(ENV["HELPNDX"], /[ \t+,;]+/); fn != 0; fn = strtok())
  141.       {
  142.          if (!length(path_ext(fn)))
  143.             fn = fn ".ndx"
  144.  
  145.          locate_help_file = fn
  146.  
  147.          if ((fn = find_help_file(fn)))
  148.          {
  149.             helporder[index]     = fn
  150.             helpndx[fn].filename = fn
  151.             index++
  152.  
  153.             if (tolower(path_ext(fn)) == ".ndx")
  154.             {
  155.                if ( message_level == 0 )
  156.                   message("Processing %s...", fn)
  157.    
  158.                # load it into a system buffer
  159.                buf = create_buffer( "", fn, BUFFER_NO_UNDO+BUFFER_SYSTEM )
  160.                current_buffer = buf
  161.                goto_buffer_top()
  162.    
  163.                # load the extensions 
  164.                if (search("^[ \\t]*EXTENSIONS:\\c", sf))
  165.                {
  166.                   helpndx[fn].extensions = ltrim( trim(read_buffer()) )
  167.                   helpndx[fn].extensions = "<" tolower(helpndx[fn].extensions) ">"
  168.                   gsub(" ", ">|<", helpndx[fn].extensions)
  169.                }
  170.                else
  171.                   helpndx[fn].extensions  = "*"
  172.    
  173.                # load the description
  174.                if (search("^[ \\t]*DESCRIPTION:\\c", sf))
  175.                   helpndx[fn].description = ltrim(trim(read_buffer()))
  176.                else
  177.                   helpndx[fn].description = fn
  178.  
  179.                # load the help files (if any)
  180.                # (Note: This is a preditor extension to the OS/2 NDX
  181.                #        file definition and therefore can be placed
  182.                #        inside a comment to allow the NDX file to
  183.                #        be used with KwikINF)
  184.                if (search("^[ \\t]*FILES:\\c", sf) || \
  185.                    search("^[ \\t]*/\\*[ \\t]*FILES:\\c", sf))
  186.                {
  187.                   str = read_buffer()
  188.                   gsub(/\*\//, "", str)
  189.                   helpndx[fn].files = ltrim(trim(str))
  190.                }
  191.  
  192.                # see if there are any entries in this ndx file
  193.                helpndx[fn].has_entries = search( "^\\(", sf)
  194.  
  195.                current_buffer = old_buf
  196.                delete_buffer(buf)
  197.             }
  198.             else
  199.             {
  200.                helpndx[fn].extensions  = "*"
  201.                helpndx[fn].description = fn
  202.                helpndx[fn].has_entries = 0
  203.             }
  204.          }
  205.          else 
  206.             warning("Unable to locate " locate_help_file ". The file must exist in your DPATH.")
  207.       }
  208.       if ( message_level == 0 )
  209.          message("Processing complete.")
  210.    }
  211.    else
  212.       notify("No HELPNDX environment variable defined")
  213. }
  214.  
  215. #
  216. # ndx_help()
  217. #  will search for symbol in the currently loaded ndx files.
  218. #
  219. global function ndx_help(symbol, ndx_file)
  220. {
  221.    local cmd, pos, file, topic, show_it
  222.  
  223.    if ( symbol == "" )
  224.         symbol = symbol_under_cursor()
  225.  
  226.    if ( length(ndx_file) )
  227.       cmd = find_topic(ndx_file, symbol)
  228.    else
  229.       cmd = find_help(symbol)
  230.  
  231.    if (length(cmd))
  232.    {
  233.       if (!(show_it = match(cmd, /hlp/) && match(cmd, /view/)))
  234.             show_it = match(cmd, /winhelp/)
  235.  
  236.       if (show_it)
  237.       {
  238.          file  = ltrim(substr(cmd, RSTART+RLENGTH))
  239.          pos   = cindex(file, " ")
  240.          topic = ltrim(substr(file, pos + 1))
  241.          file  = prefix(file, pos - 1)
  242.  
  243.          if ( message_level == 0 )
  244.             message("Looking Up %s in %s...", topic, file)
  245.  
  246.          show_help(file, topic)
  247.       }
  248.       else
  249.       {
  250.          if ( message_level == 0 )
  251.             message("Executing %s...", cmd)
  252.  
  253.          system("@" cmd)
  254.       }
  255.       if ( message_level == 0 )
  256.          message("")
  257.  
  258.       return 1
  259.    }
  260.    return 0
  261. }
  262.  
  263. local function find_help(symbol)
  264. {
  265.    local i
  266.    local fn
  267.    local ext
  268.    local cmd
  269.    local dlgid
  270.    local bufext
  271.    local ndx_file
  272.    local hlp_file
  273.    local cmd_list[]
  274.    local found_list[]
  275.    local found       = 0
  276.  
  277.    for ( i in helporder )
  278.    {
  279.       fn     = helporder[i]
  280.       ext    = helpndx[fn].extensions
  281.       bufext = ltrim( path_ext(buffer_filename), "." )
  282.  
  283.       if ( ext == "*" || ext == "<*>" || match(bufext, ext) )
  284.       {
  285.          if (!fast_help)
  286.             cmd = find_topic(fn, symbol)
  287.  
  288.          if (fast_help || length(cmd))
  289.          {
  290.             found++
  291.             found_list[found] = fn
  292.  
  293.             if (!fast_help)
  294.             {
  295.                cmd_list[found] = cmd
  296.                if (first_help)
  297.                   break
  298.             }
  299.          }
  300.       }
  301.    }
  302.  
  303.    if ( found == 1 )
  304.    {
  305.       ndx_file = helpndx[found_list[found]].filename
  306.  
  307.       if (fast_help)
  308.          cmd = find_cmd(found, symbol)
  309.       else
  310.          cmd = cmd_list[found]
  311.    }
  312.    else if (found > 1)
  313.    {
  314.       dlgid = create_selection_dialog("Select a help file", 40)
  315.       for ( i in found_list )
  316.       {
  317.          set_dialog_item( dlgid, IDL_LIST, DAC_ADD_ITEM,
  318.                           helpndx[found_list[i]].description )
  319.       }
  320.  
  321.       new_response = ""
  322.       begin_dialog(dlgid)
  323.       if (length(new_response))
  324.       {
  325.          for ( i in found_list )
  326.          {
  327.             if ( helpndx[found_list[i]].description == new_response )
  328.             {
  329.                ndx_file = find_help_file(helpndx[found_list[i]].filename)
  330.                if (fast_help)
  331.                   cmd = find_cmd(ndx_file, symbol)
  332.                else
  333.                   cmd = cmd_list[i]
  334.             }
  335.          }
  336.       }
  337.       delete_dialog(dlgid)
  338.    }
  339.    return cmd
  340. }
  341.  
  342. local function find_cmd(ndx_file, symbol)
  343. {
  344.    local hlp_file
  345.    local cmd      = find_topic(ndx_file, symbol)
  346.  
  347.    if (!length(cmd))
  348.    {
  349.       if (!isWindows())
  350.          hlp_file = find_help_file(path_fname(ndx_file) ".inf")
  351.  
  352.       if (!length(hlp_file))
  353.          hlp_file = find_help_file(path_fname(ndx_file) ".hlp")
  354.  
  355.       if (length(hlp_file))
  356.       {
  357.          if(isWindows())
  358.             cmd = "winhelp " hlp_file " " symbol
  359.          else
  360.             cmd = "view "    hlp_file " " symbol
  361.       }
  362.    }
  363.    return cmd
  364. }
  365.  
  366. local function find_topic(ndx_file, symbol)
  367. {
  368.    local hlp_file
  369.  
  370.    local cmd      = ""
  371.    local oldbuf   = current_buffer
  372.    local buf      = create_buffer( "", ndx_file, BUFFER_NO_UNDO+BUFFER_SYSTEM )
  373.    local sf       = SEARCH_FORWARD+SEARCH_REGEX
  374.    local excluded = 0
  375.  
  376.    current_buffer = buf
  377.    goto_buffer_top()
  378.  
  379.    if ( message_level == 0 )
  380.       message("Searching %s...", ndx_file)
  381.  
  382.    if (tolower(path_ext(ndx_file)) == ".ndx")
  383.    {
  384.       if (helpndx[ndx_file].has_entries)
  385.       {
  386.          if (search("^[ \\t]*\\([ \\t]*" quote_regex(symbol), sf))
  387.          {
  388.             goto_bol()
  389.             cmd      = get_help_cmd(symbol)
  390.             excluded = !length(cmd)
  391.          }
  392.          else if (!(excluded = is_topic_excluded(symbol)))
  393.          {
  394.             # Only dig through the ndx file while there be wildcards there.
  395.  
  396.             goto_buffer_top()
  397.             while (search("^[ \\t]*\\(.*\\*", sf))
  398.             {
  399.                goto_bol()
  400.                cmd = get_help_cmd(symbol)
  401.                if (length(cmd))
  402.                   break
  403.                else
  404.                   sf = or(sf, SEARCH_ADVANCE)
  405.             }
  406.          }
  407.       }
  408.       else
  409.          excluded = is_topic_excluded(symbol)
  410.  
  411.       if (!length(cmd) && !excluded)
  412.       {
  413.          if (length(helpndx[ndx_file].files))
  414.             cmd = search_help_files(helpndx[ndx_file].files, symbol)
  415.          else if (!helpndx[ndx_file].has_entries)
  416.          {
  417.             if (!isWindows())
  418.                hlp_file = find_help_file(path_fname(ndx_file) ".inf")
  419.  
  420.             if (!length(hlp_file))
  421.                hlp_file = find_help_file(path_fname(ndx_file) ".hlp")
  422.  
  423.             if (length(hlp_file))
  424.                cmd = search_help_files(hlp_file, symbol)
  425.          }
  426.  
  427.          if (!and(buffer_flags, BUFFER_READ_ONLY))
  428.          {
  429.             if (!helpndx[ndx_file].has_entries &&
  430.                 !length(helpndx[ndx_file].files))
  431.             {
  432.                helpndx[ndx_file].files = ndx_file
  433.                goto_buffer_bottom()
  434.                if (current_column != 1)
  435.                   insert_newline()
  436.    
  437.                insert_string("/* FILES: " ndx_file " */")
  438.                insert_newline()
  439.             }
  440.    
  441.             if (length(helpndx[ndx_file].files))
  442.             {
  443.                if (length(cmd))
  444.                {
  445.                   goto_buffer_bottom()
  446.                   if (current_column != 1)
  447.                      insert_newline()
  448.  
  449.                   insert_string("(" symbol ", " cmd ")")
  450.                   insert_newline()
  451.                   write_buffer()
  452.                }
  453.                else
  454.                {
  455.                   goto_buffer_bottom()
  456.                   if (current_column != 1)
  457.                      insert_newline()
  458.  
  459.                   insert_string("/* EXCLUDE: " symbol " */")
  460.                   insert_newline()
  461.                   write_buffer()
  462.                }
  463.             }
  464.          }
  465.       }
  466.    }
  467.    else
  468.    {
  469.       if (search(symbol, SEARCH_FORWARD))
  470.       {
  471.          if(isWindows())
  472.             cmd = "winhelp " ndx_file " " symbol
  473.          else
  474.             cmd = "view "    ndx_file " " symbol
  475.       }
  476.    }
  477.  
  478.    current_buffer = oldbuf 
  479.    delete_buffer(buf)
  480.  
  481.    if ( message_level == 0 )
  482.       message("")
  483.  
  484.    return cmd
  485. }
  486.  
  487. # Search through Excluded key-words.
  488. # (Note: This is a preditor extension to the OS/2 NDX
  489. #        file definition and therefore can be placed
  490. #        inside a comment to allow the NDX file to
  491. #        be used with KwikINF)
  492. #
  493. local function is_topic_excluded(symbol)
  494. {
  495.    local str
  496.    local sf  = SEARCH_FORWARD+SEARCH_REGEX
  497.  
  498.    goto_buffer_top()
  499.    while (search("^[ \\t]*EXCLUDE:\\c", sf) || \
  500.           search("^[ \\t]*/\\*[ \\t]*EXCLUDE:\\c", sf))
  501.    {
  502.       str = read_buffer()
  503.       gsub(/\*\//, "", str)
  504.       if (match(str, "[ \\t,+]*" quote_regex(symbol) "[ \\t,+]*"))
  505.          return TRUE
  506.    }
  507.    return FALSE
  508. }
  509.  
  510. local function get_help_cmd(symbol)
  511. {
  512.    local arr[]
  513.    local i, item, file, path, show_it
  514.  
  515.    local found  = 0
  516.    local cmd    = ""
  517.    local ln     = read_buffer()
  518.  
  519.    split(ln, arr, "\\(")
  520.    for ( i in arr )
  521.    {
  522.       ln = ltrim(arr[i])
  523.       if ( match(ln, ".+,") )
  524.       {
  525.          item = substr(ln, RSTART, RLENGTH-1)
  526.          ln   = ltrim(substr(ln, RSTART+RLENGTH))
  527.    
  528.          match(ln, ".+\\)")
  529.          cmd  = substr(ln, RSTART, RLENGTH-1)
  530.    
  531.          # adjust for any regular expression characters contained in
  532.          # the item name (except for * which has special meaning 
  533.          gsub("\\\\", "\\\\", item)
  534.          gsub("\\^",  "\\^",  item)
  535.          gsub("\\$",  "\\$",  item)
  536.          gsub("\\.",  "\\.",  item)
  537.          gsub("\\[",  "\\[",  item)
  538.          gsub("\\]",  "\\]",  item)
  539.          gsub("\\|",  "\\|",  item)
  540.          gsub("\\(",  "\\(",  item)
  541.          gsub("\\)",  "\\)",  item)
  542.          gsub("\\{",  "\\{",  item)
  543.          gsub("\\}",  "\\}",  item)
  544.          gsub("\\+",  "\\+",  item)
  545.          gsub("\\?",  "\\?",  item)
  546.          gsub("\\<",  "\\<",  item)
  547.          gsub("\\>",  "\\>",  item)
  548.          gsub("\\*",  ".*",   item)
  549.    
  550.          item = "<" item ">"
  551.          if ( match(symbol, item) )
  552.          {
  553.             if(isWindows())
  554.             {
  555.                gsub(/\.inf/, ".hlp", cmd)
  556.    
  557.                if (!(show_it = match(cmd, /view/)))
  558.                      show_it = match(cmd, /winhelp/)
  559.    
  560.                if (show_it)
  561.                {
  562.                   file = ltrim(substr(cmd, RSTART+RLENGTH))
  563.                   file = prefix(file, cindex(file, " ") - 1)
  564.                   path = find_help_file(file)
  565.                   if (length(path))
  566.                      gsub(file, path, cmd)
  567.                }
  568.             }
  569.             gsub("~", symbol, cmd)
  570.             found = 1
  571.             break
  572.          }
  573.       }
  574.    }
  575.    return found ? cmd : ""
  576. }
  577.  
  578. local function search_help_files(files, symbol)
  579. {
  580.    local fn, buf, old_buf
  581.    local found = 0
  582.    local cmd   = ""
  583.  
  584.    old_buf = current_buffer
  585.  
  586.    for (fn = strtok(files, /[ \t+,;]+/); (fn = strtok()); )
  587.    {
  588.       fn = find_help_file(fn)
  589.  
  590.       if ( message_level == 0 )
  591.          message("Checking %s...", fn)
  592.  
  593.       buf = create_buffer( "", fn, BUFFER_NO_UNDO+BUFFER_SYSTEM )
  594.       current_buffer = buf
  595.       goto_buffer_top()
  596.       found = search(symbol, SEARCH_FORWARD)
  597.       delete_buffer(buf)
  598.  
  599.       if (found)
  600.       {
  601.          if(isWindows())
  602.             cmd = "winhelp " fn " " symbol
  603.          else
  604.             cmd = "view "    fn " " symbol
  605.          break
  606.       }
  607.    }
  608.  
  609.    current_buffer = old_buf 
  610.    return cmd
  611. }
  612.  
  613. local function find_help_file(file)
  614. {
  615.    local path
  616.    if (length(file))
  617.    {
  618.       if (length(findfirst(file)))
  619.          path = file
  620.       else
  621.       {
  622.          if (!(path = search_path(file, "DPATH;BOOKSHELF;HELP;PATH;CPE")))
  623.          {
  624.             path = editor_path() file
  625.             if (!length(findfirst(path)))
  626.             {
  627.                path = editor_path() "help\\" file
  628.                if (!length(findfirst(path)))
  629.                   path = ""
  630.             }
  631.          }
  632.       }
  633.    }
  634.    return path
  635. }
  636.