Register forum user name Search FAQ

Gammon Forum

Notice: Any messages purporting to come from this site telling you that your password has expired, or that you need to verify your details, confirm your email, resolve issues, making threats, or asking for money, are spam. We do not email users with any such messages. If you have lost your password you can obtain a new one by using the password reset link.
 Entire forum ➜ MUSHclient ➜ General ➜ Help database supplied with MUSHclient version 4.76+

Help database supplied with MUSHclient version 4.76+

It is now over 60 days since the last post. This thread is closed.     Refresh page


Posted by Nick Gammon   Australia  (23,120 posts)  Bio   Forum Administrator
Date Tue 12 Jul 2011 03:42 AM (UTC)
Message
There are some problems with the help file supplied with MUSHclient these days. The help file itself is basically sound, but it uses a format that is no longer supported by Windows XP, Vista, Windows 7 etc.

As a work-around, version 4.76 onwards of MUSHclient will have the entire "raw" help database supplied as a SQLite3 database called help.db in the main MUSHclient directory.

Since SQLite3 supports FTS (full text search) then you can make a plugin that does sophisticated boolean searches of the help files (eg. "alias NEAR trigger", "alias NOT trigger" or "alias AND trigger AND add").

The help database is a little idiosyncratic in design, for historical reasons, however an example plugin will be shipped that shows how you might extract usable data from it.

The example plugin (currently) just outputs help information to the main output window, however it could be amended to use a miniwindow, or maybe generate HTML files for use in your web browser.

You can use the "snippet" feature of the FTS search to generate snippets of the help to show the context. For example, searching for "alias NEAR trigger":


