[GRASS-dev] [GRASS GIS] #2409: last call for options keys consolidation

GRASS GIS GRASS GIS developer
21

#2409: last call for options keys consolidation
----------------------------------+-----------------------------------------
Reporter: martinl | Owner: grass-dev@…
     Type: task | Status: new
Priority: blocker | Milestone: 7.0.0
Component: Default | Version: unspecified
Keywords: standardized options | Platform: Unspecified
      Cpu: Unspecified |
----------------------------------+-----------------------------------------

Comment(by martinl):

related to attachment:prefix_to_basename.diff

I don't fully understand why to define key 'output' for basename options.
I thought that `G_OPT_BASENAME_OUTPUT` will have default key like
'basename_output' or 'output_basename' (better for backward
compatibility). Similarly `G_OPT_BASENAME_INPUT` 'input_basename'.

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/2409#comment:18&gt;
GRASS GIS <http://grass.osgeo.org>

22

#2409: last call for options keys consolidation
----------------------------------+-----------------------------------------
Reporter: martinl | Owner: grass-dev@…
     Type: task | Status: new
Priority: blocker | Milestone: 7.0.0
Component: Default | Version: unspecified
Keywords: standardized options | Platform: Unspecified
      Cpu: Unspecified |
----------------------------------+-----------------------------------------

Comment(by wenzeslaus):

Replying to [comment:18 martinl]:
> related to attachment:prefix_to_basename.diff
>
> I don't fully understand why to define key 'output' for basename
options. I thought that `G_OPT_BASENAME_OUTPUT` will have default key like
'basename_output' or 'output_basename' (better for backward
compatibility). Similarly `G_OPT_BASENAME_INPUT` 'input_basename'.

Currently, it seems to me that the current option naming policy is to use
input or output regardless of type. So input can be raster for one module
but vector or imagery group for another. Basename is just another item in
the list of possible types/meanings.

I think that in case that the output is group or spatio temporal dataset,
the option name `basename` is appropriate if you want to set the basename
for maps differently from the name of the group.

When opening #2136 it was not clear to me when `output`,
`output_basename`/`basename_output` or `basename` are appropriate. The
motivation for #2136 was unification and creation of standard mechanism in
the first place.

But especially after going through Pietro's list in comment:5:ticket:2136,
it seems to me that basename is nothing special and the default/most used
name for the option should be the same as if it would be raster or vector,
so `output` and `input` in these cases.

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/2409#comment:19&gt;
GRASS GIS <http://grass.osgeo.org>

23

#2409: last call for options keys consolidation
----------------------------------+-----------------------------------------
Reporter: martinl | Owner: grass-dev@…
     Type: task | Status: new
Priority: blocker | Milestone: 7.0.0
Component: Default | Version: unspecified
Keywords: standardized options | Platform: Unspecified
      Cpu: Unspecified |
----------------------------------+-----------------------------------------

Comment(by martinl):

Replying to [comment:19 wenzeslaus]:
> Currently, it seems to me that the current option naming policy is to
use input or output regardless of type. So input can be raster for one
module but vector or imagery group for another. Basename is just another
item in the list of possible types/meanings.

then why the default key is set to `basename` ?
source:grass/trunk/lib/gis/parser_standard_options.c#L336

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/2409#comment:20&gt;
GRASS GIS <http://grass.osgeo.org>

24

#2409: last call for options keys consolidation
----------------------------------+-----------------------------------------
Reporter: martinl | Owner: grass-dev@…
     Type: task | Status: new
Priority: blocker | Milestone: 7.0.0
Component: Default | Version: unspecified
Keywords: standardized options | Platform: Unspecified
      Cpu: Unspecified |
----------------------------------+-----------------------------------------

Comment(by martinl):

For those how would like to spend some energy and check possible
inconsistency in parameter names I attached
attachment:module_params_overview-2014-11-24.csv.gz

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/2409#comment:21&gt;
GRASS GIS <http://grass.osgeo.org>

25

#2409: last call for options keys consolidation
----------------------------------+-----------------------------------------
Reporter: martinl | Owner: grass-dev@…
     Type: task | Status: new
Priority: blocker | Milestone: 7.0.0
Component: Default | Version: unspecified
Keywords: standardized options | Platform: Unspecified
      Cpu: Unspecified |
----------------------------------+-----------------------------------------

Comment(by wenzeslaus):

