[GRASS-dev] Help text for r.stats

[Vaclav Petras]

On Wed, Aug 1, 2018 at 5:54 AM, Nikos Alexandris <nik at 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 at 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 file ;)
>>
>> cheers,
>> Vero
>>
>> El dom., 29 jul. 2018 a las 11:46, Nikos Alexandris (<
>> nik at 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 at 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 at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/grass-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/grass-dev/attachments/20180802/c365dc5b/attachment.html>