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

[Helena Mitasova]

On Sep 25, 2008, at 11:36 AM, Glynn Clements wrote:

>
> 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)

this is almost exactly what happened in our class today - I told the  
students
to use predefined color rules table that was provided in a text file,
so you give an input raster map and then you are asked to provide
"Type of color table"
so logically you select "rules"
and then you provide path to the rules table and Run
and you get the error message that they are exclusive

Replacing "Type of color table" with "Select a predefined color table"
or something like that would make it clearer that this is an  
alternative to
the rules file not a parameter indicating that rules file will be used.

And I can confirm that when you go back to try to fix it - blank indeed
is not obvious at all - it looks like you always have to select from  
the list
something.
>
> 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.

changing the wording may help. I am not sure that one would have to  
go as
far as say - "Select only one option from the three provided below"
I guess GRASS users are pretty smart and don't need that level
of guidance,

Helena


>
> 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>
> _______________________________________________
> grass-dev mailing list
> grass-dev at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/grass-dev