Re: Help function for lua

[William Ahern <william@...>]

On Thu, Jan 16, 2020 at 11:22:36AM -0700, bil til wrote:
> I think more like some "1 page function summary in documentation style", e.
> g. if you invoke "help(print)", or "help(for)", or "help(if)".
> 
> ... and there should be some "standard way" to support library suppliers who
> also want to supply such code for their lib functions, e. g.
> "help(lib.func)" or so ... ("help(string.unpack)", ....) .
> 
> .. the important thing would be, that it is somehow very simple invocation
> like "help(...)". ... if the user would need some more "sophisticated trick"
> to find variable information, then I think it would not be too useful... .
> 
> I think in many lua applications (e. g. lua on "large systems" like Windows,
> Linux, Android...), the "static size" of the code of lua is "ridiculously
> small", and in such case it really is no load at all, to include all such
> "function documentation" in the code.
> 
> In "controller applications", where storage space is sparse, of course this
> "including help info into code" should be switched off easily. And it would
> be very nice, if such "static help info" really then is linked to ROM in
> case controllers supporting ROM / RAM separated memory (e. g. RISC
> controllers). 

Why not just embed a link to the reference manual?

  $ help
  https://www.lua.org/manual/5.3/

  $ help"string.unpack"
  https://www.lua.org/manual/5.3/manual.html#pdf-string.unpack

One of the great things about Lua is the clear, concise, yet comprehensive
online manual, all in a single HTML page! The most useful thing a Lua
beginner can learn is to habitually look to the reference manual. That's
true for most languages[1], but *especially* true for Lua.

[1] As committee standards go, I think the ISO C standard is very nice, and
I have at least two dozen ISO and similar committee standards (exclusive of
RFCs) under ~/Desktop to compare it to, some of them costing a $100USD each.
The POSIX standard is also quit nice, but the HTML version uses frames,
which has its pros and cons. The Lua manual has a separate, single-page
table of contents/index, which provides all the benefits and none of the
downsides.