rpm --help and manpage are not as helpful as they could be

[Jeff Johnson]

Tracker

[Denys (denys-redhat-bugs)]

Description of problem:

Assume you have no idea how to find out which package /bin/ls belongs to. You only know that rpm can tell you that. You run:

# rpm --help
Usage: rpm [OPTION...]
  --quiet

    Bingo. It lies right from the start (because the command
    you are looking for is "rpm -qf FILE1 FILE2...", and it
    obviously doesn't match "rpm [OPTION...]" description -
    FILE1 FILE2 part is not an OPTION)...

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

Query options (with -q or --query):
  -c, --configfiles list all configuration files
  -d, --docfiles list all documentation files
...

Verify options (with -V or --verify):
  --nofiledigest don't verify digest of files
  --nomd5 don't verify digest of files
...

      Read the above again. What is "Query/Verify" options?
      It becomes understandable only when you read *next two sections*
      and understand that there are -q and -V opts and "Query/Verify options"
      must be options which can be applied to both.
      Had the first section in the above text been put below next two,
      it would be more clear. Had --help text explain main modes of rpm
      (like -q, -V, ...) before going into their options,
      it would be even better.

The rest of the help text is equally semi-cryptic.

I created this bug because I tried to use --requires, looked at help and:

...
Options implemented via popt alias/exec:
      [what is popt alias/exec and why should I know this here?]
  --requires list capabilities required by package(s)
...

Aha! Lets try to use it... how?.... maybe this? :

# rpm --requires kexec-tools-1.102pre-96.el5_5.1.x86_64.rpm
RPM version 4.7.2
Copyright (C) 1998-2002 - Red Hat, Inc.
This program may be freely redistributed under the terms of the GNU GPL

Usage: rpm [-aKfgpWHqVcdilsKiv?] [-a|--all] [-f|--file]...

Nope.

As you see, rpm --help does not actually help me... neither does "man rpm". Of course I will google for it now, but I'd like to see help text improved...

[Denys (denys-redhat-bugs)]

Undocumented bit:
rpm --help only says that "-i, --install install package(s)", but apparently after -q, -i means --info:

$ rpm -qpi glibc-2.10.90-24.x86_64.rpm
Name : glibc Relocations: (not relocatable)
Version : 2.10.90 Vendor: Fedora Project
Release : 24 Build Date: Mon 28 Sep 2009 12:58:58 PM UTC
Install Date: (not installed) Build Host: xenbuilder4.fedora.phx.redhat.com
Group : System Environment/Libraries Source RPM: glibc-2.10.90-24.src.rpm
Size : 13856845 License: LGPLv2+ and LGPLv2+ with exceptions and GPLv2+
Signature : (none)
Packager : Fedora Project
URL : http://sources.redhat.com/glibc/
Summary : The GNU libc libraries
Description :
The glibc package contains standard libraries which are used by
multiple programs on the system. In order to save disk space and
memory, as well as to make upgrading easier, common system code is
kept in one place and shared between programs. This particular package
contains the most important sets of shared libraries: the standard C
library and the standard math library. Without these two libraries, a
Linux system will not function.

[Bug (bug-redhat-bugs)]

This bug appears to have been reported against 'rawhide' during the Fedora 14 development cycle.
Changing version to '14'.

More information and reason for this action is here:
http://fedoraproject.org/wiki/BugZappers/HouseKeeping

[Jeff (jeff-redhat-bugs)]

re: comment #1. Yes -i means different things in different contexts. There's
also the i -n "-bi" which means something else entirely.

No matter what: there's only 26 letters in the alphabet, 52 if you permit case.
RPM has far more than 52 options since like forever.

[Denys (denys-redhat-bugs)]

