Vaclav:
On Wed, Aug 1, 2018 at 5:54 AM, Nikos Alexandris <[email protected]> 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
signature.asc
Description: PGP signature
_______________________________________________ grass-dev mailing list [email protected] https://lists.osgeo.org/mailman/listinfo/grass-dev