Replying to [comment:20 martinl]:
> Replying to [comment:19 wenzeslaus]:
> > Currently, it seems to me that the current option naming policy is to
use input or output regardless of type. So input can be raster for one
module but vector or imagery group for another. Basename is just another
item in the list of possible types/meanings.
>
> then why the default key is set to `basename` ?
source:grass/trunk/lib/gis/parser_standard_options.c#L336

And also the description could be better. I can fix it when I get to it.

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/2409#comment:22&gt;
GRASS GIS <http://grass.osgeo.org>

26

On 24.11.2014 20:42, GRASS GIS wrote:

#2409: last call for options keys consolidation

----------------------------------+-----------------------------------------
Reporter: martinl | Owner: grass-dev@…
     Type: task | Status: new
Priority: blocker | Milestone: 7.0.0
Component: Default | Version: unspecified
Keywords: standardized options | Platform: Unspecified
      Cpu: Unspecified |

----------------------------------+-----------------------------------------

Hi Martin,

can I ask for the script, or the way, you extracted the flags and options per module?

Thanks, Nikos

27

#2409: last call for options keys consolidation
----------------------------------+-----------------------------------------
Reporter: martinl | Owner: grass-dev@…
     Type: task | Status: new
Priority: blocker | Milestone: 7.0.0
Component: Default | Version: unspecified
Keywords: standardized options | Platform: Unspecified
      Cpu: Unspecified |
----------------------------------+-----------------------------------------

Comment(by glynn):

Replying to [ticket:2409 martinl]:
> Before releasing G7 we should check all the modules and use the
standardized options as much as possible. Changing key of an option or a
flag will be not possible after releasing GRASS 7.0.0.

It should be safe to change a key provided that the old value is an
accepted abbreviation for the new value.

And on that note, if anyone is planning on changing any keys, please

  1. Avoid abbreviating keys; the user can always abbreviate, but they
can't "unabbreviate".

  2. Place an underscore between distinct words, to increase the set of
