Gentoo Websites Logo
Go to: Gentoo Home Documentation Forums Lists Bugs Planet Store Wiki Get Gentoo!
Bug 113032 - 'equery list -f' needs better documentation
Summary: 'equery list -f' needs better documentation
Status: RESOLVED FIXED
Alias: None
Product: Portage Development
Classification: Unclassified
Component: Tools (show other bugs)
Hardware: x86 Linux
: High enhancement (vote)
Assignee: Portage Tools Team
URL:
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2005-11-19 13:38 UTC by walt
Modified: 2005-11-23 11:09 UTC (History)
1 user (show)

See Also:
Package list:
Runtime testing required: ---


Attachments
equery-help-list.patch (equery-help-list.patch,1.01 KB, patch)
2005-11-19 17:01 UTC, Harald van Dijk (RETIRED)
Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description walt 2005-11-19 13:38:40 UTC
For example:

#equery list *madp*
[ Searching for package '*madp*' in all categories among: ]
 * installed packages
[I--] [  ] media-libs/libmad-0.15.1b (0)
[I--] [  ] media-plugins/gst-plugins-mad-0.8.10 (0.8)
[I--] [  ] media-plugins/xmms-mad-0.8 (0)

and 'madplay' was overlooked completely.  Here is another example:

#equery list *play*
[ Searching for package '*play*' in all categories among: ]
 * installed packages
[I--] [  ] media-sound/madplay-0.15.2b (0)

but mplayer and realplayer were overlooked.  And one more example:

#equery list *m*
[ Searching for package 'make.conf' in all categories among: ]
 * installed packages




Reproducible: Always
Steps to Reproduce:
1.
2.
3.




Portage 2.0.51.22-r3 (default-linux/x86/2005.1, gcc-3.3.6, glibc-2.3.5-r2,
2.6.15-rc1-gb286e392 i686)
=================================================================
System uname: 2.6.15-rc1-gb286e392 i686 AMD Athlon(TM) XP 2100+
Gentoo Base System version 1.6.13
dev-lang/python:     2.3.5-r2, 2.4.2
sys-apps/sandbox:    1.2.12
sys-devel/autoconf:  2.13, 2.59-r6
sys-devel/automake:  1.4_p6, 1.5, 1.6.3, 1.7.9-r1, 1.8.5-r3, 1.9.6-r1
sys-devel/binutils:  2.15.92.0.2-r10
sys-devel/libtool:   1.5.20
virtual/os-headers:  2.6.11-r2
ACCEPT_KEYWORDS="x86"
AUTOCLEAN="yes"
CBUILD="i686-pc-linux-gnu"
CFLAGS="-march=athlon-xp -O2 -pipe"
CHOST="i686-pc-linux-gnu"
CONFIG_PROTECT="/etc /usr/kde/2/share/config /usr/kde/3.4/env
/usr/kde/3.4/share/config /usr/kde/3.4/shutdown /usr/kde/3/share/config
/usr/lib/X11/xkb /usr/share/config /var/qmail/control"
CONFIG_PROTECT_MASK="/etc/gconf /etc/terminfo /etc/env.d"
CXXFLAGS="-march=athlon-xp -O2 -pipe"
DISTDIR="/usr/portage/distfiles"
FEATURES="autoconfig distlocks sandbox sfperms strict"
GENTOO_MIRRORS="http://gentoo.oregonstate.edu
http://www.ibiblio.org/pub/linux/distributions/gentoo"
PKGDIR="/usr/portage/packages"
PORTAGE_TMPDIR="/var/tmp"
PORTDIR="/usr/portage"
SYNC="rsync://rsync.gentoo.org/gentoo-portage"
USE="x86 3dnow 3dnowex 3dnowext X X509 Xaw3d aac acpi acpi4linux alsa apm arts
artswrappersuid audiofile avi bash-completion berkdb bitmap-fonts bzip2 bzlib
c++ cdr cjk codecs cpudetection crypt cups curl custom-cflags divx4linux dpms
dri dv dvd dvdr dxr3 ecc edl eds emacs emboss encode evms2 exif expat fam fame
ffmpeg foomaticdb fpx freetype ftp gcj gdbm gif gimpprint glibc-compat20 glut
gnome gnomedb gnutls gpgme gpm gs gstreamer gtk gtk2 gtkhtml guile hal hpn httpd
idn imagemagick imap imlib immqt-bc ipv6 java javascript jce jp2 jpeg jpeg2k kde
kig-scripting lame lcms libg++ libwww linuxthreads-tls live lzo lzw lzw-tiff mad
mbox mcal mikmod mime mimencode mjpeg mmx mmx2 mmxext mng mod motif mp3 mpeg
mpeg4 multislot mythtv ncurses network nls nntp nocd noreiserfs nptl nsplugin
nspr ntfs ntlm objc ogg oggvorbis openal opengl oss pam pcap pcre pdflib perl
png python qt quicktime readline real samba screenshot sdl server sharedmem
smime sockets speedo spell sse sse2 ssl svg symlink sysfs sysvipc tcltk tcpd tga
threads tiff truetype truetype-fonts type1 type1-fonts ucs2 udev unicode usb
utf8 uudeview v4l2 verbose vidix vorbis win32codecs xanim xine xml2 xmms xrandr
xsl xslt xv xvid xvmc yv12 zlib userland_GNU kernel_linux elibc_glibc"
Unset:  ASFLAGS, CTARGET, LANG, LC_ALL, LDFLAGS, LINGUAS, MAKEOPTS, PORTDIR_OVERLAY
Comment 1 Harald van Dijk (RETIRED) gentoo-dev 2005-11-19 14:39:53 UTC
> #equery list *m*
>[ Searching for package 'make.conf' in all categories among: ]

