[GRASS-dev] new std options for files

[Hamish]

Glynn:
> 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.

Ok, I finally understand this now.


> I'm not a fan of paragraph-length tooltips; there comes a point at
> which you just need to refer to the manual.

I am a fan of self-documenting software; I agree that 4-5 sentences into
the tooltip it might be better to refer the user to the help page. I
would be happy with 2-3 sentence tooltips, no more than 4-5 lines tall
when wrapped. I think tooltips are very valuable for GRASS as the module
options are often quite abstruse.


> > 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.");
[...]
> 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).


Ok, for ->description we should avoid fancy formatting within the
string, it should be up to the GUI or G_usage() to do the formatting. I
have modified the above string in CVS to remove the \n. It doesn't need
to be there. If tooltips are recommended to be not more than a few
sentences we don't need to worry about formatting multi-paragraph.


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

got it.

> > 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've now fixed this in CVS.


I also added module->label to G_usage(), if present. (e.g. v.net.iso)
tcl GUI already has it.


TODO:

## for G_usage() add line wrap at col 76 for ->descriptions and
->descs strings (break at whitespace; see lib/gis/error.c).

## ->descs is ignored in the tcl GUI, it should be appended to the
tooltip. (use the parsed ->descs list, not raw ->descriptions string)
e.g. v.clean


Hamish