[GRASS-dev] Help text for r.stats

[Nikos Alexandris]

Vaclav:

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

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

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 228 bytes
Desc: not available
URL: <http://lists.osgeo.org/pipermail/grass-dev/attachments/20180808/06b387c5/attachment.sig>