One observation: `r.stats`'s `--help` returns
Parameters:
..
separator Field separator
default: space
..
Shouldn't all separator options be listed here?
They are described in the `.html ` page:
..
separator=character
Field separator
Special characters: pipe, comma, space, tab, newline
Default: space
..
Does this deserve a ticker?
Nikos
How is it described in all other modules using the “separator” option? Maybe, it is worth checking and making it uniform.
You could open a ticket and provide a diff file 
cheers,
Vero
El dom., 29 jul. 2018 a las 11:46, Nikos Alexandris (<nik@nikosalexandris.net>) escribió:
One observation:
r.stats’s--helpreturnsParameters: .. separator Field separator default: space ..Shouldn’t all separator options be listed here?
They are described in the
.htmlpage:.. separator=character Field separator Special characters: pipe, comma, space, tab, newline Default: space ..Does this deserve a ticker?
Nikos
grass-dev mailing list
grass-dev@lists.osgeo.org
https://lists.osgeo.org/mailman/listinfo/grass-dev
Ciao Vero,
I had a look. I am not yet that familiar with the "UI" construction from
C source code, so I am not sure where to dig for this (comment: with
Python it's easy).
As noted, and as you likely have observed,
the 'html' manual mentions all options. They are only missing in
the command line help text.
The same is valid for `r.univar`, `r.stats.quantile` for
example. That is: only one separator option is mentioned, the default
one. All manuals do mention all options though.
I'll have to look at this later on.
Thank you, Nikos
* Veronica Andreo <veroandreo@gmail.com> [2018-07-31 00:13:59 +0200]:
How is it described in all other modules using the "separator" option?
Maybe, it is worth checking and making it uniform.
You could open a ticket and provide a diff filecheers,
VeroEl dom., 29 jul. 2018 a las 11:46, Nikos Alexandris (<
nik@nikosalexandris.net>) escribió:One observation: `r.stats`'s `--help` returns
Parameters: .. separator Field separator default: space ..Shouldn't all separator options be listed here?
They are described in the `.html ` page:
.. separator=character Field separator Special characters: pipe, comma, space, tab, newline Default: space ..Does this deserve a ticker?
Nikos
_______________________________________________
grass-dev mailing list
grass-dev@lists.osgeo.org
https://lists.osgeo.org/mailman/listinfo/grass-dev
--
Nikos Alexandris | Remote Sensing & Geomatics
GPG Key Fingerprint 6F9D4506F3CA28380974D31A9053534B693C4FB3
On Wed, Aug 1, 2018 at 5:54 AM, Nikos Alexandris <nik@nikosalexandris.net>
wrote:
Ciao Vero,
I had a look. I am not yet that familiar with the "UI" construction from
C source code, so I am not sure where to dig for this (comment: with
Python it's easy).As noted, and as you likely have observed,
the 'html' manual mentions all options. They are only missing in
the command line help text.The same is valid for `r.univar`, `r.stats.quantile` for
example. That is: only one separator option is mentioned, the default
one. All manuals do mention all options though.
Hi Nikos,
The difference is between `options` and `descrtiption` items (let's call
these items for now, basically key-value pairs defined in the code). The
separators are defined in plain text as a `description` item while the
options you see with other modules are defined using the structured
`options` item. Note the difference in the manual "options:"/"Options:" and
"Special characters:".
The reason why they are defined this ways is that `options` are the only
allowed values checked by the command line parameters parser while
`description` is simply a text for the user to read. For example, executing
r.colors map=elevation color=xxx
gives
ERROR: Value <xxx> out of range for parameter <color>
Legal range: aspect,aspectcolr,bcyr,bgyr,blues,...
On the other hand,
r.stats input=elevation -x sep=xxx
gives
1xxx1xxx141.99614
2xxx1xxx141.27849
3xxx1xxx141.37904
4xxx1xxx142.29822
...
Now, the reason why you don't see it in the command line help is that the
separator parameter (which is a standard option G_OPT_F_SEP) defines both
label and description:
https://trac.osgeo.org/grass/browser/grass/trunk/lib/gis/parser_standard_options.c#L601
https://grass.osgeo.org/programming7/parser__standard__options_8c_source.html
601 case G_OPT_F_SEP:
602 Opt->key = "separator";
603 Opt->type = TYPE_STRING;
604 Opt->key_desc = "character";
605 Opt->required = NO;
606 Opt->gisprompt = "old,separator,separator";
607 Opt->answer = "pipe";
608 Opt->label = _("Field separator");
609 Opt->description = _("Special characters: pipe, comma, space,
tab, newline");
610 break;
If both are defined, only label is shown in the command line help. That is
to make the command line help short (so you can read it quickly without
scrolling). The `default` and `options` items are part of the short help
because they are considered crucial in getting the command line right. You
can read about the decision here:
[GRASS-dev] Adding an expert mode to the parser (September 2016)
https://lists.osgeo.org/pipermail/grass-dev/2016-September/082388.html
https://lists.osgeo.org/pipermail/grass-dev/2016-September/082469.html
https://lists.osgeo.org/pipermail/grass-dev/2016-September/082526.html
That being said, this is not set in stone. For example, some modules could
benefit from something like formalized "suggested values" as opposed to
"the only allowed values", but "suggested values" is still not the same as
"special characters" here or generally "specially treated values".
Best,
Vaclav
I'll have to look at this later on.
Thank you, Nikos
* Veronica Andreo <veroandreo@gmail.com> [2018-07-31 00:13:59 +0200]:
How is it described in all other modules using the "separator" option?
Maybe, it is worth checking and making it uniform.
You could open a ticket and provide a diff filecheers,
VeroEl dom., 29 jul. 2018 a las 11:46, Nikos Alexandris (<
nik@nikosalexandris.net>) escribió:One observation: `r.stats`'s `--help` returns
Parameters: .. separator Field separator default: space ..Shouldn't all separator options be listed here?
They are described in the `.html ` page:
.. separator=character Field separator Special characters: pipe, comma, space, tab, newline Default: space ..Does this deserve a ticker?
Nikos
_______________________________________________
grass-dev mailing list
grass-dev@lists.osgeo.org
https://lists.osgeo.org/mailman/listinfo/grass-dev--
Nikos Alexandris | Remote Sensing & Geomatics
GPG Key Fingerprint 6F9D4506F3CA28380974D31A9053534B693C4FB3
_______________________________________________
grass-dev mailing list
grass-dev@lists.osgeo.org
https://lists.osgeo.org/mailman/listinfo/grass-dev
Vaclav:
On Wed, Aug 1, 2018 at 5:54 AM, Nikos Alexandris <nik@nikosalexandris.net>
wrote:Ciao Vero,
I had a look. I am not yet that familiar with the "UI" construction from
C source code, so I am not sure where to dig for this (comment: with
Python it's easy).As noted, and as you likely have observed,
the 'html' manual mentions all options. They are only missing in
the command line help text.The same is valid for `r.univar`, `r.stats.quantile` for
example. That is: only one separator option is mentioned, the default
one. All manuals do mention all options though.Hi Nikos,
The difference is between `options` and `descrtiption` items (let's call
these items for now, basically key-value pairs defined in the code). The
separators are defined in plain text as a `description` item while the
options you see with other modules are defined using the structured
`options` item. Note the difference in the manual "options:"/"Options:" and
"Special characters:".The reason why they are defined this ways is that `options` are the only
allowed values checked by the command line parameters parser while
`description` is simply a text for the user to read. For example, executingr.colors map=elevation color=xxx
gives
ERROR: Value <xxx> out of range for parameter <color>
Legal range: aspect,aspectcolr,bcyr,bgyr,blues,...On the other hand,
r.stats input=elevation -x sep=xxx
gives
1xxx1xxx141.99614
2xxx1xxx141.27849
3xxx1xxx141.37904
4xxx1xxx142.29822
...
This is a "design" choice, then.
Now, the reason why you don't see it in the command line help is that the
separator parameter (which is a standard option G_OPT_F_SEP) defines both
label and description:https://trac.osgeo.org/grass/browser/grass/trunk/lib/gis/parser_standard_options.c#L601
https://grass.osgeo.org/programming7/parser__standard__options_8c_source.html601 case G_OPT_F_SEP:
602 Opt->key = "separator";
603 Opt->type = TYPE_STRING;
604 Opt->key_desc = "character";
605 Opt->required = NO;
606 Opt->gisprompt = "old,separator,separator";
607 Opt->answer = "pipe";
608 Opt->label = _("Field separator");
609 Opt->description = _("Special characters: pipe, comma, space,
tab, newline");
610 break;If both are defined, only label is shown in the command line help.
I know this. Yet, I didn't find/read/notice that the "Special
characters" are defined using the 'description' "item".
That is
to make the command line help short (so you can read it quickly without
scrolling). The `default` and `options` items are part of the short help
because they are considered crucial in getting the command line right. You
can read about the decision here:[GRASS-dev] Adding an expert mode to the parser (September 2016)
https://lists.osgeo.org/pipermail/grass-dev/2016-September/082388.html
https://lists.osgeo.org/pipermail/grass-dev/2016-September/082469.html
https://lists.osgeo.org/pipermail/grass-dev/2016-September/082526.html
Thank you so much for providing these links.
(Your answer's structure, helps me to concentrate on the essentials.
I'll take this as a lesson to improve my writings!)
That being said, this is not set in stone. For example, some modules could
benefit from something like formalized "suggested values" as opposed to
"the only allowed values", but "suggested values" is still not the same as
"special characters" here or generally "specially treated values".
Maybe I am over-thinking about it: is it wrong to allow _all_ characters
being used as separators except of the set of characters that have a
special meaning to the underlying OSes or else would cause any sorts of
problems?
Then, describe this like "Supported characters are only..." or "All
characters supported except of ..."?
Great answer Vaclav!
[rest deleted]
Nikos
On Tue, Aug 7, 2018 at 10:44 PM, Nikos Alexandris <nik@nikosalexandris.net>
wrote:
Vaclav:
That being said, this is not set in stone. For example, some modules could
benefit from something like formalized "suggested values" as opposed to
"the only allowed values", but "suggested values" is still not the same as
"special characters" here or generally "specially treated values".Maybe I am over-thinking about it: is it wrong to allow _all_ characters
being used as separators except of the set of characters that have a
special meaning to the underlying OSes or else would cause any sorts of
problems?
This comment was really general, not necessarily related to field
separators in text files. Anyway, the problem with separators is really to
have the separator in the command line written without any escaping or
quoting. To avoid thinking about when and how to do it, we provide these
special values such as "pipe" which are the replaced by the corresponding
character (but themselves are completely safe/harmless). Additionally,
these special characters are good for readability `separator=,` or `,
separator=',', in Python` look little strange and whitespace characters may
suffer from combination of both. Of course then there is the problem with
conflict with characters in the file. Comma as separator and comma as
"decimal point" would be the typical example from Czech environment. How we
avoid that is that we let user to decide on the separator and we are using
pipe as a default since it is an unusual character in text (but also quite
know and visually appropriate at the same time if you are dealing with
command line).
Then, describe this like "Supported characters are only..." or "All
characters supported except of ..."?
Disallowing characters is not really desired for the separator, but
generally the "only supported characters/values" behavior is what the
options item is doing. The "all values except these" behavior, basically a
negation of the options item is something we don't have in the parser (but
we probably don't have any use of it either at this point).
Great answer Vaclav!
Thanks!