[GRASS-dev] Help text for r.stats
nik at nikosalexandris.net
Tue Aug 7 19:44:26 PDT 2018
>On Wed, Aug 1, 2018 at 5:54 AM, Nikos Alexandris <nik at nikosalexandris.net>
>> 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.
>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
>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
>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
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:
>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,
>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".
>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)
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
Then, describe this like "Supported characters are only..." or "All
characters supported except of ..."?
Great answer Vaclav!
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 228 bytes
Desc: not available
More information about the grass-dev