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. _______________________________________________ Gnucap-devel mailing list [email protected] https://lists.gnu.org/mailman/listinfo/gnucap-devel
