Hi,
I've just added two new standard options for file input and output to
the parser. Time to make distclean again, sorry. (added to the end of
the list, so there shouldn't be as much weirdness this time)
Hamish
Hamish wrote:
I've just added two new standard options for file input and output to
the parser. Time to make distclean again, sorry. (added to the end of
the list, so there shouldn't be as much weirdness this time)
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.
Proposed change: ->description is always the option description, and
->tooltip, if present, contains the tooltip. ->label is dropped.
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.
[*] http://thread.gmane.org/gmane.comp.gis.grass.devel/16809
Hamish
Hamish wrote:
> I've just added two new standard options for file input and output to
> the parser. Time to make distclean again, sorry. (added to the end of
> the list, so there shouldn't be as much weirdness this time)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.
This is between the application and the GUI code. The parser options
which generate descriptions (--interface-description, --tcltk,
--script etc) simply output the contents of those fields as-is.
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.
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.
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).
--
Glynn Clements <glynn@gclements.plus.com>
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
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@gclements.plus.com>
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
Hamish wrote:
## ->descs is ignored in the tcl GUI, it should be appended to the
tooltip.
If you have tooltips for individual choices (e.g. for each item in an
option menu; is that possible?), then the description for that choice
would be the entire tooltip.
You certainly *don't* want to be appending the entire set of
option/description pairs to the tooltip for the option; that would
result in excessively large tooltips, e.g. the color= option of
r.colors:
color Type of color table
options: aspect,grey,grey.eq,grey.log,byg,byr,gyr,rainbow,ramp,
random,ryg,wave,rules
aspect: aspect oriented grey colors
grey: linear grey scale
grey.eq: histogram equalized grey scale
grey.log: histogram logarithmic transformed grey scale
byg: blue through yellow to green colors
byr: blue through yellow to red colors
gyr: green through yellow to red colors
rainbow: rainbow color table
ramp: color ramp
random: random color table
ryg: red through yellow to green colors
wave: color wave
rules: create new color table by rules
--
Glynn Clements <glynn@gclements.plus.com>
Hamish wrote:
> ## ->descs is ignored in the tcl GUI, it should be appended to the
> tooltip.
Glynn:
If you have tooltips for individual choices (e.g. for each item in an
option menu; is that possible?), then the description for that choice
would be the entire tooltip.
that would be nicer than the full list for each option; it sounds
possible, "just" some smart parsing needed in the GUI code.
also, WRT help finding modules in the GUI menu tree I have just uploaded
a new script to CVS, tools/module_synopsis.sh. It makes a list of all
modules like:
g.module: Module description.
.
.
.
Perhaps the GUI menu items could have tooltips parsed from the resulting
file, in the same way option->options could have tooltips parsed from
the ->descs list?
I am not aware of another software package which does that, maybe for
good reason? At the same time our menu has more entries than most other
software. I seem to remember that Tcl won't let you do this? (beyond
module name printed to the bottom of the gis.m window) Maybe wxPy will?
note in writing that script, g.parser and r.mapcalc were the only two
modules that caused an obvious error (actually produced an error msg,
not $?==1). Progress!
Hamish
HamishB wrote:
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....
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 would like to bring up this issue again (since I am confused):
Currently only about 10 modules use
module->label
In the GUI pop up it is even printed in the wrong vertical order
if above definition is true + there is ugly vertical space between
these two lines.
Question: what's the point of module->label? Take it out or
modify 290+ modules? We need some consistency...
Is there anything using module->label|description as tooltip?
confused (about why we need two things to do nearly the same),
Markus
--
View this message in context: http://www.nabble.com/new-std-options-for-files-tf3438602.html#a12554008
Sent from the Grass - Dev mailing list archive at Nabble.com.
Hi,
you are not only one confused Markus by this;-)
The label/description stuff is a bit illogical. I suppose to change in this way:
* Use 'description' as short sentence describing module/flag/option
(must be defined).
* Rename 'label' to 'tooltip'.
Martin
2007/9/7, Markus Neteler <neteler@itc.it>:
HamishB wrote:
>
>> 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.
> ...
> 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 would like to bring up this issue again (since I am confused):
Currently only about 10 modules use
module->labelIn the GUI pop up it is even printed in the wrong vertical order
if above definition is true + there is ugly vertical space between
these two lines.Question: what's the point of module->label? Take it out or
modify 290+ modules? We need some consistency...
Is there anything using module->label|description as tooltip?confused (about why we need two things to do nearly the same),
Markus
--
View this message in context: http://www.nabble.com/new-std-options-for-files-tf3438602.html#a12554008
Sent from the Grass - Dev mailing list archive at Nabble.com._______________________________________________
grass-dev mailing list
grass-dev@grass.itc.it
http://grass.itc.it/mailman/listinfo/grass-dev
--
Martin Landa <landa.martin@gmail.com> * http://gama.fsv.cvut.cz/~landa *
Markus Neteler wrote:
>> 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.
> ...
> 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 would like to bring up this issue again (since I am confused):
Currently only about 10 modules use
module->labelIn the GUI pop up it is even printed in the wrong vertical order
if above definition is true + there is ugly vertical space between
these two lines.Question: what's the point of module->label?
For use as a label in the GUI in case the description is too verbose.
Take it out or
modify 290+ modules? We need some consistency...
Leave it as-is.
Is there anything using module->label|description as tooltip?
Any option which has a separate label will have the description as the
tooltip.
confused (about why we need two things to do nearly the same),
Some descriptions are too verbose to use as labels in the GUI.
--
Glynn Clements <glynn@gclements.plus.com>