[GRASS-dev] new std options for files
glynn at gclements.plus.com
Thu Mar 22 10:36:17 EDT 2007
> > 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)
When the ->label field was originally added, G_tcltk() did:
desc = opt->label ? opt->label : opt->description;
However, this was changed to output both the ->label and ->description
fields verbatim, with the behaviour left up to the GUI code.
Currently, if ->label is provided, that is used for the item label
while ->description is used for the tooltip. If you don't have
->label, then ->description is used for the item label, and there's no
need for a tooltip (I would only repeat what the item label says).
Essentially, a two-sentence description is fine in the --help output
or the manual page, but not as a GUI label, hence the addition of the
->label field. But some descriptions are only a couple of words, so
there's no need for separate label text.
> > > 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'm not a fan of paragraph-length tooltips; there comes a point at
which you just need to refer to the manual.
> 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
There are plenty of ->description fields which are longer than that,
some with embedded newlines. E.g.:
Opt->description = _("A single vector map can be connected to multiple database "
"tables.\nThis number determines which table to use.");
> 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.
The reasoning is that if the ->description is short enough to use as a
label, there's no need to go through all 300+ modules adding ->label
entries which simply duplicate the ->description.
> 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).
I'd rather see G_usage() do the formatting; tabs wouldn't be
appropriate if the description is used in a tooltip (and probably
wouldn't have the desired result in HTML).
Glynn Clements <glynn at gclements.plus.com>
More information about the grass-dev