You forgot to quote your argument; the shell changed *m* to whatever files in
your current directory contain an m (which happened to be make.conf).

Also, the argument to equery list is interpreted as a regular expression, not as
a pattern for pathnames, so '*m*', '*play*', and '*madp*' are not the correct
syntax.

Finally, even then it's an undocumented bug/feature in older versions of
gentoolkit; the current ~arch gentoolkit already defaults to not interpreting
arguments specially in any way (with the now documented possibility to override
that using the -f option).
Comment 2 Jakub Moc (RETIRED) gentoo-dev 2005-11-19 15:31:42 UTC
# equery list 'mod_*'
[ Searching for package 'mod_*' in all categories among: ]
 * installed packages

# equery list 'mod_*' -f

[ Searching for package 'mod_*' in all categories among: ]
 * installed packages

# equery list mod_* -f

[ Searching for package 'mod_*' in all categories among: ]
 * installed packages

# emerge -pv mod_perl mod_suphp
These are the packages that I would merge, in order:

Calculating dependencies ...done!
[ebuild   R   ] www-apache/mod_perl-2.0.1-r2  3,607 kB
[ebuild   R   ] www-apache/mod_suphp-0.6.0  -checkpath +mode-force -mode-owner
-mode-paranoid 241 kB

Apparently I missed something? BTW, app-portage/gentoolkit-0.2.1_rc1
Comment 3 Harald van Dijk (RETIRED) gentoo-dev 2005-11-19 15:54:28 UTC
> Apparently I missed something?

This part:

> Also, the argument to equery list is interpreted as a regular expression, not as
> a pattern for pathnames, so '*m*', '*play*', and '*madp*' are not the correct
> syntax.

:)

For your example, equery list -f 'mod_.*' should work.
Comment 4 Jakub Moc (RETIRED) gentoo-dev 2005-11-19 16:00:04 UTC
(In reply to comment #3)
> > Apparently I missed something?
> 
> This part:
> 
> > Also, the argument to equery list is interpreted as a regular expression, not as
> > a pattern for pathnames, so '*m*', '*play*', and '*madp*' are not the correct
> > syntax.
> 
> :)
> 
> For your example, equery list -f 'mod_.*' should work.

