Bug 586372 - rpm --help and manpage are not as helpful as they could be
rpm --help and manpage are not as helpful as they could be
Status: CLOSED WONTFIX
Product: Fedora
Classification: Fedora
Component: rpm (Show other bugs)
14
All Linux
low Severity medium
: ---
: ---
Assigned To: Panu Matilainen
Fedora Extras Quality Assurance
:
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2010-04-27 08:34 EDT by Denys Vlasenko
Modified: 2012-08-16 15:50 EDT (History)
4 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2012-08-16 15:50:30 EDT
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Denys Vlasenko 2010-04-27 08:34:35 EDT
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...
Comment 1 Denys Vlasenko 2010-05-06 10:45:23 EDT
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.
Comment 2 Bug Zapper 2010-07-30 07:29:00 EDT
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
Comment 3 Jeff Johnson 2010-08-02 16:19:00 EDT
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.
Comment 4 Denys Vlasenko 2010-08-04 12:51:34 EDT
(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?
Comment 5 Jeff Johnson 2010-08-04 13:35:01 EDT
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.
Comment 6 Denys Vlasenko 2010-08-04 16:08:07 EDT
(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 :)
Comment 7 Jeff Johnson 2010-08-04 16:21:29 EDT
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.
Comment 8 Denys Vlasenko 2010-08-04 20:45:27 EDT
(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.
Comment 9 Jeff Johnson 2010-08-04 20:59:40 EDT
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.
Comment 10 Denys Vlasenko 2010-08-05 22:05:07 EDT
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:
  ...
Comment 11 Jeff Johnson 2010-08-05 22:27:27 EDT
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.
Comment 12 Jeff Johnson 2010-08-05 22:41:31 EDT
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.
Comment 13 Fedora End Of Life 2012-08-16 15:50:33 EDT
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

Note You need to log in before you can comment on or make changes to this bug.