Functions

 BroadcastPlugin - Broadcasts a message to all installed plugins
 ... of message (eg. trigger has fired = 1, alias matched = 2 ... 

 DeleteLines - Clears some recent lines from the output window.
 ... call DeleteLines from a trigger, alias or timer using send ... 

 ExportXML - Exports a world item in XML format
 ... lets you export one trigger, timer, alias, macro, keypad item ... 


One possible way of displaying the help would be to combine the FTS searches with the utils.filterpicker function. This lets you filter output dynamically at runtime based on what is typed into the filter box. Thus you could refresh the help topics shown based on what is typed into the filter.

- Nick Gammon

www.gammon.com.au, www.mushclient.com
Top

Posted by Nick Gammon   Australia  (23,120 posts)  Bio   Forum Administrator
Date Reply #1 on Tue 12 Jul 2011 04:41 AM (UTC)

Amended on Sat 16 Jul 2011 04:27 AM (UTC) by Nick Gammon

Message
The help database does not ship with the FTS tables created, to save space. These tables can be quickly created the first time the database is accessed, for example in a plugin's OnPluginInstall function:


-- for fixing up entities
local entities = {
  ["&lt;"]    = "<";
  ["&gt;"]    = ">";
  ["&amp;"]   = "&";
  ["&quot;"]  = "\"";
  } -- end of entities

local function fix_description (s)
  if not s then
    return ""
  end -- if
  
  -- get rid of tags 
  s = s:gsub ("</?%a+/?>", "")
  
  -- convert entities ...
  s = s:gsub ("&%a-;", entities)

  return s
end -- fix_description

function OnPluginInstall ()
  -- open database on disk 
  
  if not db then
    db = assert (sqlite3.open(GetInfo (66) .. "help.db"))
  end -- if
  
  local commands = false
  
  -- see if commands table exists
  for row in db:nrows("SELECT * FROM sqlite_master WHERE type = 'table' AND name = 'commands'") do 
    commands = true
  end
  
  if not commands then
    ColourNote ("red", "", "MUSHclient help database 'help.db' not found.")
    db:close ()
    db = nil
    return
  end -- if
  
  local fts4 = false
  
  -- see if fts4 tables exist
  for row in db:nrows("SELECT * FROM sqlite_master WHERE type = 'table' AND name = 'commands_lookup'") do 
    fts4 = true
  end

    -- if no fts4 tables, make them
  if not fts4 then
    local start = utils.timer ()
    ColourNote ("cyan", "", "Creating help database full-text lookup tables ...")
    
    -- START
    assert (db:execute [[
      BEGIN TRANSACTION;
      DROP TABLE IF EXISTS commands_lookup;
      DROP TABLE IF EXISTS dialogs_lookup;
      DROP TABLE IF EXISTS functions_lookup;
      DROP TABLE IF EXISTS general_doc_lookup;
      DROP TABLE IF EXISTS errors_lookup;
      DROP TABLE IF EXISTS lua_functions_lookup;
    ]])
    
    -- COMMANDS
    assert (db:execute "CREATE VIRTUAL TABLE commands_lookup USING FTS4(name, summary, description)")

    -- fix up HTML stuff
    for row in db:nrows("SELECT command_name, short_description, description FROM commands") do 
      assert (db:execute (string.format ([[
      INSERT INTO commands_lookup (name, summary, description) 
             VALUES (%s, %s, %s)]], 
             fixsql (row.command_name), 
             fixsql (row.short_description),
             fixsql (fix_description (row.description)))))
    end -- for
        
    -- DIALOGS
    assert (db:execute "CREATE VIRTUAL TABLE dialogs_lookup USING FTS4(name, summary, description)")

    -- fix up HTML stuff
    for row in db:nrows("SELECT dialog_name, title, description FROM dialogs") do 
      assert (db:execute (string.format ([[
      INSERT INTO dialogs_lookup (name, summary, description) 
             VALUES (%s, %s, %s)]], 
             fixsql (row.dialog_name), 
             fixsql (row.title),
             fixsql (fix_description (row.description)))))
    end -- for
        
    -- WORLD FUNCTIONS
    assert (db:execute "CREATE VIRTUAL TABLE functions_lookup USING FTS4(name, summary, description, lua_example, lua_notes)")
    assert (db:execute [[INSERT INTO functions_lookup (name, summary, description, lua_example, lua_notes) 
                         SELECT name, summary, description, lua_example, lua_notes FROM functions]])
        
    -- GENERAL TOPICS
    assert (db:execute "CREATE VIRTUAL TABLE general_doc_lookup USING FTS4(name, summary, description)")

    -- fix up HTML stuff
    for row in db:nrows("SELECT doc_name, title, description FROM general_doc") do 
      assert (db:execute (string.format ([[
      INSERT INTO general_doc_lookup (name, summary, description) 
             VALUES (%s, %s, %s)]], 
             fixsql (row.doc_name), 
             fixsql (row.title),
             fixsql (fix_description (row.description)))))
    end -- for
        
    -- ERRORS
    assert (db:execute "CREATE VIRTUAL TABLE errors_lookup USING FTS4(name, error_code, description)")
    assert (db:execute [[INSERT INTO errors_lookup (name, error_code, description) 
                         SELECT error_name, error_code, meaning FROM errors ]])
        
    -- LUA FUNCTIONS
    assert (db:execute "CREATE VIRTUAL TABLE lua_functions_lookup USING FTS4(name, summary, description)")
    
    -- fix up HTML stuff
    for row in db:nrows("SELECT name, summary, description FROM lua_functions") do 
      assert (db:execute (string.format ([[
      INSERT INTO lua_functions_lookup (name, summary, description) 
             VALUES (%s, %s, %s)]], 
             fixsql (row.name), 
             fixsql (row.summary),
             fixsql (fix_description (row.description)))))
    end -- for
    
    -- DONE
    assert (db:execute "COMMIT;")
    ColourNote ("cyan", "", string.format ("Done. Took %0.3f seconds.", utils.timer () - start))
    
  end -- if 
    
end -- OnPluginInstall


On my PC this took about 0.2 seconds to run.

[EDIT] Modified FTS creation to remove tags like <code> from the lookup database (otherwise you see annoying things like <code> in the snippets). Also convert &lt; to < and so on.

Also modified to check that the database is present (by checking for the "commands" table). SQLite3 tends to create an empty database on opening, so the fact that the open succeeds does not guarantee you have any tables present.

- Nick Gammon

www.gammon.com.au, www.mushclient.com
Top

Posted by Fiendish   USA  (2,533 posts)  Bio   Global Moderator
Date Reply #2 on Tue 12 Jul 2011 05:55 AM (UTC)
Message
You could convert the help to a pdf via HLP->CHM->PDF converters.

https://github.com/fiendish/aardwolfclientpackage
Top

Posted by Nick Gammon   Australia  (23,120 posts)  Bio   Forum Administrator
Date Reply #3 on Tue 12 Jul 2011 06:07 AM (UTC)
Message
I quite like the idea of full-text searches. Of course this doesn't stop you doing what you suggested.

- Nick Gammon

www.gammon.com.au, www.mushclient.com
Top

Posted by Fiendish   USA  (2,533 posts)  Bio   Global Moderator
Date Reply #4 on Tue 12 Jul 2011 07:13 AM (UTC)
Message
A pdf from html should be fully searchable.

https://github.com/fiendish/aardwolfclientpackage
Top

Posted by Nick Gammon   Australia  (23,120 posts)  Bio   Forum Administrator
Date Reply #5 on Tue 12 Jul 2011 08:15 AM (UTC)
Message
To be honest with you Fiendish, I've never really warmed to the PDF file format. Certainly it is great that it spans operating system boundaries, and is a way of distributing data in a "universal" way ... but the thing that troubles me is that PDF files are organized into pages.

Books have pages. Newspapers have pages. Computers don't.

When I am reading the PDF file that tells me about the Atmega328 processor frequently there are "page breaks" in totally meaningless positions, like in the middle of a description about how to control interrupts. The concept of "page breaks" is a paradigm that doesn't translate into computer screens.

Then you have "US Letter" documents that won't print on my A4 paper because the PDF file is designed around the paper that you happen to use in the USA. That isn't portable.

And the searching of them is often somewhat hard to figure out - certainly you can search, but in a somewhat random way.

I don't know, it's hard to explain. It's like PDF was designed by someone that really likes paper books, but was told to make them electronic, without really considering that books are supposed to convey information, and that the fact that they are in pages was a limitation of the medium, not something that should be lovingly preserved in the new format.

Quote:

A pdf from html should be fully searchable.


I presume your use of "should be" was not without some regard to the limitations of the medium?

- Nick Gammon

www.gammon.com.au, www.mushclient.com
Top

Posted by Nick Gammon   Australia  (23,120 posts)  Bio   Forum Administrator
Date Reply #6 on Wed 13 Jul 2011 01:24 AM (UTC)
Message
An example plugin for searching the help database will be included in version 4.76 onwards. This lets you type "mchelp <whatever>" and have your phrase searched for in general help, functions help, and Lua function help.

An example below shows what you see if you type "mchelp miniwindow":



You can also request "snippets" which shows the context in which the word(s) appear (like Google does) by using mchelps, for example "mchelps delete from":



If you click on one of the displayed hyperlinks you see the help for the desired topic (eg. DeleteTimer):




You could adapt the plugin to show help elsewhere, like a miniwindow. However even as distributed, the inline help can be useful if you are scripting, as you can copy and paste examples directly from the help, and especially so if the inbuilt help system is not working properly.

- Nick Gammon

www.gammon.com.au, www.mushclient.com
Top

Posted by Worstje   Netherlands  (899 posts)  Bio
Date Reply #7 on Wed 13 Jul 2011 01:46 AM (UTC)
Message
Why not output a .CHM file, which has been supported since Windows 978 if I recall correctly? There's tons of different help-creation packages out there, and I'm sure there's a .chm compiler somewhere out there as well.
Top

Posted by Twisol   USA  (2,257 posts)  Bio
Date Reply #8 on Wed 13 Jul 2011 02:25 AM (UTC)
Message
Worstje said:
Windows 978

We're still on Windows 7 here in prehistoric times, but thanks for dropping by, Future Guy!

'Soludra' on Achaea

Blog: http://jonathan.com/
GitHub: http://github.com/Twisol
Top

Posted by Nick Gammon   Australia  (23,120 posts)  Bio   Forum Administrator
Date Reply #9 on Wed 13 Jul 2011 02:51 AM (UTC)
Message
Worstje said:

Why not output a .CHM file, which has been supported since Windows 978 if I recall correctly? There's tons of different help-creation packages out there, and I'm sure there's a .chm compiler somewhere out there as well.


I seem to recall that someone a while back was working on exactly that, they had it "half done" and then went very quiet.

I think I tried that conversion myself a while ago, and whilst it sort-of worked, I wasn't too happy with the end result.

- Nick Gammon

www.gammon.com.au, www.mushclient.com
Top

Posted by Twisol   USA  (2,257 posts)  Bio
Date Reply #10 on Wed 13 Jul 2011 03:00 AM (UTC)
Message
Nick Gammon said:
I seem to recall that someone a while back was working on exactly that, they had it "half done" and then went very quiet.

*whistles innocently*

'Soludra' on Achaea

Blog: http://jonathan.com/
GitHub: http://github.com/Twisol
Top

The dates and times for posts above are shown in Universal Co-ordinated Time (UTC).

To show them in your local time you can join the forum, and then set the 'time correction' field in your profile to the number of hours difference between your location and UTC time.


29,953 views.

It is now over 60 days since the last post. This thread is closed.     Refresh page

Go to topic:           Search the forum


[Go to top] top

Information and images on this site are licensed under the Creative Commons Attribution 3.0 Australia License unless stated otherwise.