[Gnucap-devel] Gnucap Comprehensive Help System Implementation Details

[Rishabh Yadav]

*Gnucap Comprehensive Help System Implementation Details*



*Overview*

The community support and documentation of a software plays an important
role in enhancing the user experience. Gnucap has very active developers
community who are always ready to assist and explain things in a very
elaborative manner. What Gnucap lacks is a well structured documentation of
commands which can be accessed in the interpreter.


My project aims to build a comprehensive help system which can assist a
user/developer directly in the interpreter without searching for
commands/inbuilt function over the internet or Gnucap manual all the time.
Motivated by the need of a help system in Gnucap,I came up with one
possible basic structure with which first we can start and gradually make
it more comprehensive.


The structure of help function is such that it tries to access the text
string defined by the developer in the comment section of source file of a
plugin and prints this text as help information in the interpreter. For
this structure to work properly a standard of writing help string in the
source file is to be defined so that whenever a user calls help function
with a command they get the help manual of that command.


The help string is defined between a start tag and an end tag.The help
function access this string,parses it and then prints the output at the
interpreter.

The help string should start from the next line just after the start tag is
defined and it should be terminated by an end tag which is defined in the
new line just after the string ends.

The start tag is <Plugin Manual> and the end tag is <End>.If you don't like
the naming convention of these tags then you can easily change them by
editing a config file.


Example:Suppose we define a source file called c_example.cc and include
following details in the comment section of the file.

<plugin_manual>

This is a help string.

<end>



Then,help function parses and prints the help string defined between
<plugin_manual> and <end> tag which is:

This is a help string.

Apart from this text accessing and printing workflow of help system,project
later on aims to provide few utilities which may aid in writing good and
proper documentation of a plugin.





 *Proposed Features and Implementation Details*



   - *List all functions*: Gnucap should have a command which can print all
   the available functions so that users can browse all the available features
   on the go. Filters can also be passed as a parameter to list only
   functions/commands of interest.


   - *Did you mean?*: Sometimes users don't remember the name of command
   they want to use and end up getting '^ ? what's this?'.There suggestion
   feature can be used which can be used for looking up a command which is
   very much similar to the command entered by the user and print it in the
   interpreter.The similarity between the two string can be calculated by a
   metric given by Levenshtein distance and based on this metric,command(s)
   alongwith summary of what it does,can be presented to the user.


   - *User Interface:*A user interface within the interpreter which can
   assist user in knowing everything interactively about a command can be
   defined. Here,a user will be able to execute the examples provided in the
   help manual to understand the usage of command clearly. The context in
   which the example of a command is supposed to execute properly is created
   within this user interface.


   - *Output format of Help String*:The help manual of a plugin can be
   imported in the form of Pdf,Plaintext and HTML format.


   - *Inbuilt Function*:The basic help system currently implemented in
   Gnucap only looks for source files in the current working directory.A
   function get_location('function_name') has to be defined to look for the
   source file which may exist at any location and return the path of that
   directory.The source files generally reside where gnucap is installed so
   search path can be dynamically created.Hence,the average time complexity in
   searching for the path of source file of this function depends only on the
   number of source files in a particular directory.

A very basic form of this implemetation can be found in the *WIP
branch[1]*of Gnucap repository.

These are the few "must required" features which I'll try to implement as
early as possible.In parallel,I'll keep on adding more and more features to
this manual to create a comprehensive help system.This manual will be
published in Gnucap Wiki and it will be updated regularly.



If you have any better help system implementation structure or  any cool
feature in your mind then please let us know. Your suggestions and feedback
is very important and highly appreciated.

[1] http://git.savannah.gnu.org/cgit/gnucap.git/tree/c_help.cc?h=WIP


You can find the pdf copy of this email in the attachments.


Thanking You,
Rishabh Yadav
Junior Undergraduate
Department of Electronics Engineering
IIT (BHU), Varanasi
Varanasi-221005
India