Hi Chris,
The main issue is the occasional use of "dataset" as an alias for
"input". It's inconsistently available as an alias which seems not
ideal, but it also shows up in unexpected ways.
"raster edit" has only --dataset with no --input or -i:
--dataset <DATASET>
The rationale was that raster edit only takes a single dataset which is
both input and output. Input could also suggest that it won't be
modified, which is not the case here. But I see we have hesitated in
different similar (or similar looking, but subtely different) situations
if we needed to expose input, dataset or both.
"raster overview add" has:
-i, --dataset, --input <INPUT>
But "raster overview delete" and "raster overview refresh" have only:
--dataset <DATASET>
A dataset-specific one "dataset check" doesn't use it:
-i, --input <INPUT>
For dataset check, the dataset isn't modified.
Is the "dataset" alias really worth having?
Good question. Happy to hear about other's opinion on this.
A couple others are unique cases that may not be a problem. These just
stand out as different since meta_var rarely deviates from the naming
pattern.
"raster calc" has:
-i, --input <INPUTS>
Plural to suggest you can specify several ones
"raster blend" has:
-i, --color-input, --input <COLOR-INPUT>
The metavar is important to remind the semantics because it accepts a
second input dataset : --overlay <OVERLAY>
Those are the only cases I've found where the meta_var name is
different than the long name. Nearly all have <INPUT> for --input even
if there is an alias, e.g., "raster pansharpen" has `-i,
--panchromatic, --input <INPUT>`.
Similar to raster blend:
-i, --panchromatic, --input <INPUT> Input panchromatic raster dataset
[required]
--spectral <SPECTRAL> Input spectral band dataset [1.. values] [required]
The input name helps here to remember which dataset is implicit or not
when you use it in a pipeline context (input must not be specified as
the result of the previous step):
gdal raster pipeline read panchro.tif ! pansharpen multispectral.tif !
write out.tif
I checked several others that can
take multiple input datasets, and "raster calc" is the only one I
found with plural INPUTS. Maybe that's not a big deal because the
meta_var is only for display in the documentation? It could still be
worth making them consistent for readability.
Yes we could put plural INPUTS in other situations where input accepts
multiple files
Since <INPUT> is almost
always used for the positional input dataset(s), when I see
<COLOR-INPUT> it looks like possibly something other than a raster
dataset.
Should the metavar of INPUT be INPUT-DATASET in general case, and
COLOR-INPUT-DATASET for blend / PANCHRO-DATASET for pansharpen ?
--
http://www.spatialys.com
My software is free, but my time generally not.
_______________________________________________
gdal-dev mailing list
[email protected]
https://lists.osgeo.org/mailman/listinfo/gdal-dev
