[GRASS-dev] new std options for files
hamish_nospam at yahoo.com
Wed Mar 21 23:04:30 EDT 2007
> 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.
> 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
(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).
More information about the grass-dev