Please, put some *human-readable* and *explicit* examples to the man page then,
or make the required syntax match a common sense (which is a test that the above
one fails badly). 
Comment 5 walt 2005-11-19 16:32:12 UTC
(In reply to comment #3)
> > Apparently I missed something?
> 
> This part:
> 
> > Also, the argument to equery list is interpreted as a regular expression...

1) Thanks for your very prompt reply, and thanks for supporting gentoo :o)

2) What document are you quoting above?  It is not in the manpage for equery.

3)  I object in the strongest possible way to the use of regular expressions
  in an end-user tool.  I own the O'Reilly book on 'sed & awk' and have read
  it multiple times and I still cannot remember how to use regexps!  equery
  is *not* (or should not be) a developer's tool, it is an end-user's tool!
  Or, perhaps, end-users like me should have our own qpkg/equery which is
  separate from the tools that you developers use?  Ignore the needs of users
  at your peril!  (I think Bill Gates said that when he was at Harvard.)
Comment 6 Harald van Dijk (RETIRED) gentoo-dev 2005-11-19 16:59:48 UTC
> 2) What document are you quoting above?  It is not in the manpage for equery.

That was a quote from my initial response; what the manpage for equery (in the
~arch version) says is

       list <local-opts> pkgspec
              This command lists packages matching pkgspec in a user-specified
              combination  of  installed  packages,  packages  which  are  not
              installed, the portage tree, and the portage overlay tree.

              <local-opts> -I cannot be used by itself;  if  -I  is  used,  -p
              and/or  -o  must be also be present.  By default, only installed
              packages are searched.  -o searches only the overlay  tree  [and
              possibly installed packages], not the main portage tree.

              -i, --installed search installed packages (default)
              -I, --exclude-installed do not search installed packages
              -p, --portage-tree also search in portage tree (/usr/portage)
              -o,    --overlay-tree    also    search    in    overlay    tree
              (/usr/local/portage)
              -f, --full-regex query is a regular expression
              -d, --duplicates only list installed duplicate packages

Here the use of regular expressions is documented.

> 3)  I object in the strongest possible way to the use of regular expressions
>   in an end-user tool.  I own the O'Reilly book on 'sed & awk' and have read
>   it multiple times and I still cannot remember how to use regexps!

The main pitfall is using * instead of .*; there's no need to have mastered
regular expressions if you just use intend to use simple ones. Having talked
with Jakub about it a little bit, would adding this to the output of equery
--help list be enough?

Examples:
  equery list x11-libs/gtk+  - list all installed versions of x11-libs/gtk+
  equery list -p -f 'mod_.*' - list all versions of all Apache modules
Comment 7 Harald van Dijk (RETIRED) gentoo-dev 2005-11-19 17:01:17 UTC
Created attachment 73201 [details, diff]
equery-help-list.patch

This patch would do exactly that. Okay? Bad idea? Any better ideas?
Comment 8 walt 2005-11-19 17:34:53 UTC
(In reply to comment #7)
> Created an attachment (id=73201) [edit]
> equery-help-list.patch
> 
> This patch would do exactly that. Okay? Bad idea? Any better ideas?

Instead of anwering your question, I will offer another question (just
like my wife taught me to do):  what is the problem with qpkg, which I
consider the perfect end-user tool?  I have never had any problem or
difficulty using qpkg, and (as a dumb-shit-end-user) I never even had
to know about the difference between what the shell wants and what
python-or-perl-or-ruby-or-whoever wants.

Is the replacement of qpgk *really* important?  What horrible thing
will happen (and to whom) if qpkg remains?

(My wife also taught me to be bitchy and *very* persistent!)

BTW, thanks again for supporting gentoo!  :o)
Comment 9 Harald van Dijk (RETIRED) gentoo-dev 2005-11-19 17:52:46 UTC
> Is the replacement of qpgk *really* important?  What horrible thing
> will happen (and to whom) if qpkg remains?

