Latest Help System Code

Mike

Place a text file in the same location as the directory, .lua file, .wlua file, or .dll file. The file for xxx should be named xxx.help, the help system will substitute "To get more detailed help ..." for the string "{{explanation}}". Perhaps it would have been better to use "{{details}}".

To provide detailed help for an individual module, crate a sub-directory and put the .help files in it. For example if we have the module xxx.lua, the path for help with the module would be .\xxx.help (where . is the path to xxx.lua), while the detailed help for the yyy function will be .\xxx\yyy.help. All the user has to do is write text files and creare sub-directories. The script help.lua handles the rest, and if no help file is found, help.lua gracefully returns "No help available for " .. name rather than crashing.

Samir

Great idea !
Maybe that help system could parse html documentation to produce help on modules / functions / methods / properties.
I think to use that to programmatically obtain help on LuaRT with a 'help' module, returning strings :

local help = require "help"

local each_help, each_type = help.find("each")

Mike

I like that quite a bit. The basic code could be adapted to parse html, and we might make more extensive use of gsub. For my work on the system, I will continue using text files for now while I work out other issues about expanding the search path, to make it easier to search the app directory when running in interactive mode. (Works perfectly when required into a script.) Or might it be better to drop interactive mode entirely or put it in a separate script?

Samir

I think that the two methods could co-exist with different goals : one to give an interactive help system and another to give scripting capabilities based on the help system

Mike

That would seem best.

Mike

I've done some experimenting and it is possible to create an html string, write it to a file, and open it in your default browser. Proof of concept code:

local console = require("console")

local testhtml = "<html><body>This is a test.</body></html>"

local env = sys.env

local path = env.temp or env.tmp or "."

local file = sys.File(path .."\\test.html") 
path = file.fullpath
file = file:open("write")
file:write(testhtml)
file:close()
sys.cmd(path)`
```

Samir

HTML generation from the help system is a great idea. I like how you used sys.cmd() to open the generated HTML file 😉

Mike

I have devised a format for .help files which are basically Lua table contructors.

I have perfected auto-generating .txt files from .help files as required.

I am working on auto-generating .html files with working hyperlinks from help files.

Will post code when finished.

Mike

Auto-generation of .html files is done, except for links. Should finish in a day or two.

Mike

Links working. 😄 "\n" in a .help file will be gsub'ed to "<br>" for html.
I'm doing some code cleanup, and I will develop a tool to facilitate writing/editing .help files.
I will post links when I'm finished.

Mike

Just about finished with the tool.

Mike

The attached file is the completed help system (except for making the paths configurable). The following directory structure is assumed:
LuaRT is installed to C:\LuaRT and has the following subdirectories: lib, for .lua and .wlua files; clib for .dll files; and user for user scripts (in subdirectories of user).

With the next release where Directory:make() bug is fixed, I will create a simple configuration tool to specify the search paths, so any paths the user wishes can be searched.

But the code as given correctly generates help files from templates, in text or html format as requested, with working hyperlinks when a html help file is viewed in a browser.

[[Login to see the link]]

Samir

Sorry, i tried to run "luart helpconsole.lua" with the content of the zip file extracted to a "lib" directory in LuaRT installation folder. I have set the LUA_PATH before to "<luRT path>\lib\?\?.lua;<luRT path>\lib\?.lua"

I can execute helpconsole.lua, but every time it failed with "no help available" (I tried with words help, conslib, walkdir...)

By the way, it's very interesting ! You have convinced me to include a help system with luaRT !

Mike

I've done some more tinkering and I have provided a configuration utility which lets the user specify the the search paths. I will send an updated help system later today or tomorrow. The only assumption made is that all directories are subdirectories of a single root directory. (Which could even be C:\ , but the utility will run slowly in that case.)

The user will be presented with a list of paths, choose one and then chooses whether to search that directory, that directory's subdirectories, or both. The choice is repeated until the user indicates he's done, then the user is asked for the directory where the various files of the help system are located.

I will include a readme file with more detail about how it works.

Mike

Tonight or tomorrow I will send a revised zip file with more complete instructions.

Samir

Ok ! That's cool !
But take your time there's no need to hurry 😅

Mike

Just doing some final debugging.

Mike

The website was lagging, it took awhile to see my posts. Sorry for the duplicates.

Mike

Revised code:

[[Login to see the link]]