Online Help in eLua?

[jbsnyder]

I'm not suggesting this for the current release, but I was playing  
around with enumerating the tables for our hardware modules and it  
gave me a thought.

Is there a plan or interest in using metatables to provide simple help  
information for module methods?  I know something like this could  
always quickly grow into something that consumes many kilobytes of  
space, but what about just optional really short descriptions, like  
the following:

 > help(adc.setclock)
setclock( id, clock, [timer_id] ) -- set clock and timer_id for  
channel id

or even just the parameter list:
 > help(adc.setclock)
setclock( id, clock, [timer_id] )

Doing some sort of programmatic generation of the list, I think, would  
be key to make it maintainable.

Maybe this could even be extended so that the documentation could be  
kept inline in the module source and have a script that will take take  
these elements and populate the webbook docs.

Just a thought :-)   I like the idea of only having to update  
documentation in one place and have it be usable in multiple  
contexts.  I'm not thinking it should be too rigid or have a million  
fields that need to be populated, more something that is as simple as  
possible.

--
James Snyder
Biomedical Engineering
Northwestern University
[hidden email]
http://fanplastic.org/key.txt

_______________________________________________
Elua-dev mailing list
[hidden email]
https://lists.berlios.de/mailman/listinfo/elua-dev

[Dado Sutter]

Hello,
   I had thought about a "help module" once. It would not depend on modules's metatables (to be implemented by each new module) but would be a separate module and have something like your help() function.
   The problem is that, with our current main target boards, we just can't affoard so much ram and even flash. (Remember, some crazy guys are talking seriously about eLua on 8 bits :)
   If architectured as an optional module, it could be interesting to have in the next generation of chips/boards, that promisse to come with plenty of space to play with. (they are actually out there already ! :)
   We also want to concentrate the doc in a single place and the move we've made (comming on v0.6) to webbook proves that. But not all the project's "doc" is related to the modules, their functions or even the code implementation. This would be more of a "Reference Manual", which is one of the sections of the new "site/doc".
   I'm not sure if Bogdan will care too much about documenting the core code, other than keeping it clear and "self-documented". But it will be nice to hear some more opinions on this too.
   Thanks for the thread Snyder.

Best
Dado

On Tue, Mar 10, 2009 at 15:17, James Snyder <[hidden email]> wrote:

I'm not suggesting this for the current release, but I was playing around with enumerating the tables for our hardware modules and it gave me a thought.

Is there a plan or interest in using metatables to provide simple help information for module methods?  I know something like this could always quickly grow into something that consumes many kilobytes of space, but what about just optional really short descriptions, like the following:

> help(adc.setclock)
setclock( id, clock, [timer_id] ) -- set clock and timer_id for channel id

or even just the parameter list:
> help(adc.setclock)
setclock( id, clock, [timer_id] )

Doing some sort of programmatic generation of the list, I think, would be key to make it maintainable.

Maybe this could even be extended so that the documentation could be kept inline in the module source and have a script that will take take these elements and populate the webbook docs.

Just a thought :-)   I like the idea of only having to update documentation in one place and have it be usable in multiple contexts.  I'm not thinking it should be too rigid or have a million fields that need to be populated, more something that is as simple as possible.

--
James Snyder
Biomedical Engineering
Northwestern University
[hidden email]
http://fanplastic.org/key.txt

_______________________________________________
Elua-dev mailing list
[hidden email]
https://lists.berlios.de/mailman/listinfo/elua-dev

_______________________________________________
Elua-dev mailing list
[hidden email]
https://lists.berlios.de/mailman/listinfo/elua-dev

[jbsnyder]

On Mar 10, 2009, at 1:44 PM, Dado Sutter wrote:

Hello,
   I had thought about a "help module" once. It would not depend on modules's metatables (to be implemented by each new module) but would be a separate module and have something like your help() function.
   The problem is that, with our current main target boards, we just can't affoard so much ram and even flash. (Remember, some crazy guys are talking seriously about eLua on 8 bits :)
   If architectured as an optional module, it could be interesting to have in the next generation of chips/boards, that promisse to come with plenty of space to play with. (they are actually out there already ! :)

Right, and it could be traded for functionality on space-impaired platforms.

I'm not sure how large this would end up being if it were really kept as simple as possible, but space is always at a premium :-)

   We also want to concentrate the doc in a single place and the move we've made (comming on v0.6) to webbook proves that. But not all the project's "doc" is related to the modules, their functions or even the code implementation. This would be more of a "Reference Manual", which is one of the sections of the new "site/doc".

This is true.  What I was thinking of was less something that would regenerate the docs from scratch and more something that would parse documentation strings in the code and the HTML in the docs and update text sections in the HTML they didn't match the code.  This way could could selectively slave parts of the HTML documentation contents off of descriptions in the code.

I suppose something like this could also run the other way.  If the reference manual HTML is regularized enough, you could scrape the module documentation from the html and generate some sort of packed doc that could live in romfs or on an SD card, and then you could get your documentation from there.  This might be the easiest solution and keeps the webbook docs as the master.

--

James Snyder

Biomedical Engineering

Northwestern University

[hidden email]

http://fanplastic.org/key.txt

_______________________________________________
Elua-dev mailing list
[hidden email]
https://lists.berlios.de/mailman/listinfo/elua-dev

[BogdanM]

On Tue, Mar 10, 2009 at 8:17 PM, James Snyder <[hidden email]> wrote:

I'm not suggesting this for the current release, but I was playing around with enumerating the tables for our hardware modules and it gave me a thought.

Is there a plan or interest in using metatables to provide simple help information for module methods?  I know something like this could always quickly grow into something that consumes many kilobytes of space, but what about just optional really short descriptions, like the following:

