gdal
gdal copied to clipboard
Simplify `--help` output for new CLI?
Feature description
I'm working on a gdal raster reclassify utility for the new CLI. It has three arguments: the input/output datasets, and a table to define the reclassification. Looking at the output of --help, it's a bit difficult to spot this:
Usage: gdal raster reclassify [OPTIONS] <INPUT> <OUTPUT>
Reclassify values in a raster dataset
Positional arguments:
-i, --input <INPUT> Input raster dataset [required]
-o, --output <OUTPUT> Output raster dataset [required]
Common Options:
-h, --help Display help message and exit
--version Display GDAL version and exit
--json-usage Display usage as JSON document and exit
--drivers Display driver list as JSON document and exit
--config <KEY>=<VALUE> Configuration option [may be repeated]
--progress Display progress bar
Options:
-f, --of, --format, --output-format <OUTPUT-FORMAT> Output format ("GDALG" allowed)
--co, --creation-option <KEY>=<VALUE> Creation option [may be repeated]
--overwrite Whether overwriting existing output is allowed
-m, --mapping <MAPPING> Reclassification mappings (or specify a @<filename> to point to a file containing mappings [required]
--ot, --datatype, --output-data-type <OUTPUT-DATA-TYPE> Output data type. OUTPUT-DATA-TYPE=Byte|Int8|UInt16|Int16|UInt32|Int32|UInt64|Int64|CInt16|CInt32|Float16|Float32|Float64|CFloat32|CFloat64
Advanced Options:
--if, --input-format <INPUT-FORMAT> Input formats [may be repeated]
--oo, --open-option <KEY>=<VALUE> Open options [may be repeated]
For more details, consult https://gdal.org/programs/gdal_raster_reclassify.html
WARNING: the gdal command is provisionally provided as an alternative interface to GDAL and OGR command line utilities.
The project reserves the right to modify, rename, reorganize, and change the behavior of the utility
until it is officially frozen in a future feature release of GDAL.
Some thoughts:
- The only option that is specific to this program is "--mapping". Could we make the options that are unique to a particular program more obvious?
- The distinction between "options" , "common options", and "advanced options" isn't obvious. For example "--oo" is an "advanced option", but "--co" is an "option", and "--config" is a "common option". One could argue that everything except
--mappingis a "common option" - Does every utility need
--driversand--version, or can those only be documented at the root level (gdal --driversorgdal raster --driversbut notgdal raster reclassify --drivers) - Four alternative ways to write
--output-formatand three to write--output-data-typeis a lot.
Additional context
No response