[GRASS-dev] new std options for files

[Hamish]

> Hamish wrote:
> > as earlier mentioned* I'd like to change the Option struct to
> > rationalize the ->description and ->label parts.
> > 
> > currently, if a label is defined it becomes the description, and the
> > description becomes the tooltip. This is non-intuitive and
> > inconsistent.
Glynn:
[...]
> I note that a few of the standard options abuse these fields, assuming
> that both fields will be displayed consecutively (as is done for
> --help). Those should be fixed, as should applications which use the
> fields in a similar manner.
> 
> > Proposed change: ->description is always the option description, and
> > ->tooltip, if present, contains the tooltip. ->label is dropped.
> 
> ->description should be a description suitable for --help or use in
> the manual page. If present, ->label should be a shorter description
> for use in dialogs in case ->description is too long for that purpose.

ok, therein lies the confusion.

->label was added to 5.1 by Radim in gis.h rev 1.10 for the purpose you
describe:  /* Optional short label, used in GUI as item label */

and in practice (parser.c and modules) this has been used to facilitate
the tooltip in a few places: The v.clean thresh= option uses it, and
v.net.iso uses the module version (tcl GUI includes that well, --help
doesn't)

(I also see in that rev he added **opts  /* NULL or NULL terminated
array of parsed options */, maybe useful for g.parser putenv'ing $@
before overwriting it, for use with --script?)

 
> I'm not sure that you really need tooltips when you already have a
> text label, but if they are desired, they may as well contain the
> contents of the ->description field.

so parser.c/GUI acts like:

if (->label == NULL)
{
   label = description;
   description = NULL;
}

then the GUI only prints the shortened label, or if that doesn't exist
it uses the full description as the label. (and tooltip is not possible)

> > Also in Flag and GModule structs.
> > 
> > Alternative (which I'm leaning towards):  keep ->label, just remove
> > the weirdness and make it always be the tooltip.
> 
> The weirdness (e.g. misuse of those fields by G_OPT_WHERE and
> G_OPT_V_CATS) should definitely be removed.
>
> I see no point in having a tooltip which says exactly the same thing
> as the label. Tooltips are only useful if they contain additional
> information which isn't in the button/checkbox/etc label (e.g. because
> the button uses an icon or a terse description).


so we have three possible levels of verbosity for an option description:
  ->label:       a few words
  ->description: a sentence
  ->tooltip:     a paragraph/short example showing format (doesn't exist)

I think it is a good idea to keep ->description (as commonly used now)
short and to the point, ie shorter than ~65 chars (so it fits on one
line). Certainly the label should quite short. It looks bad when the
description is line wrapped in --help, or colliding with the right side
of the GUI window.

I guess what I don't like is that the description has a dual meaning
depending on the context (ie if a label is present). I agree that it's
dumb to duplicate the description as a tooltip in the 99% of the cases
where there is no label.

So still a bit blurry about how to clean this up, and if ->tooltip is a
good idea. At least now I understand what's happening.


Also, the long description (or tooltip) with --help needs to have
\t\t, as the text starts in a column determined by the longest option
name and often it looks odd ("tooltip" extra descr starts out-of-line).


Hamish