[GRASS-dev] r.colors confusion with "color", "rules", and "raster" options

[Glynn Clements]

Hamish wrote:

> [stating my peace then dropping this to focus on far more ghastly UI issues]
> 
> > Hamish wrote:
> > > I've just added some logic in 6.x SVN to more nicely handle different
> > > user interpretations of the commands. "accept sloppy input, create
> > > tight output" and all that. Sure 'color=rules rules=filename' is
> > > redundant, but the intention is obvious. some people (especially those
> > > unfamiliar) like to tick every box. if it doesn't hurt anything, let
> > > 'em.
> Glynn:
> > Reverted.
> > 
> > If input is invalid, you report that it's invalid, not silently do
> > what you *think* that the user meant (i.e. DWIM).
> 
> I accept the general point, but in this case can you offer an
> alternative intent for 'color=rules rules=filename'?
> 
> I find "invalid" a bit strong in this case, but agree that if the user
> misinterprets something then it is our task to make the instructions
> clearer.

Well, if the user specifies 'color=rules rules=filename', the error
message is:

	ERROR: "color", "rules", and "raster" options are mutually exclusive

>From that, it should be clear that the user has to choose between
color= and rules=. The option descriptions:

	rules   Path to rules file
	color   Type of color table

should make it clear that rules= is the correct choice for reading
rules from a file.

Also, the additon of "from stdin" to the text for color=rules:

	create new color table based on user-specified rules read from stdin

should make it clear that this isn't what they want if they are
reading rules from a file.

> > If the user misunderstands something, you should educate them, not
> > reinforce the misconception.
> 
> In cases where it is obvious what they meant, my view would be to
> focus on the goal and let a minor misappreciation for the underlying
> design pass.
> 
> 
> trying to get into the head of a new user for a minute:
> 
> Gary the Grass user is presented with the r.colors GUI.
> He starts filling in options from the top down. As a beginner he can
> only guess what to put for each option. For "color=" he gets a drop
> down menu, the top entry being blank and the bottom being rules. ummm...
> The next is for "rules=" filename. That makes sense and he uses that.
> But what to put for the colors= option now? Being slightly unsure of
> himself with this new complex software, and wanting to make doubly sure
> that the rules= option is used, and lacking the experience to follow 
> the subtle logic, the points the colors= option at what he thinks is
> for rules=. That gives an error not to use the colors= option. But then
> he thinks that he *did* give the neutral answer to color=, and what to
> set it to now? (blank may be far from obvious)

If a user thinks that they should fill in as many options as possible,
that's a fundamental misconception that should be corrected sooner
rather than later.

I've just noticed that the wxPython dialogs don't indicate whether an
option is required or optional, while the Tcl/Tk dialogs note this for
each option.

Really, if a user just selects options based upon instinct, they're
likely to run into more substantial problems sooner rather than later.

> > > > -rules: create new color table based on user-specified rules
> > > > +rules: create new color table based on user-specified rules read from stdin
> > > 
> > > I reverted that as it is somewhat misleading. It can mean either read
> > > directly from stdin or if no stream is waiting then to enter into the
> > > interactive environment.
> > 
> > Huh? It always means "read from stdin". If stdin is a tty, you get the
> > interactive prompts; if it's a file or pipe, you don't.
> 
> Well technically, yes, but I feel that we're splitting hairs here.
> To the same newly recruited user, what is a stdin and where can I go to
> buy one? -----Do those extra words contribute to the clarity of meaning?

Absolutely. Otherwise, it's stating that the option uses
user-specified rules read from ... who knows where?

For someone as new as "Gary", would they even know that they need to
put the rules into a file? Or what format those rules should be in?

Or would they just see "based on user-specified rules" and expect it
to pop up a window into which they can enter rules? If they do,
they're in for shock, as the GUI waits for r.colors, which is waiting
for something to be fed to its stdin.

By the point that they are entering a valid sequence of colour rules
into a text file, they probably know that they will need to use rules=
to use it. Otherwise, why would they be creating that file in the
first place? What are they planning to do with it once it has been
created?

-- 
Glynn Clements <glynn at gclements.plus.com>