accepted abbreviations (e.g. "line_color" can be abbreviated to "lcol"
bult "linecolor" can't).

To recap: if an option key consists of multiple words (sequences of
characters separated by underscores), the key can be abbreviated to any
combination of prefixes of the individual words. The first letter of the
first word must be provided; subsequent words may be omitted entirely.
Underscores are optional.

The main limitation is that each word can only be abbreviated to a
(possibly empty) prefix, so

  1. Compound words cannot have their components abbreviated individually,
so "background" cannot be abbreviated to "bg". "back_ground" can be
abbreviated to "background" or "bg", but looks ugly.

  2. Plurals cannot be abbreviated to a plural, so "columns" can be
abbreviated to "col" but not to "cols". Again, "column_s" could be
abbreviated to "column_s" or "col" or "cols", but also looks ugly.

It would be reasonably straightforward to extend the code to support an
"invisible" word separator, which would behave like underscore but would
be omitted from the --help output. So if "background" was changed to e.g.
"back'ground" it would show as "background" in the --help output but could
be abbreviated to "bg".

One possible drawback is that if an abbreviation was rejected due to being
a valid abbreviation for more than option, the conflicting option wouldn't
necessarily be apparent to the user (due to the separator being hidden).

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/2409#comment:23&gt;
GRASS GIS <http://grass.osgeo.org>

28

Ciao Niko,

2014-11-24 20:09 GMT+01:00 Nikos Alexandris <nik@nikosalexandris.net>:

can I ask for the script, or the way, you extracted the flags and options
per module?

sure, http://svn.osgeo.org/grass/sandbox/martinl/print_module_parameters_csv.py

Martin

--
Martin Landa
http://geo.fsv.cvut.cz/gwiki/Landa
http://gismentors.eu/mentors/landa

29

#2409: last call for options keys consolidation
----------------------------------+-----------------------------------------
Reporter: martinl | Owner: grass-dev@…
     Type: task | Status: new
Priority: blocker | Milestone: 7.0.0
Component: Default | Version: unspecified
Keywords: standardized options | Platform: Unspecified
      Cpu: Unspecified |
----------------------------------+-----------------------------------------

Comment(by martinl):

Replying to [comment:23 glynn]:
> Replying to [ticket:2409 martinl]:

> 1. Compound words cannot have their components abbreviated
individually, so "background" cannot be abbreviated to "bg". "back_ground"
can be abbreviated to "background" or "bg", but looks ugly.

thanks for useful comments, there are a lot of options which are
abbreviated. Eg.

{{{
bgcolor Background color
}}}

Do we prefer to leave as it is or change to

{{{
background_color
}}}

?

Then it can be abbreviated to

{{{
bcolor
}}}

but not to

{{{
bgcolor
}}}

That would require to rename the option to

{{{
back_ground_color
}}}

which is ugly as Glynn already noted.

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/2409#comment:24&gt;
GRASS GIS <http://grass.osgeo.org>

30

#2409: last call for options keys consolidation
----------------------------------+-----------------------------------------
Reporter: martinl | Owner: grass-dev@…
     Type: task | Status: new
Priority: blocker | Milestone: 7.0.0
Component: Default | Version: unspecified
Keywords: standardized options | Platform: Unspecified
      Cpu: Unspecified |
----------------------------------+-----------------------------------------

Comment(by martinl):

Replying to [comment:24 martinl]:
> Do we prefer to leave as it is or change to
>
> {{{
> background_color
> }}}
>
> ?
>
> Then it can be abbreviated to
>
> {{{
> bcolor
> }}}
>
> but not to
>
> {{{
> bgcolor
> }}}

The attachment:renamed_options.diff adds to the parser support for renamed
options. Eg.

{{{
d.erase bgcolor=black
}}}

will continue to work with appropriate warning

{{{
WARNING: Please update the interface of the module: option <bgcolor> has
been renamed to <background_color> in GRASS 7.0
}}}

Make sense to you?

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/2409#comment:25&gt;
GRASS GIS <http://grass.osgeo.org>

31

#2409: last call for options keys consolidation
----------------------------------+-----------------------------------------
Reporter: martinl | Owner: grass-dev@…
     Type: task | Status: new
Priority: blocker | Milestone: 7.0.0
Component: Default | Version: unspecified
Keywords: standardized options | Platform: Unspecified
      Cpu: Unspecified |
----------------------------------+-----------------------------------------

Comment(by annakrat):

Replying to [comment:25 martinl]:
> Replying to [comment:24 martinl]:
> > Do we prefer to leave as it is or change to
> >
> > {{{
> > background_color
> > }}}
> >
> > ?
> >
> > Then it can be abbreviated to
> >
> > {{{
> > bcolor
> > }}}
> >
> > but not to
> >
> > {{{
> > bgcolor
> > }}}
>

In this case I would keep bgcolor, I don't think we have to unabbreviate
everything just for the sake of consistency and in this case as you show,
the abbrevated versions are not really suitable, unless Glynn implements
the new mechanism, which I think would be confusing.

> The attachment:renamed_options.diff adds to the parser support for
renamed options. Eg.
>
> {{{
> d.erase bgcolor=black
> }}}
>
> will continue to work with appropriate warning
>
> {{{
> WARNING: Please update the interface of the module: option <bgcolor> has
been renamed to <background_color> in GRASS 7.0
> }}}
>
> Make sense to you?

This is great, I haven't tested it yet, but it will be very useful.

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/2409#comment:26&gt;
GRASS GIS <http://grass.osgeo.org>

32

#2409: last call for options keys consolidation
----------------------------------+-----------------------------------------
Reporter: martinl | Owner: grass-dev@…
     Type: task | Status: new
Priority: blocker | Milestone: 7.0.0
Component: Default | Version: unspecified
Keywords: standardized options | Platform: Unspecified
      Cpu: Unspecified |
----------------------------------+-----------------------------------------

Comment(by annakrat):

I will change r.colors options (raster -> rast, volume -> rast3d) unless
someone is against, sometime soon.

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/2409#comment:27&gt;
GRASS GIS <http://grass.osgeo.org>

33

#2409: last call for options keys consolidation
----------------------------------+-----------------------------------------
Reporter: martinl | Owner: grass-dev@…
     Type: task | Status: new
Priority: blocker | Milestone: 7.0.0
Component: Default | Version: unspecified
Keywords: standardized options | Platform: Unspecified
      Cpu: Unspecified |
----------------------------------+-----------------------------------------

Comment(by martinl):

Replying to [comment:26 annakrat]:

> In this case I would keep bgcolor, I don't think we have to unabbreviate
everything just for the sake of consistency and in this case as you show,
the abbrevated versions are not really suitable, unless Glynn implements
the new mechanism, which I think would be confusing.
> > {{{
> > WARNING: Please update the interface of the module: option <bgcolor>
has been renamed to <background_color> in GRASS 7.0
> > }}}
> >
> > Make sense to you?
>
> This is great, I haven't tested it yet, but it will be very useful.

If we use the patch noted above than we can happily rename `bgcolor` to
`background_color` I would say...

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/2409#comment:28&gt;
GRASS GIS <http://grass.osgeo.org>

34

#2409: last call for options keys consolidation
----------------------------------+-----------------------------------------
Reporter: martinl | Owner: grass-dev@…
     Type: task | Status: new
Priority: blocker | Milestone: 7.0.0
Component: Default | Version: unspecified
Keywords: standardized options | Platform: Unspecified
      Cpu: Unspecified |
----------------------------------+-----------------------------------------

Comment(by martinl):

Replying to [comment:27 annakrat]:
> I will change r.colors options (raster -> rast, volume -> rast3d) unless
someone is against, sometime soon.

same should be done with `d.rast.leg`

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/2409#comment:29&gt;
GRASS GIS <http://grass.osgeo.org>

35

#2409: last call for options keys consolidation
----------------------------------+-----------------------------------------
Reporter: martinl | Owner: grass-dev@…
     Type: task | Status: new
Priority: blocker | Milestone: 7.0.0
Component: Default | Version: unspecified
Keywords: standardized options | Platform: Unspecified
      Cpu: Unspecified |
----------------------------------+-----------------------------------------

Comment(by glynn):

Replying to [comment:27 annakrat]:
> I will change r.colors options (raster -> rast, volume -> rast3d) unless
someone is against, sometime soon.

"raster" shouldn't be abbreviated. "volume" should probably be "raster_3d"
(for which "raster3d" and "rast3d" are accepted abbreviations).

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/2409#comment:30&gt;
GRASS GIS <http://grass.osgeo.org>

36

#2409: last call for options keys consolidation
----------------------------------+-----------------------------------------
Reporter: martinl | Owner: grass-dev@…
     Type: task | Status: new
Priority: blocker | Milestone: 7.0.0
Component: Default | Version: unspecified
Keywords: standardized options | Platform: Unspecified
      Cpu: Unspecified |
----------------------------------+-----------------------------------------

Comment(by glynn):

Replying to [comment:24 martinl]:

> Do we prefer to leave as it is or change to
>
{{{
background_color
}}}
>
> ?
>
> Then it can be abbreviated to
>
{{{
bcolor
}}}

Except: d.vect currently has both bgcolor= (label background color) and
bcolor= (label border colour). If these were changed to background_color
and border_color, bcolor would be rejected as ambiguous.

Another possibility with regards to abbreviating compound words would be
to use an upper-case letter (rather than a specific character, such as the
single quote in the previous example), so backGround_color would work like
back_ground_color but arguably isn't quite as ugly. Similarly, "columnS"
doesn't seem as bad as column_s.

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/2409#comment:31&gt;
GRASS GIS <http://grass.osgeo.org>

37

#2409: last call for options keys consolidation
----------------------------------+-----------------------------------------
Reporter: martinl | Owner: grass-dev@…
     Type: task | Status: new
Priority: blocker | Milestone: 7.0.0
Component: Default | Version: unspecified
Keywords: standardized options | Platform: Unspecified
      Cpu: Unspecified |
----------------------------------+-----------------------------------------

Comment(by annakrat):

Replying to [comment:30 glynn]:
> Replying to [comment:27 annakrat]:
> > I will change r.colors options (raster -> rast, volume -> rast3d)
unless someone is against, sometime soon.
>
> "raster" shouldn't be abbreviated. "volume" should probably be
"raster_3d" (for which "raster3d" and "rast3d" are accepted
abbreviations).

So we then have to rename also option rast, rast3d in g.region I suppose,
and perhaps some others. We shouldn't forget that although unabbreviating
doesn't cause problems in the command line, python scripts require the
full name of the command.

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/2409#comment:32&gt;
GRASS GIS <http://grass.osgeo.org>

38

#2409: last call for options keys consolidation
----------------------------------+-----------------------------------------
Reporter: martinl | Owner: grass-dev@…
     Type: task | Status: new
Priority: blocker | Milestone: 7.0.0
Component: Default | Version: unspecified
Keywords: standardized options | Platform: Unspecified
      Cpu: Unspecified |
----------------------------------+-----------------------------------------

Comment(by annakrat):

Replying to [comment:31 glynn]:
> Another possibility with regards to abbreviating compound words would be
to use an upper-case letter (rather than a specific character, such as the
single quote in the previous example), so backGround_color would work like
back_ground_color but arguably isn't quite as ugly. Similarly, "columnS"
doesn't seem as bad as column_s.

Please don't do that. GRASS suffers from "too many ways to do the same
thing", let's not make it worse.

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/2409#comment:33&gt;
GRASS GIS <http://grass.osgeo.org>

39

#2409: last call for options keys consolidation
----------------------------------+-----------------------------------------
Reporter: martinl | Owner: grass-dev@…
     Type: task | Status: new
Priority: blocker | Milestone: 7.0.0
Component: Default | Version: unspecified
Keywords: standardized options | Platform: Unspecified
      Cpu: Unspecified |
----------------------------------+-----------------------------------------

Comment(by wenzeslaus):

Replying to [comment:32 annakrat]:
> Replying to [comment:30 glynn]:
> > Replying to [comment:27 annakrat]:
> > > I will change r.colors options (raster -> rast, volume -> rast3d)
unless someone is against, sometime soon.
> >
> > "raster" shouldn't be abbreviated. "volume" should probably be
"raster_3d" (for which "raster3d" and "rast3d" are accepted
abbreviations).
>
> So we then have to rename also option rast, rast3d in g.region I
suppose, and perhaps some others. We shouldn't forget that although
unabbreviating doesn't cause problems in the command line, python scripts
require the full name of the command.

I would not unabbreviate everything. Some standard widely used
abbreviations such as `rast` or `vect` are OK I would say. Non-abbreviated
terms should be used for less standard things such as `elevation` or
`index`. This is a good compromise between clear readable names and overly
long options and module calls.

Of course in some cases unabbreviating would be quite harmless concerning
total length of option(s), for example `rast` -> `raster` but I don't have
an idea how badly this would work for `strds` (which I'm not comfortable
with but I don't have a better idea).

Also sometimes you just have to make the option name shorter by leaving
out some words. Of course this is combined a lot with abbreviating because
it would be not readable anyway, for example `npmin` from G7:v.surf.rst
which has meaning ''Minimum number of points for approximation in a
segment'', the only meaningful not shortened not abbreviated name I can
think of is `minimum_of_points_for_approximation` which is juts too long.

This brings me to my final point. If we unabbreviate and unshorten
everything and we will provide a lot of different options how to
abbreviate it then we can naturally expect that people will use it a lot
and they will of course use different abbreviations. But this, I think,
defeats the purpose of unabbreviated option that is readability (and auto-
documentation) because by looking at the command with abbreviated option
you are not able to say what they mean.

Therefore, I think that using the abbreviations occasionally on places
where everybody would like to shorten anyway is the way to go.

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/2409#comment:34&gt;
GRASS GIS <http://grass.osgeo.org>

40

#2409: last call for options keys consolidation
----------------------------------+-----------------------------------------
Reporter: martinl | Owner: grass-dev@…
     Type: task | Status: new
Priority: blocker | Milestone: 7.0.0
Component: Default | Version: unspecified
Keywords: standardized options | Platform: Unspecified
      Cpu: Unspecified |
----------------------------------+-----------------------------------------

Comment(by wenzeslaus):

Replying to [comment:25 martinl]:
> Replying to [comment:24 martinl]:
> > Do we prefer to leave as it is or change to
> >
> > {{{
> > background_color
> > }}}
> >
> > ?
> >
> > Then it can be abbreviated to
> >
> > {{{
> > bcolor
> > }}}
> >
> > but not to
> >
> > {{{
> > bgcolor
> > }}}
>
> The attachment:renamed_options.diff adds to the parser support for
renamed options. Eg.
>
> {{{
> d.erase bgcolor=black
> }}}
>
> will continue to work with appropriate warning
>
> {{{
> WARNING: Please update the interface of the module: option <bgcolor> has
been renamed to <background_color> in GRASS 7.0
> }}}
>
> Make sense to you?

We need something like this for a long time already. It is really good as
long as it is used as you are proposing that is to maintain backwards
compatibility. I wouldn't like to see that used as a way to provide
different names for one option.

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/2409#comment:35&gt;
GRASS GIS <http://grass.osgeo.org>