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