v.import documentation megabug

[jidanni]

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.

[annakrat]

Could you please summarize it in a readable way? And even better, please create a pull request if it's clear what should be fixed.

[nila]

This is an open source project, based on voluntary free time work. And not a giga multinational company with unlimited resources. Please respect that and I second @annakrat’s comment, “create a pull request if it's clear what should be fixed”.