> help(adc.setclock)
setclock( id, clock, [timer_id] ) -- set clock and timer_id for channel id

or even just the parameter list:
> help(adc.setclock)
setclock( id, clock, [timer_id] )

Doing some sort of programmatic generation of the list, I think, would be key to make it maintainable.

Maybe this could even be extended so that the documentation could be kept inline in the module source and have a script that will take take these elements and populate the webbook docs.

Hmmm, I was thinking about something precisely between these lines. Have a common documentation format (XML?) in which every function has two descriptions: a short description and a long description. The short one (or both, this should be selectable) would go inside eLua, while both of them would always go in webbook.
Your idea is very good, and inline with eLua's design principle of "run everything from the board". If we run everything from the board, having "on-line help" would certainly be a big help and a nice addition. I'm worried about flash consumption, but it doesn't have to be a problem. We could save the help in a file, in a simple format, and then load it either from internal ROMFS (if there's space there), or from SD, or from another ROMFS that leaves in a separate SPI flash, or ... well, you got the picture :) I like this idea a lot.
Excellent timing James! And thanks for mentioning this _before_ I even started to rewrite the API docs. Now I'll probably make them XML and write a simple Lua script to transform that into either webbook or "eLua format" (TBD).

Best,
Bogdan

PS. I have _got_ to finish those pesky docs already !!! I started to type ESC :w even when writing mails in gmail :|

_______________________________________________
Elua-dev mailing list
[hidden email]
https://lists.berlios.de/mailman/listinfo/elua-dev

[BogdanM]

Right, and it could be traded for functionality on space-impaired platforms.

I'm not sure how large this would end up being if it were really kept as simple as possible, but space is always at a premium :-)

True, but we'll make this configurable like everything else we have, so this shouldn't be such a big problem.
 

   We also want to concentrate the doc in a single place and the move we've made (comming on v0.6) to webbook proves that. But not all the project's "doc" is related to the modules, their functions or even the code implementation. This would be more of a "Reference Manual", which is one of the sections of the new "site/doc".

This is true.  What I was thinking of was less something that would regenerate the docs from scratch and more something that would parse documentation strings in the code and the HTML in the docs and update text sections in the HTML they didn't match the code.  This way could could selectively slave parts of the HTML documentation contents off of descriptions in the code.

I'd go with the XML version, since it's way easier to standardize. Different people working on the same HTML document have different ideas about formatting (I don't have to tell you that :) ), or about using new style=... args or opting for older HTML tags, or other things like this. A XML file would only have content, thus this problem is gone. No need to parse HTML anymore. The formatting part of HTML will be generated by a simple Lua script from the XML.

Best,
Bogdan

_______________________________________________
Elua-dev mailing list
[hidden email]
https://lists.berlios.de/mailman/listinfo/elua-dev

[John Hind]

Why not Lua table constructors? That way you avoid having to include SAX parser by leveraging what is already there. I wrote a mass of custom XML parsing code before finally “getting” Lua’s functionality as a data definition language. If anything Lua is terser and more functional than XML and already having the parser should be the deal clincher!

 

From: elua- Bogdan Marinescu Sent: 10 March 2009 19:14

I'd go with the XML version, since it's way easier to standardize.

 

_______________________________________________
Elua-dev mailing list
[hidden email]
https://lists.berlios.de/mailman/listinfo/elua-dev

[BogdanM]

Personally (and arguably) I find XML easier to read. But since I was planning to get a Lua table as the result of parsing the XML, we might just skip this step and get to the Lua table directly. Sometimes I just miss the obvious solutions, thanks for helping me to keep on track :)

Best,
Bogdan

On Wed, Mar 11, 2009 at 1:31 PM, John Hind <[hidden email]> wrote:

Why not Lua table constructors? That way you avoid having to include SAX parser by leveraging what is already there. I wrote a mass of custom XML parsing code before finally “getting” Lua’s functionality as a data definition language. If anything Lua is terser and more functional than XML and already having the parser should be the deal clincher!

 

From: elua- Bogdan Marinescu Sent: 10 March 2009 19:14

I'd go with the XML version, since it's way easier to standardize.

 

_______________________________________________
Elua-dev mailing list
[hidden email]
https://lists.berlios.de/mailman/listinfo/elua-dev

_______________________________________________
Elua-dev mailing list
[hidden email]
https://lists.berlios.de/mailman/listinfo/elua-dev

[Dado Sutter]

My vote is for Lua Tables too.
(You've antecipated my msg John :)

We're already using them on webbook's menu tree definition.
It is maybe not as widely known as XML but for this project it is not a problem, much on the contrary. To do the most we can in Lua seems very atractive to me.
So I'm doing some tests with IUP and Hamster (which works upon Scons too) to a GUI build configurator and automation tool, that may well grow to be an eLua IDE later on.
Kepler will also have it's place guaranteed on the (memory) bigger boards.
This makes us fully "Lua embedded" :)

Best
Dado

On Wed, Mar 11, 2009 at 08:31, John Hind <[hidden email]> wrote:

Why not Lua table constructors? That way you avoid having to include SAX parser by leveraging what is already there. I wrote a mass of custom XML parsing code before finally “getting” Lua’s functionality as a data definition language. If anything Lua is terser and more functional than XML and already having the parser should be the deal clincher!

 

From: elua- Bogdan Marinescu Sent: 10 March 2009 19:14

I'd go with the XML version, since it's way easier to standardize.

 

_______________________________________________
Elua-dev mailing list
[hidden email]
https://lists.berlios.de/mailman/listinfo/elua-dev

_______________________________________________
Elua-dev mailing list
[hidden email]
https://lists.berlios.de/mailman/listinfo/elua-dev