[GRASS-dev] Re: [GRASS GIS] #1031: More specific parameter information in command line help

[GRASS GIS]

#1031: More specific parameter information in command line help
--------------------------+-------------------------------------------------
  Reporter:  huhabla      |       Owner:  grass-dev at lists.osgeo.org
      Type:  enhancement  |      Status:  new                      
  Priority:  minor        |   Milestone:  7.0.0                    
 Component:  libgis       |     Version:  svn-trunk                
Resolution:               |    Keywords:  parser, help             
  Platform:  All          |         Cpu:  All                      
--------------------------+-------------------------------------------------
Comment (by huhabla):

 Replying to [comment:3 martinl]:
 > Replying to [comment:2 huhabla]:
 > > I am aware that some of informations i requests are given by the usage
 string. But IMHO it is more convenient and easier to understand
 (especially for command line beginner) to make these informations also
 available in the help description. My enhancement request is only related
 to the command line. It does not touch the automated gui generation.
 >
 > I think that the beginners usually do not use CLI at all. At least
 'type' and 'required' are redundant info
 >

 > {{{
 >       input   Name of input raster map
 >               status: input
 >               type: cell
 >               required: yes
 > }}}
 >
 > We could use {{{key_desc}}} attribute for defining prompt type.
 >
 > {{{
 > input=raster
 > }}}
 >
 > instead of
 >
 > {{{
 > input=name
 > }}}
 >
 > The question is how to handle 'status' of the options.
 >
 > > The usage string does not always provide the convenient information if
 the parameter is of type raster, vector, volume, integer or float. In many
 modules input and output parameter are named related to the modules
 purpose, the information if its an input or output is only present if you
 read the help page.
 >
 > Right, it could be improved by better {{{key_desc}}} usage.

 Thats a good idea. We could start modifying the default options in
 lib/gis/parser.c adding {{{key_desc}}}. Although this information is
 already specified in the {{{gisprompt}}} string ... we can use the
 convenient naming scheme used in {{{gisprompt}}} for {{{key_desc}}}.

 >
 > > Martin Landa currently renamed in several modules the input and output
 parameter to make clear which of them are inputs or outputs. I.e:
 elevation -> elevation_input, direction -> direction_output, but this is
 IMHO not a good idea. It is redundant information, especially if you are
 using the gui.
 >
 > Right, see [wiki:Grass7/NewFeatures#Renamedoptions Rename options]. Your
 idea about 'status' info seems to be better solution. If you prefer I can
 remove '_input/optput' from paramaters key string.

 Well this is only my humble opinion. In case other developers prefer the
 your naming schema i will accept it. Thats why i would like to discuss
 this topic.

 I would personally prefer to remove '_input/optput' from paramaters key
 string and establish a combination of {{{key_desc}}} and the additional
 "status" parameter in the command line. Maybe we can use a better name
 than "status" ... like "type"? Additionally we can hide the status
 parameter in case "input", "map" and "output" are used as {{{key}}}
 strings?

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