The biggest problem: it was broken and its maintainer didn't want to support it
anymore, so the bugs didn't get fixed. :) Do a search here on bugzilla for qpkg,
if you're interested. It's still installed as
/usr/share/doc/gentoolkit-*/deprecated/qpkg/qpkg; one example of a bug: try
using it to list all packages containing '++'.
Comment 10 Jakub Moc (RETIRED) gentoo-dev 2005-11-20 00:55:16 UTC
(In reply to comment #8)
> what is the problem with qpkg, which I
> consider the perfect end-user tool?  I have never had any problem or
> difficulty using qpkg

> Is the replacement of qpgk *really* important?  What horrible thing
> will happen (and to whom) if qpkg remains?

Sorry, but this won't fly. See http://tinyurl.com/dlbl3 for more. 
Comment 11 walt 2005-11-20 12:17:38 UTC
Part of my confusion is that the behavior of 'list' doesn't seem consistent, so
I can't construct a model in my head of how to use it.  Example:
#equery l mozilla
[ Searching for package 'mozilla' in all categories among: ]
 * installed packages
[I--] [  ] www-client/mozilla-firefox-bin-1.0.7 (0)
[I--] [  ] www-client/mozilla-launcher-1.42 (0)

This much is excellent -- that is exactly how I would like 'list' to work.
So...I would expect 'equery l mozil' to produce exactly the same result,
since 'list' clearly matches partial package names without using any wildcards.
It doesn't work that way, but I don't see why it can't be made to.  If some
bright user understands regular expressions then he can use -f.  Is this
completely unreasonable?

(And yes, I think putting examples in the --help section would be a great idea,
thanks.)
Comment 12 Harald van Dijk (RETIRED) gentoo-dev 2005-11-20 13:22:07 UTC
Actually, that `equery l mozilla` output is a bug (which has been fixed
already); it's because in looking for a package "mozilla-<version>", it simply
looks for any package starting with "mozilla-".
Comment 13 walt 2005-11-20 15:38:12 UTC
<sigh> So my feature was your bug.  This is just like being married :o(

Okay, would it be technically do-able to add another local-opt which would
let me type something like 'equery --noregex l moz' to get my 'buggy' behavior
back again?  I'm being persistent because I truly think that expecting users
to know regular expressions is not realistic.  I want gentoo to succeed, not
scare people away!

In fact, a package manager GUI would be far better for this purpose than any
command-line fixes I could ever dream up.  Has any work ever been done on
such a thing?
Comment 14 Harald van Dijk (RETIRED) gentoo-dev 2005-11-20 16:30:11 UTC
> Okay, would it be technically do-able to add another local-opt which would
> let me type something like 'equery --noregex l moz' to get my 'buggy' behavior
> back again?

--noregex would be a wrong name, but a --partial-name option or something
similar would probably be relatively easy to implement, and seems to be what you
would like your --noregex option to do. Just to make sure: am I understanding
you correctly about that?

> In fact, a package manager GUI would be far better for this purpose than any
> command-line fixes I could ever dream up.  Has any work ever been done on
> such a thing?

Perhaps porthole does what you want? (I don't use it myself, so I'm not sure
about what it does and doesn't provide.)
Comment 15 walt 2005-11-20 17:34:49 UTC
(In reply to comment #14)
> ...a --partial-name option or something
> similar would probably be relatively easy to implement...

Yes!  Just to clarify:  'qpkg -I zilla' also lists both of the packages I
mentioned above, and without using any special wildcards or quoting.  This
is the level of sophistication that many early users of gentoo could probably
figure out before giving up in digust  -- and that is my main concern.

If the --help menu also carefully mentioned that users who don't speak
regex could use my proposed flag as an alternative...I would be very happy!

> Perhaps porthole does what you want?...

The porthole ebuild is complaining about USE flags, so I will need to do a
little debugging.  Thanks for the tip -- and thanks for listening to my
complaints :o)

Comment 16 Harald van Dijk (RETIRED) gentoo-dev 2005-11-20 23:32:39 UTC
Better handled with a new bug IMO, see bug #113134 for that.
Comment 17 Paul Varner (RETIRED) gentoo-dev 2005-11-23 11:09:15 UTC
Fixed in gentoolkit-0.2.1_rc2, Examples have been added to the equery man page.