Re: [ANN] LuaHelp

[Luis Carvalho <lexcarvalho@...>]

Hi David,

Thank you for your comments.

<snip>
> - Is there a reason help.c is written in C rather than Lua?

I wanted to borrow the logic from Lua's module system, so I got lazy and
simply ripped a big chunk from loadlib.c. There might be some other reasons
since I recall coding LuaHelp in Lua and then switching to C, but this was
some time ago and I can't remember exactly the reasons...
 
> - What's the name of the syntax the help pages are written in?  It
> appears markdown inspired.

It *is* markdown.
 
> - One alternative to help"math.sqrt" is to support help(math.sqrt).
> [4] does the latter, and Python supports both [1-3] as well as things
> like help("keywords").  help(getname(math.sqrt)) might be another
> approach.  To distinguish package functions and object methods, e.g.
> io.write and file:write, I see LuaHelp currently uses help"io.write"
> and help"file.write", which could become ambiguous, though I'm not
> sure what the ideal way to uniquely name object methods is
> ("<io>:write"?).

I've changed LuaHelp a bit, based on your links and suggestions --- thank you.
You can now register any "keyable" Lua value (but nil, as it can not be used
as a table key) with a lhp (LuaHelp page). Objects with a __help metatable
key have the value from this key printed when called as argument to "help":

$ lua -lhelp
Lua 5.1.4  Copyright (C) 1994-2008 Lua.org, PUC-Rio
> function docobj (desc)
>>   local o = newproxy(true)
>>   getmetatable(o).__help = desc
>>   return function() return newproxy(o) end
>> end
> docfactory = docobj"Test object"
> o1 = docfactory()
> help(o1)
Test object
> help(setmetatable({}, {__help = "Table test"}))
Table test
> help.register(o1, "Special object")
> help(o1)
Special object
> help(docfactory())
Test object
> o1 = nil
> help(o1)
Sorry, help not available

As a consequence, you can also register any function so

> cache = debug.getfenv(help.register)
> help"math.sqrt" -- cache entry

math.sqrt (x)
-------------

  Returns the square root of `x`. (You can also use the expression `x^0.5` to
  compute this value.)

> help.register(math.sqrt, cache["math.sqrt"])
> help(math.sqrt)

math.sqrt (x)
-------------

  Returns the square root of `x`. (You can also use the expression `x^0.5` to
  compute this value.)


I've also added ":" as a valid separator, which should alleviate the ambiguity:

> help"file:write"

file:write (...)
----------------

  Writes the value of each of its arguments to `file`. The arguments must be
  strings or numbers. To write other values, use `tostring` or `string.format`
  before `write`.

 
> - Python invokes the pager (less) rather than just a print.  In Lua,
> someone can always redefine print to obtain a similar effect: function
> print(s) local f = io.popen("less", "w"); f:write(s); f:close() end .

Definitely. You can actually have "true" man pages by translating from
markdown to troff if needed. I could probably define help.print as the
"pager"...

Please check the latest version, 0.2-1, at

http://code.google.com/p/luahelp/downloads/list

Cheers,
Luis

-- 
Computers are useless. They can only give you answers.
                -- Pablo Picasso

-- 
Luis Carvalho (Kozure)
lua -e 'print((("lexcarvalho@NO.gmail.SPAM.com"):gsub("(%u+%.)","")))'