(In reply to comment #3)
> re: comment #1. Yes -i means different things in different contexts. There's
> also the i -n "-bi" which means something else entirely.

Please document it in the help text. That's what this bug is about.

> No matter what: there's only 26 letters in the alphabet, 52 if you permit case.
> RPM has far more than 52 options since like forever.

I do not propose to change -i to three different options.

Your comment assumes that I do. How did you arrive at the conclusion that I want -i option renamed?

The description of this bug is "rpm --help and manpage are not as helpful as they could be". Which means that I ask for "rpm --help" text to be made clearer.

One of the needed improvements is to explain what -i means in what context.

How can I help you with this?

[Jeff (jeff-redhat-bugs)]

I most definitely DO propose eliminating contextually
dependent multiple meaninsg for "-i". Its silly and stoopid
to fuss about with single character options.

Unfortunately there's no way to fix the issue properly.

There are 3 usage cases of -i.

and there is --help and "man rpm".

AFAIK, all 3 usage cases are documented in both places.

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.

[Denys (denys-redhat-bugs)]

(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
  ...
...

[Jeff (jeff-redhat-bugs)]

Re:
> Options implemented via popt alias/exec:
> *** above line is unclear. What does it mean "implemented via popt
> alias/exec"?

Try "man popt". One of the -i usage cases that you are trying to
"document" is configurable (see /usr/lib/rpm/rpmpopt). Which means
that it can be changed, overriddeen, deleted, translated, and otherwise
altered by users howsoever they wish.

You will never succeed documenting RPM "options" unless you understand
popt aliases and execs, and how they are used in RPM.

[Denys (denys-redhat-bugs)]

(In reply to comment #7)
> Re:
> > Options implemented via popt alias/exec:
> > *** above line is unclear. What does it mean "implemented via popt
> > alias/exec"?
>
> Try "man popt". One of the -i usage cases that you are trying to
> "document" is configurable (see /usr/lib/rpm/rpmpopt).

Very good explanation, can you add "these options are configurable (see /usr/lib/rpm/rpmpopt and /etc/popt)" phrase to the help text please?

> Which means that it can be changed, overriddeen, deleted, translated, and otherwise altered by users howsoever they wish.

I googled "modify /etc/popt", "modified /etc/popt" and "/etc/popt is modified" (with quotes). Zero hits for each.

In my opinion the 0.001% of users who love breaking script compatibility and inflicting other kinds of PITA on themselves may indeed tweak /usr/lib/rpm/rpmpopt and/or /etc/popt, and will undoubtedly enjoy additional pain from having rpm --help out of sync.

But I am one of the remaining 99.999% of users.

[Jeff (jeff-redhat-bugs)]

The text displayed is part of popt, not RPM. Its added to CLI parsing
tables using this line from /usr/include/popt.h:

#define POPT_AUTOALIAS { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptAliasOptions, \
                        0, "Options implemented via popt alias/exec:", NULL },

But there's no reason per-se why RPM MUST compile with that text

(switching hats I also maintain popt)
Its rather hard to have a single string attached to help messages
that pleases everyone. E.g. RPM uses popt in ways that no other
application does, and so I can't quite justify your suggestion for
adding to popt (even though its perfectly reasonable for RPM using popt).

Yes hardly anyone uses the (quite powerful) popt aliases/execs.

But still, RPM --help has no direct knowledge of _ANYTHING_
loaded as a popt alias/exec. Whether 99.99999% of users
don't realize (and don't care and don't know) that what appears
to be a CLI option is actually a popt alias/exec, there are _STILL_
extremely important differences in --help when i18n becomes
involved. The i18n process for popt aliases/execs is quite different
than it is for RPM code.

[Denys (denys-redhat-bugs)]

Ok, let's put popt discussion aside.

What is your position on the other part of my proposal: to start rpm --help text with "Operation modes" section and then describe allowable options for each section? (I am repeating the example below):

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

 *** then we go deeper into options for each mode (or group of modes with similar options), starting from the most used ones: ***

Query options (with -q or --query):
  ...

Query/Verify package selection options:
  ...

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 ***
  ...

Common options for all rpm modes and executables:
  ...

[Jeff (jeff-redhat-bugs)]

OK no popt alias/exec (but there are _STILL_ popt --help limitations)

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

Not unreasonable. The issue is purely that a separate text-only
comment needs to be written and a popt table entry to display
the text. The problem with two --help entries is that bit rot
would cause the text-only mode descriptive entry to diverge
from rpm "modes". In fact modes aren't that useful (from a
devel POV) because options tend to generalize, and (in fact)
SELinux forced rpm to be split into 5 helper executables
back in 2004 with popt exec "glue" to pretend that rpm
was still a single executable. But yr request is not unreasonable.

> *** then we go deeper into options for each mode (or group of modes with
> similar options), starting from the most used ones: ***

Again not unreasonable, but you better look at
     POPT_ARGFLAG_DOC_HIDDEN
first. In fact RPM has nearly as many options that are NOT displayed
as are displayed. SO the criteria "most used" is arguable, and incomplete
because most options are not in --help at all (largely because I don't
believe that 16 pages of spewage from --help is any help at all).
But its quite possible to reorg popt tables according to whatever criteria
one wishes, "most used" is as good as any otther (I tended towards
alphabetic, or with a similarity cluster grouping instead).

> *** current --help doesn't mention -i, -U, -e in the above line, I
> propose adding it ***

1-liner change in a popt table somewhere. not even worth discussing.

> *** similarly, here above i'd like to see mode options for which the
> below "modifier" options are valid ***

Signature/digest disablers are rather more complicated than other
options because they started life per-mode and are not (essentially, de facto)
all-mode, certainly applying to query/verify/install/erase/upgrade/checksig
"modes". As I pointed out previously, rpm got split into 5 helper executables
accorsing to some poorly perceived "mode" of execution so that SELinux
might be able to apply different labels to different "modes". In fact,
except for a _MAJOR_ split between build <-> install, modes of
operation are more cumbersome than useful. JMHO having spent 12
years now working on RPM. YMMV, everyone's does.

[Jeff (jeff-redhat-bugs)]

I should point out that adding "-i" in --help display
(where this bug started) assumes that there is onl;y one -i.

Truly there are many bug reports because one cannot do
    rpm -b -i
(because -bi is a single long option marked with POPT_ARGFLAG_ONEDASH)

and
   rpm -qi <-> rpm -q -i
has its own speshul pains because multiple popt execs need
to be written for the 5 executables (or there's a poptPeek and a poptStuffArg rewrite
to substitute --info for -i)

and finally its quite obvious that this set of single character options
has a weirdo
   -i -U -e
(hint: one of the options is capitalized).

And so we come full circle: RPM should _NEVER_ have had
3 meanings for a single -i implemented. I dinna do that,
its quite b0rken in design, yhe damage happened circa 1997.

[Fedora (fedora-redhat-bugs)]

This message is a notice that Fedora 14 is now at end of life. Fedora
has stopped maintaining and issuing updates for Fedora 14. It is
Fedora's policy to close all bug reports from releases that are no
longer maintained. At this time, all open bugs with a Fedora 'version'
of '14' have been closed as WONTFIX.

(Please note: Our normal process is to give advanced warning of this
occurring, but we forgot to do that. A thousand apologies.)

Package Maintainer: If you wish for this bug to remain open because you
plan to fix it in a currently maintained version, feel free to reopen
this bug and simply change the 'version' to a later Fedora version.

Bug Reporter: Thank you for reporting this issue and we are sorry that
we were unable to fix it before Fedora 14 reached end of life. If you
would still like to see this bug fixed and are able to reproduce it
against a later version of Fedora, you are encouraged to click on
"Clone This Bug" (top right of this page) and open it against that
version of Fedora.

Although we aim to fix as many bugs as possible during every release's
lifetime, sometimes those efforts are overtaken by events. Often a
more recent Fedora release includes newer upstream software that fixes
bugs or makes them obsolete.

The process we are following is described here:
http://fedoraproject.org/wiki/BugZappers/HouseKeeping