Offline help file

Posted by Nick Gammon on Fri 13 Apr 2007 05:51 AM — 7 posts, 38,754 views.

Nick Gammon Australia Forum Administrator Fri 13 Apr 2007 05:51 AM #0

There have been some comments recently that the help file supplied with MUSHclient does not work under Windows Vista.

It seems that Microsoft has decided to stop supporting, or supplying, the help reader that was around for many previous versions.

As an interim measure, all of the topics in the help file are now available as separate .htm files, suitable for offline browsing with your web browser.

They have been generated from the same database used to make the original help file, and also the online version available at this web site.

Simply download this file (1.25 Mb):

http://www.gammon.com.au/files/mushclient/mushclient_help_4.03.zip

Then unzip it into some suitable location (eg. your MUSHclient install directory). You will find a single subdirectory called "html" with around 760 html files in it.

The main contents page is DOC_contents.htm, however it doesn't really matter which file you open, as there is a link to that page at the bottom of every page.

The files are named consistently, so for example, to get the documentation on GetInfo you look inside FNC_GetInfo.htm file.

Maxhrk USA Sun 15 Apr 2007 02:06 AM #1

you know.. you can make a custom help program just for your mushclient if microsoft don't support it anymore. :)

you know.. I need a search function to search throughout offline help to find what i want to find. heh. I am lazy yeah.

Nick Gammon Australia Forum Administrator Sun 15 Apr 2007 04:35 AM #2

Quote:

you can make a custom help program just for your mushclient if microsoft don't support it anymore

Yes, however I am lazy too. :)

Quote:

I need a search function to search throughout offline help to find what i want to find

Hmmm - this bit of code will do that. You need Lua scripting, and the "io" library enabled for the plugin or world where you put it. It also uses the windows_utils.dll which is available from:

http://www.gammon.com.au/files/mushclient/lua5.1_extras/windows_utils.zip

You could probably build it into an alias where the argument to the alias is the thing to search for.

Anyway, it demonstates a few useful things:

Quering the user for a string (the search string)
Finding all the files in a directory (the help files in this case)
Opening a file and reading all of it into memory
Getting rid of HTML tags (like <p>)
Converting HTML entities (like <) into their equivalents
Building up a list for a "choose from a list" dialog box
Processing the result
Opening an HTML file


-- help files path 
--  this is the MUSHclient.exe path with an html subdirectory

local help_path = GetInfo (66) .. "html\\"

-- ask what to search for
local search_for = utils.inputbox ("Phrase to search for", 
                           "Search help", previous_search or "")

if not search_for then
  return
end -- cancelled

search_for = Trim (search_for)

if #search_for == 0 then
  return  -- no string
end -- empty string

-- remember for next time
previous_search = search_for

-- get all help files
local files = assert (utils.readdir (help_path .. "*.htm"))

-- case-insensitive matches
search_for = string.upper (search_for)

-- list of matching files
local matching_files = {}

-- process each file
for fname in pairs (files) do
  local f = io.open (help_path .. fname, "r")  -- open it
  local s = f:read ("*a")  -- read all of it
  f:close ()  -- close it
  
  -- get rid of HTML tags
  s = string.gsub (s, "<.->", "")
  -- fix up entities (like &amp;)
  s = string.gsub (s, "&(%w-);", GetXMLEntity)
  -- case-insensitive
  s = string.upper (s)

  -- see if our search string is there
  if string.match (s, search_for, 1, true) then
    table.insert (matching_files, fname)
  end -- if found

end  -- each file

if #matching_files == 0 then
  utils.msgbox ("No matches")
  return
end -- nothing


local type_conversions = {
  FNC = " (function)",
  DOC = " (general)",
  DLG = " (dialog)",
  CMD = " (command)",
  LUA = " (Lua)",
  }

-- table for utils.listbox 
local choose_list = {}

-- build name/keys pairs, and add type of help
--  e.g. "FNC_ChatPersonal.htm" becomes "ChatPersonal (function)"

