[GRASS5] Interfaces ... (long)

[Eric G. Miller]

As some of you may know, I've been monkeying around with the XML
interface thing that Jan put together (thanks Glynn for fixing that
printf bug).  Anyway, I have some changes or proposals I'd like to
submit.  I've categorised them in order of importance and ease of
implementation.  I apologize if I've made some assumptions about
SGML/XML knowledge.

Simple and Necessary:

  *  Currently the "gisprompt" and "key_desc" parts of the Option
     group are ignored.  Both are very important for providing a user
     with the correct interface.  I submit that these changes should be
     added as attributes of the "parameter" element right away.

  *  There needs to be a way to handle interactive programs.  I'll have
     more on this later, but perhaps there should be an attribute of
     "task" for flagging interactive *only* programs.  Some programs
     may run as command line, but prompt for user input.  This latter
     case is more difficult, but for the time being they could all be
     specified as "interactive" and a front-end that couldn't accomodate
     that could drop the "task" from its list.  TclTkGrass has a
     mechanism to spawn an xterm for these, but that wouldn't be viable
     for a browser interface... For the simple yes/no interactive, this
     could be added to the GModule struct (name, description,
     interactive?).
     
Simple and better semantics:

  *  Currently the "parameter" element is used both for Options and
     Flags.  From a parsing stand point, it makes life slightly more
     difficult.  Also, most of the attributes and child elements of the
     "parameter" element do not apply to Flags and would be erroneous if
     present (e.g.  "required=", "multiple=", "<default>",
     "<values>,<value>").  A flag is always "off" by default, and is
     almost never required (more on this later), can't be specified
     multiple times, and has no set of possible values.

     I propose separating the flag element from the parameter element.

     <!ELEMENT flag  description?>
     <!ATTLIST flag  name CDATA #REQUIRED>

     <!ELEMENT parameter-group (description?, (parameter | flag)+)>

  *   Currently the DTD does not enforce that if there is a "default"
      element and a set of "value" elements, that the default be a
      member of the set of "values".  It may be better to have an
      attribute of "value" that has default property, or to let
      "default" occur once in the "values" set.  The latter is probably
      easier and more logically correct.  NOTE: DTD's can't really say
      much about the content of elements, only the structure (XML
      Schemas *can* speak to content, but it is only recently adopted).
      But the G_usage_xml() could clearly handle the latter case, and
      it'd help any front end.  This change is less important, but a
      good idea IMHO.

More Work and More Complex:

  *   In some modules there is a clear dependency/conflict relationship
      between various flags and options.  In cases I've encountered, it
      often seems to be, you can run the command with a, b, c or with a
      and d (but not b and c).  I think it would be valuable to be able
      to capture this inter option/flag dependency, as better interfaces
      could be generated.  I don't have a fully formulated suggestion
      for this one, but it would require some significant changes.  

      One way to look at them, is to create an option/flag grouping.
      This should be feasible within the current DTD framework as more
      than one "parameter-group" can exist for a given task.  However,
      the "parameter-group" is probably too high up the chain, as we
      would probably not want to have to duplicate common options for
      each parameter-group.
      
      One way to change this in the DTD, would be to allow "parameter"
      and "flag" elements to exist as direct children of "task" and only
      use "parameter-group" when a set of options should be grouped
      together *and* conflict with any other parameter-group.  The
      G_parser() system would have to have a way to specify this
      information.  There could be the concept of a OptionGroup, and
      individual options could be added to OptionGroups.  

      Another way to approach, might be to add a mechanism to specify
      more complex dependency/conflict relationships between options
      before calling G_parser().  That is there'd be a functions like:
      G_parser_depends (OptionOfInterest, OptionRequired),
      G_parser_conflicts (OptionOfInterest, OptionConflicts)
      There'd be some interaction with the "required" member for Options
      which would need to be considered.  For instance, if a "global"
      option has "opt->required = YES", then another option can't
      conflict with it.  Nor, could one option require an option that
      requires a third option that conflicts with the first.  I'm not
      sure how you'd specify this in a DTD...

      This kind of dependency/conflict stuff can't get a bit hairy, but
      it would provide the ability to create better user interfaces.

Pipe Dream:

  *   Returning to the problem of interactive programs...
      This gets alot deeper into system architecture concepts, but it is
      extremely important if we agree there should be a mechanism for
      separating the interface from the implementation.  
      
      It's clear there needs to be a mechanism for a running module to
      prompt for user action, but be able to do so in a way not tied to
      any particular implementation (like Vask or the various G_ask_*
      listing routines both which assume a terminal, and the first
      assumes "curses").  We could return to XML to provide such
      mechanisms (or at least the specifications), but it will take some
      thought and alot of work to realize.  

      There are different types of user interaction that are often
      required.  The simplest to deal with would probably be the Vask
      case where the user is prompted to fill out "form" type data.
      But, the program would have to know it wants to dump out a form
      specification, rather than a curses interface *and* the program
      would have to have to ability to restart where it left off
      (consider the nature of http -- the module would have to exit,
      then be restarted when it was called again with the form data
      "posted").

      Even if we solved the above, what about display programs that take
      direction via "mouse clicks", or something of the nature of
      v.digit?  Here the interaction is of a different sort, and it
      wouldn't do for the modules to stop and start.

      I don't have much for suggestions on this last one, but it is
      something to consider longer range.
-- 
Eric G. Miller <egm2 at jps.net>