[GRASS-dev] [GRASS GIS] #4000: v.import documentation megabug

[GRASS GIS]

#4000: v.import documentation megabug
-------------------------+---------------------------------
 Reporter:  jidanni      |      Owner:  grass-dev@…
     Type:  defect       |     Status:  new
 Priority:  trivial      |  Milestone:
Component:  Docs         |    Version:  git-releasebranch78
 Keywords:               |        CPU:  Unspecified
 Platform:  Unspecified  |
-------------------------+---------------------------------
 It's bug #4000. Time for my v.import documentation megabug.
 Mainly because apparently v.import calls v.in.org under the hood.

 Anyway, here is the whole mess:
 {{{
 Do not require input=... for v.import -f
 Please do not require the user to have an input file just to use
 v.import -f .
 Or document workaround:
  v.import -f input=/dev/null
 Also
  SYNOPSIS
        ...
        v.import  [-flo]  input=string  ...

 needs to be
        v.import  -f #in fact maybe detect and don't allow it to be
 combined with other options
        v.import  [-lo]  input=string  ...

 and "[required]" needs to be removed from
  input=string [required]
            Name of OGR datasource to be imported
 P.S., change
  The list of actually supported formats can be printed by -f flag.
 to
  The list of actually supported formats can be printed by the -f flag.
 Wait, it seems that v.import is some sort of alias for v.in.org. Well
 the man page should just say so at the top, and the rest left mostly
 blank. (Please don't maintain two sets of almost identical
 documentation. Bad for writers, and bad for readers. In fact you can
 list both aliases in the same SYNOPSIS of a symlinked (or just copied) new
 single page.)
 And in fact one can do
  v.in.ogr -f
 without input=string, so the v.in.ogr man page needs to be fixed too.

 r.in.gdal -f in fact does not require input=... output=...
 The r.in.gdal man page should be fixed to reflect reality:
  SYNOPSIS
        r.in.gdal -f #now alone on a separate line
 and "[required]" needs to be removed from these:
  input=name [required]
  output=name [required]

 v.import -f produces jumbled list
 Currently the user must use
  v.import -f | sort -f
 if he wants to read the list produced in any orderly fashion.
 Perhaps this could be done automatically, or at least documented on
 the man page.

 r.in.gdal -f produces jumbled list
 Currently the user must use
  r.in.gdal -f | sort -f
 if he wants to read the list produced in any orderly fashion.
 Perhaps this could be done automatically, or at least documented on
 the man page.

 v.import: combine confusing sentences
 In man v.import we read
  DESCRIPTION
  ...
  If the projection of the input does not match the projection of the
  location, the input is reprojected into the current location. In case
  that the projection of the input map does match the projection of the
  location, the input is imported directly.

 Let's take a second look at that last part:

 __________If_the_projection_of_the_input_____does_not_match_the_projection_of_the_location,_the_input_is_reprojected_into_the_current_location.
 In_case_that_the_projection_of_the_input_map_does_____match_the_projection_of_the_location,_the_input_is_imported_directly.

 Let's see if we can combine them to make a single sentence:

  If the projection of the input does not match the projection of the
  location, the input is reprojected into the current location. Else it
  is imported directly.

 Or perhaps simply:

  If the projection of the input does not match the projection of the
  location, the input is reprojected into the current location.

 Wait! Maybe -o needs to be mentioned here too, as further below we see:

  NOTES

  v.import checks the projection metadata of the dataset to be imported
  against the current location's projection. If not identical a related
  error message is shown. To override this projection check (i.e. to use
  current location's projection) by assuming that the dataset has the
  same projection as the current location the -o flag can be used. This
  is also useful when geodata to be imported do not contain any
  projection metadata at all. The user must be sure that the projection
  is identical in order to avoid to introduce data errors.

 Or maybe all this needs to be combined into one paragraph.

 Allow user to do just "v.import datum_trans=-1"
 On man v.import the user sees
  datum_trans=integer
   Index number of datum transform parameters
   -1 to list available datum transform parameters
   Options: -1-100

 OK, he is just curious, and wants to list them.
  $ v.import datum_trans=-1
 alas does not work. He needs to pack on a load of arbitrary junk:
  $ v.import datum_trans=-1 epsg=3333 input=/dev/null output=zzz
 and still just gets
  ERROR: No output format specified, define one of flags -p, -g, -j, or -w
 which by the way do not appear on the v.import man page.
 (My actual test command was
  $ grass --exec v.import datum_trans=-1 epsg=3333 input=/dev/null
 output=zzz

 Wait, man v.in.org says
  An interesting wrapper command around v.in.ogr is v.import which
 reprojects (if needed) the vector dataset during import to the projection
 of the current location.
 But the v.import page doesn't mention this relationship.
 }}}
 Sorry for the big mess.

-- 
Ticket URL: <https://trac.osgeo.org/grass/ticket/4000>
GRASS GIS <https://grass.osgeo.org>