[GRASS-dev] new std options for files

[Glynn Clements]

Hamish wrote:

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

There are plenty of ->description fields which are longer than that,
some with embedded newlines. E.g.:

	case G_OPT_V_FIELD:
	...
	    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>