[Gnucap-devel] Help.. (thoughts about the help command)

[al davis]

When I look at other programs, what they offer for help, I think 
"we can do better than that".

In gnucap, remember ... it's all plugins.  Assume that all help 
requests are about plugins, and that ALL plugins need to offer 
"help".  Remember, the "apps" directory is just a collection of 
plugins that are installed by default.

Since every command, device, function, whatever .. needs "help", 
the help command code can simply use all of the dispatchers to 
look up the keyword, and invoke its help method.  The help 
dispatcher is for keywords that do not have a counterpart 
covered by another dispatcher.

In the simple case, the help method can just print the "help 
text".

Also, in the simple case, the "help text" can be a quoted C-
string constant in the code.

The actual code to print the "help text" can be in the CKT_BASE 
class, so it would be coded only once.

Call this "level 1".

To improve upon this, help should be able to show subtopics.

To do this, add tags to the "help text".  The tag needs to be 
delimited in some way.  For this, I suggested Texinfo style, but 
I am not sure about this.   Each subtopic text consists of that 
following the delimited keyword, up to but not including the 
next delimited keyword.

If the user asks for help with no subtopic, the beginning of the 
"help text" should be printed, stopping at the first subtopic, 
followed by a list of subtopics.

To make searching easier, the "help text" could now be a "CS" 
object in the code.  CS::scan can be used to search for the 
subtopic.

As before, the actual code can be in the CKT_BASE class, coded 
only once.

Call this "level 2".

In addition to this, some help could be automatically generated, 
not part of the "help text", for example a list of possible 
parameters (looping on "param_name"), a list of subtopics, a 
list of default values.

Call this "level 3".

The amount of text could be enough to warrant a separate file, 
so the next improvement could be to allow the "help text" to be 
in a separate text file, which could be read into a CS object 
for searching on demand.

A standard needs to be defined to enable finding that file.

Even if the file is supposedly provided, it must be optional, so 
at least level-1 help is available if the file is missing.

Call this "level 4".


At one point I suggested texinfo format, but now I don't think 
it is the way to go.  The help system needs to work without 
texinfo (or anything else) installed.

Before writing a lot of text, the code needs to be mature.  
Otherwise, somebody will eventually need to rewrite a lot of 
text.