Comment 7 for bug 633656

(In reply to comment #5)
> Any other change (like unclear or imprecise or obscurely positioned or ...)
> is in the eye of the beholder and needs positive suggestions on
> specifics, not broad general RFE's or comments illustrating perceived
> flaws.

Okay, here it goes. I propose the following --help text (*** are my comments):

$ rpm --help
Usage: rpm [OPTION...] [PARAM]

 *** first we let user know which modes exist and what they do: ***

Operation modes (one of these options must be present to select the operation):
  -q,--query Query database of installed packages
  -V,--verify ...
  -i,--install Install package(s)
  -e,--erase Erase (remove) installed package(s)
  -U,--update
  ...
  ...
  --initdb initialize database
  --rebuilddb rebuild database inverted lists from
                   installed package headers
  -?, --help Show this help message
  --usage Display brief usage message

 *** then we go deeper into options for each mode, starting from the most used ones: ***

Query options (with -q or --query):
  -c, --configfiles list all configuration files
  -d, --docfiles list all documentation files
  --dump dump basic file information
  -l, --list list files in package
  --queryformat=QUERYFORMAT use the following query format
  -s, --state display the states of the listed files

Verify options (with -V or --verify):
  --nofiledigest don't verify digest of files
  --nomd5 don't verify digest of files
  --nofiles don't verify files in package
  --nodeps don't verify package dependencies
  --noscript don't execute verify script(s)

Query/Verify package selection options:
  -a, --all query/verify all packages
  -f, --file query/verify package(s) owning file
  -g, --group query/verify package(s) in group
  -p, --package query/verify a package file
...

Install/Upgrade/Erase options (with -i, -U, or -e):
        *** current --help doesn't mention -i, -U, -e in the above line, I propose adding it ***
  --aid add suggested packages to transaction
  ...
  ...

Signature options (with -??, -?? or -??):
        *** similarly, here above i'd like to see mode options for which the below "modifier" options are valid ***
  --addsign sign package(s) (identical to --resign)
  -K, --checksig verify package signature(s)
  --delsign delete package signatures
  --import import an armored public key
  --resign sign package(s) (identical to --addsign)
  --nodigest don't verify package digest(s)
  --nosignature don't verify package signature(s)

Common options for all rpm modes and executables:
  -D, --define='MACRO EXPR' define MACRO with value EXPR
  -E, --eval='EXPR' print macro expansion of EXPR
  ...

Options implemented via popt alias/exec:
      *** above line is unclear. What does it mean "implemented via popt alias/exec"? What significance for me (a user who requested --help) is in this fact? And moreover, are below options applicable to any mode? Some modes? One possible way to improve it is to drop this section entirely and move every option to the relevant section above. For example, if --scripts option only applies to -q, then it should be moved into "Query" section. ***
  --scripts list install/erase scriptlets from
  ...
  --filecaps list file names with POSIX1.e capabilities

*** THE END of --help :)