[gdal-dev] inconsistent naming for the CLI "input" argument

[Even Rouault]

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.