[GRASS-dev] grass7 - renamed optiont

GRASS GRASS developer
1

In grass7 the names of options for some commands were changed
(but the manuals were not updated).
http://trac.osgeo.org/grass/wiki/Grass7/NewFeatures#Renamedoptions

I would like to update the manuals for r.flow, r.sim.water and r.sim.sediment,
to reflect the change but first I would like to ask - is this change really necessary?
(everything that has r.flow in it from scripts to tutorials will need to be updated)

If yes, I would like to change the two last options to more meaningful terms as follows:

6.4 -> 7. proposed
elevin -> elevation
aspin -> aspect
barin -> barrier
flout -> flowline
lgout -> flowpath --> length
dsout -> density --> accumulation (or just accum?)

any feedback would be welcome

Helena

2

Hi,

2011/6/12 Helena Mitasova <hmitaso@ncsu.edu>:

If yes, I would like to change the two last options to more meaningful terms as follows:

well, these changes are not really necessary, but good to do for G7...

6.4 -> 7. proposed
elevin -> elevation
aspin -> aspect

`elevation` or `aspect` are standard option names, there is only one
reason why to keep non-standard, sometime obscure names - breaking
existing scripts. We already started standardization of option names,
let's continue.

barin -> barrier
flout -> flowline
lgout -> flowpath --> length
dsout -> density --> accumulation (or just accum?)

`flowline` is OK when changing `flowpath` to `length`?
`accumulation` is still OK, you can use shorten name when calling the module.

Martin

--
Martin Landa <landa.martin gmail.com> * http://geo.fsv.cvut.cz/~landa

3

Helena Mitasova wrote:

In grass7 the names of options for some commands were changed
(but the manuals were not updated).
http://trac.osgeo.org/grass/wiki/Grass7/NewFeatures#Renamedoptions

I would like to update the manuals for r.flow, r.sim.water and r.sim.sediment,
to reflect the change but first I would like to ask - is this change really necessary?

Yes. And we there are probably some more which should be changed (and
some of those listed on that page should be changed further).

In general: consistency is good, abbreviations are bad. And 7.0
provides an opportunity to fix past mistakes.

If yes, I would like to change the two last options to more meaningful terms as follows:

dsout -> density --> accumulation (or just accum?)

There is no reason to abbreviate an option name. The parser recognises
abbreviations provided that they are unambiguous, but it won't
recognise an unabbreviated name if the option name itself is
abbreviated.

7.0 takes this a step further: if an option name consists of multiple
words separated by underscores, you can abbreviate or omit individual
words and/or omit the underscores; e.g. an option named "levels_red"
could be abbreviated to "lev_red", "lev_r", or even just "lr".

So there shouldn't be any need to use abbreviations when choosing
option names. In some cases, it may be worth adding underscores
between the lexemes of compound words in order to facilitate
abbreviation.

The only caveat is that an abbreviation given on the command line must
not match multiple options, or else an error occurs; there is no "best
match" rule.

For this reason, no option should be a prefix of another. So instead
of e.g. "red" and "red_levels" (which would make "r=..." ambiguous),
the latter becomes "levels_red".

--
Glynn Clements <glynn@gclements.plus.com>

4

On Jun 12, 2011, at 3:03 AM, Glynn Clements wrote:

Helena Mitasova wrote:

In grass7 the names of options for some commands were changed
(but the manuals were not updated).
http://trac.osgeo.org/grass/wiki/Grass7/NewFeatures#Renamedoptions

I would like to update the manuals for r.flow, r.sim.water and r.sim.sediment,
to reflect the change but first I would like to ask - is this change really necessary?

Yes. And we there are probably some more which should be changed (and
some of those listed on that page should be changed further).

In general: consistency is good, abbreviations are bad. And 7.0
provides an opportunity to fix past mistakes.

If yes, I would like to change the two last options to more meaningful terms as follows:

dsout -> density --> accumulation (or just accum?)

There is no reason to abbreviate an option name. The parser recognises
abbreviations provided that they are unambiguous, but it won't
recognise an unabbreviated name if the option name itself is
abbreviated.

7.0 takes this a step further: if an option name consists of multiple
words separated by underscores, you can abbreviate or omit individual
words and/or omit the underscores; e.g. an option named "levels_red"
could be abbreviated to "lev_red", "lev_r", or even just "lr".

So there shouldn't be any need to use abbreviations when choosing
option names. In some cases, it may be worth adding underscores
between the lexemes of compound words in order to facilitate
abbreviation.

thanks for the explanation - I updated r.flow accordingly.

The only caveat is that an abbreviation given on the command line must
not match multiple options, or else an error occurs; there is no "best
match" rule.

For this reason, no option should be a prefix of another. So instead
of e.g. "red" and "red_levels" (which would make "r=..." ambiguous),
the latter becomes "levels_red".

there is one like this that I almost always get wrong
d.vect mypoints siz=10

does not work because there is

size and size_column

Helena

--
Glynn Clements <glynn@gclements.plus.com>

5

Glynn:

The only caveat is that an abbreviation given on the command line must
not match multiple options, or else an error occurs; there is no "best
match" rule.

I would think that an exact match should trump all others, and only after
that an error occurs on ambiguities. (I suppose cycles are cheap these days
but it seems expensive to exhaustively check every single abbrev vs. all
other options' possible abbrevs. but I guess it is safer than leaving it
to the eye of the programmer)

shrug,
Hamish

ps- slightly off-topic, but I'd like to keep discussion of this one alive:
"proposal to improve module wxGUI tab logic"
https://trac.osgeo.org/grass/ticket/886

6

Hamish wrote:

> The only caveat is that an abbreviation given on the command line must
> not match multiple options, or else an error occurs; there is no "best
> match" rule.

I would think that an exact match should trump all others,

It does. Otherwise there wouldn't be any way to enter an option which
was a prefix of another, as it would always be ambiguous. An exact
match terminates the loop (ignoring any future matches) and sets the
match count to one (ignoring any prior matches).

But if one option is a prefix of another, it cannot be abbreviated, as
that would always result in multiple inexact matches, which triggers
the ambiguity error. That's the case in both 6.x and 7.0.

It wouldn't be particularly hard to treat this situation as a special
case, but I'm not sure it's wise. The user may have overlooked the
shorter option and be intending to abbreviate the longer one. Of
course, that could also be true for an exact match, but there's not
much that we can about it; there has to be some way to specify the
shorter option.

--
Glynn Clements <glynn@gclements.plus.com>