for _, filename in ipairs (matching_files) do
  local type, name = string.match (filename, "^(%w-)_([%w_.]+)%.htm")
  choose_list [filename] = name .. (type_conversions [type] or "")
end -- for loop

-- get them to choose one
result = utils.listbox ("Choose help file", "Help search", choose_list)

-- give up if no choice made
if not result then
  return
end -- if cancelled or no choice

-- open the help file
assert (package.loadlib ("windows_utils.dll", "luaopen_windows_utils")) ()
assert (windows_utils.shell_execute (help_path .. result))

Maxhrk USA Sun 15 Apr 2007 06:21 AM #3

execellent. thanks.

Nick Gammon Australia Forum Administrator Thu 26 Apr 2007 06:04 AM #4

A new help file is available for offline browsing - this is for version 4.06, and has individual pages for each Lua function.

http://www.gammon.com.au/files/mushclient/mushclient_help_4.06.zip

(1.59 Mb)

Nick Gammon Australia Forum Administrator Wed 25 Jul 2007 10:13 PM #5

A new help file is available for offline browsing - this is for version 4.15. This basically updates the help with the more recent functions and documentation fixes.

http://www.gammon.com.au/files/mushclient/mushclient_help_4.15.zip

(1.61 Mb)

Nick Gammon Australia Forum Administrator Wed 25 Jul 2007 10:52 PM #6

Whilst fiddling with Knoppix, and getting MUSHclient to work under Wine, I noticed an annoying aspect - the help file doesn't seem to work properly.

To work around that I downloaded the individual help files (in the .zip file mentioned above) and added the following alias to MUSHclient:


<aliases>
  <alias
   match="mchelp"
   enabled="y"
   send_to="12"
   sequence="100"
  >
  <send>-- help files path 
--  this is the MUSHclient.exe path with an html subdirectory

local help_path = GetInfo (66) .. "html\\\\"

-- ask what to search for
local search_for = utils.inputbox ("Phrase to search for", 
                           "Search help", previous_search or "")

if not search_for then
  return
end -- cancelled

search_for = Trim (search_for)

if #search_for == 0 then
  return  -- no string
end -- empty string

-- remember for next time
previous_search = search_for

-- get all help files
local files = assert (utils.readdir (help_path .. "*.htm"))

-- case-insensitive matches
search_for = string.upper (search_for)

-- list of matching files
local matching_files = {}

-- process each file
for fname in pairs (files) do
  local f = io.open (help_path .. fname, "r")  -- open it
  local s = f:read ("*a")  -- read all of it
  f:close ()  -- close it
  
  -- get rid of HTML tags
  s = string.gsub (s, "&lt;.-&gt;", "")
  -- fix up entities (like &amp;amp;)
  s = string.gsub (s, "&amp;(%%w-);", GetXMLEntity)
  -- case-insensitive
  s = string.upper (s)

  -- see if our search string is there
  if string.match (s, search_for, 1, true) then
    table.insert (matching_files, fname)
  end -- if found

end  -- each file

if #matching_files == 0 then
  utils.msgbox ("No matches")
  return
end -- nothing


local type_conversions = {
  FNC = " (function)",
  DOC = " (general)",
  DLG = " (dialog)",
  CMD = " (command)",
  LUA = " (Lua)",
  }

-- table for utils.listbox 
local choose_list = {}

-- build name/keys pairs, and add type of help
--  e.g. "FNC_ChatPersonal.htm" becomes "ChatPersonal (function)"

for _, filename in ipairs (matching_files) do
  local type, name = string.match (filename, "^(%%w-)_([%%w_.]+)%%.htm")
  choose_list [filename] = name .. (type_conversions [type] or "")
end -- for loop

-- get them to choose one
result = utils.listbox ("Choose help file", "Help search", choose_list)

-- give up if no choice made
if not result then
  return
end -- if cancelled or no choice

-- open the help file
os.execute ("/usr/bin/konqueror html/" .. result)
</send>
  </alias>
</aliases>

This executes the "konqueror" web browser to show the help file, once it is found.

The alias above is intended for Linux, it won't work under Windows.