gdal icon indicating copy to clipboard operation
gdal copied to clipboard

Simplify `--help` output for new CLI?

Open dbaston opened this issue 7 months ago • 0 comments

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 --mapping is a "common option"
  • Does every utility need --drivers and --version, or can those only be documented at the root level (gdal --drivers or gdal raster --drivers but not gdal raster reclassify --drivers)
  • Four alternative ways to write --output-format and three to write --output-data-type is a lot.

Additional context

No response

dbaston avatar May 02 '25 17:05 dbaston