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

[GRASS GIS]

#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):

 #2136 is solved but the new approach was not applied everywhere yet. I
 went through the following list (from comment:5:ticket:2136) for
 standardization of basename (formerly prefix) options and changed things
 from `input_prefix` and `input_prefix` to `input` and `output` while using
 the standard options for base name (patch attached). I also updated the
 documentation and made some fixes related to earlier changes in
 prefix->basename transition.

 {{{
     g.extension => prefix: Prefix where to install extension (ignored when
 flag -s is given)
     i.cca => output: Output raster map prefix name
     i.landsat.acca => input_prefix: Example: 'B.' for B.1, B.2, ...
     i.landsat.toar => input_prefix: Example: 'B.' for B.1, B.2, ...
     i.landsat.toar => output_prefix: Example: 'B.toar.' generates
 B.toar.1, B.toar.2, ...
     i.pansharpen => output_prefix: Prefix for output raster maps
     i.pca => output_prefix: A numerical suffix will be added for each
 component map
     i.tasscap => output_prefix: Prefix for output raster maps
     i.topo.corr => output: Name (flag -i) or prefix for output raster maps
     m.nviz.script => name: Prefix of output images (default = NVIZ)
     r.blend => output_prefix: Prefix for red, green and blue output raster
 maps containing
     r.rgb => output_prefix: Prefix for output raster maps (default: input)
     r.ros => output: Prefix for output raster maps (.base, .max, .maxdir,
 .spotdist)
     r.texture => prefix: Prefix for output raster map(s)
     v.out.postgis => dsn: Starts with 'PG' prefix, eg. 'PG:dbname=grass'
     v.rast.stats => column_prefix: Column prefix for new attribute columns
 }}}

 It seems to me that `input` and `output` should be used instead of other
 options (i.e. including `basename` in the option name). This also mean
 that I think that the standard option definition should be changed
 accordingly.

 There are still some unresolved issues. As noted on [http://osgeo-
 org.1560.x6.nabble.com/Fwd-QGIS-Processing-amp-GRASS-td5155460.html
 mailing list] and in comment:13, there are issues with base names in QGIS
 processing. Basically the issue is that things are not explicit and
 actually being explicit might be better for GRASS itself regardless what
 QGIS can handle or not.

 It seems to me that base names on input should be avoided most of the
 time. Imagery modules can use imagery groups, other modules can use
 explicit list. There is a lot of modules which use one or the other.

 With outputs, the situation is more complicated. I can distinguish four
 different cases.

 Case one, the module produces just few maps and there is not many reasons
 to not provide them as separate output options. Example is G7:r.rgb
 suffixing `.r`, `.g` and `.b` versus with red, green and blue options (the
 change is in the diff). Another example of this is G7:r.ros which outputs
 base, max and dir ROS and optionally spotting distance. Now they are all
 specified using basename but G7:r.spread accepts them as separate maps
 anyway and there needs to be `-s` to activate spotting (while with
 separate options, it is enough just to check if option was provided). This
 option is OK for scripting, it is not much work to fill manually and both
 QGIS and wxGUI can handle it well (just using the standard means).

 Example of case two is G7:r.neighbors, the module can generate several
 statistics and you have to provide as many names for option output as is
 the number of requested statistics. This might be challenging when done
 manually since you must match the order but is is fine for scripting, QGIS
 and wxGUI.

 Example of case three is G7:r.texture where just base name is provided and
 module itself adds suffixes according to selected methods. When used
 manually, it is quite convenient because you don't have to care about the
 names, you just have to find them afterwards. The issue for scripting is
 that you don't have any idea what the suffixes are and they are indeed
 different than the option values. QGIS and wxGUI which don't know the
 details about the called module are completely lost. This case can be
 avoided using the approach taken by G7:r.neighbors.

 The last case are modules which produce (large) number of numbered maps,
 these are the reason why standard base name option was created. With these
 there is no other choice than to use base name. The hope with these is
 that the output can be registered to temporal dataset or group. If this is
 not the right choice then there is not much hope left for QGIS and wxGUI.
 When scripting, you can just rely on having unique enough base name. It
 should work when solving things manually because you can always check the
 result and fine tune the listing.

 I hope I will be able to do the necessary changes but I need to know where
 it makes sense to add imagery group (as output or input) to `i.*` modules
 and I need to hear opinions on moving from G7:r.texture approach to
 G7:r.neighbors approach.

-- 
Ticket URL: <http://trac.osgeo.org/grass/ticket/2409#comment:17>
GRASS GIS <http://grass.osgeo.org>