dswim/swim.pod

=head1 NAME

swim - package administration and research tool for Debian packages

=head1 SYNOPSIS

swim [options]

=head1 DESCRIPTION

B<swim> is a powerful I<package administration> and I<research tool> for
both an I<installed Debian distribution>, and/or I<not-installed virtual
Debian distribution(s)> allowing querying of software packages with a
variety of package information options, and powerful searches. Virtual
options which include ftp, installation, and package removal capabilities
can be seamlessly combined with querying or searches. B<swim> can be used
on computer systems which either have, or do not have a Debian
distribution installed. 

=head1 COMMAND LINE OPTION SYNTAX

When you press ``B<swim> <B<enter>>`` you will see a listing of command
line options in a particular syntax. This is to help you understand under
what context to use the options. When you enter the options on the command
line, the brackets, parentheses, braces, diamonds, and question marks are
not actually used.

B<Major Mode Option>

All command line options for B<swim> always start with a
B<major mode option>, except for ``swim
<enter>`` which will show the whole listing of
options. A major mode option is surrounded in braces
B<{ major mode option }>. In the case of
{--search} there are the alternative major mode
options {--refinesearch} and
{--research}, but because --search needs
to be used first before either of these two options,
--refinesearch and --research are
surrounded in parentheses (). 

Note: Through the other chapters of this manual B<{}> is
assumed for the B<major modes> in the
B<usage:> section shown at the beginning of every chapter. 

Let's take a closer look at this situation:

 {--search ? (--research || --refinesearch) <pattern(s)>}

`B<||>' or `B<|>' are used to indicate `B<or>', `B<?>' indicates
`B<optional>', <diamond> indicates an B<argument> (a required argument -
see Arguments below), (parenthesis) means `if used, must be used after the
previous required option was used'. Note: for readability C<--research>
and C<--refinesearch> are not surrounded in C<{}>. 

B<Normal Options>

Options to the major mode options are enclosed in brackets B<[ option to
major mode ]>.  C<swim [-n]> <C<enter>>; (assume enter from here on out),
for instance, will show all the command line options without using the
pager. The pager which swim uses can be set in I<swimrc> (see
I<swimrc(8)>).  ``C<swim {--help} [-n]>'' will provide brief explanations
of all of swim's options without using the pager. In this case the major
mode option B<{--help}>, and the option B<[-n]> were used. 

B<Dashes>

Options which have a single dash can be combined with other single dashed
options B<(-qaint)>. Double dashed options need to be entered by
themselves B<(--help --nopager)>, many double dashed options have an
alternative single dash option B<(-n for --nopager)>. The meaning of
options is related to the major mode they are being used with. B<[-n]>
means no pager when called with B<{--help}>, but it's a reference to the
not-installed databases when used with B<{-q --query}>, fortunately most
options do not have double meanings. 

B<Arguments>

Many options require an argument. Arguments are enclose in diamonds 
<B<argument>>. An argument to an option may also be optional in which case
a question mark ``B<?>'' will be placed between the option and the
argument.  B<[-l ?> <B<[--df]>>B<]> illustrates such a situation.  B<[-l]>
shows a file listings, and optionally the option B<[--df]> can be use with
B<[-l]> to show an expanded listing. 

B<[--dbpath> <B<dir>>B<]> requires an argument, this time the argument
would not be another option, but rather it is a directory. 

Rule: When an option is an argument to another option it can be written
anywhere, but when a non-option is an argument <B<dir>>; B<(notice no
brackets)> it has to be placed directly after the option.  Sometimes,
there may be alternative arguments divided with ``B<|>''. 
<B<argument1|argument2>>;  means use argument1 or argument2, but not both. 

Based on what we now know, let's compare this situation to the
B<{--search}> situation shown above: 

 [--ftp ? --source | --source_only ? <[--diff]>]

In this case B<--source> or alternatively
B<--source_only> can be optionally used along with
B<--ftp> because they aren't in parentheses
B<()> (also notice: | was used instead of ||, but means the
same thing ``or'').  B<--diff> can optionally be provided as
an argument to either B<--source> or
B<--source_only>. For readability --source and --source_only
weren't enclosed in brackets.

B<Global Arguments>

A B<global argument> can be typed anywhere on the command
line, and can be an option or text. If global arguments
exist they are placed last after the list of normal
options that can be used with a major mode
option. 

[targets | -S] and [targets|APT|DF] are
examples.  {-q}, {--initndb}, and
{--rebuildndb} all use global arguments.  

B<Minor Mode Options>

{-q --query} will generally use zero or more
minor mode options [-afpgn --dir], with
one exception (see QUERYING). 

=head1 VERSION

usage: B<swim --version>

This shows the version for the swim program.

=head1 HISTORY

usage: B<swim --history>
       B<swim -h>

options:  B<[--arch> <B<architecture>>B<] [--dists> <B<distribution>>B<]>
          B<[--n] [--dbpath> <B<dir>>B<] [--root> <B<dir>>B<]>  



This shows a shell-like history of searches and the most recent --stdin
edit. History is numbered with the most recent action being 1, and the
earlier actions being of a higher number until the maximum amount of lines
set in the HISTORY variable in swimrc(5). A separate history is kept for
each architecture-distribution.

=head1 MAKING INSTALLED SYSTEM DATABASES

=head2 Initial database making, and Rebuilding for an Installed system.

usage: B<swim --initdb>
       B<swim --rebuilddb>

Options:  B<[--dbpath> <B<dir>>B<] [--root> <B<dir>>B<] [--lowmem]>
          B<[--split_data> <B<lines>>B<]> 

An I<installed Debian distribution> is one in which packages are installed
using B<dpkg> or some front-end to B<dpkg> like B<apt> or B<dselect>;
B<swim> supports installation through B<apt>.  These major modes are for a
computer with an I<installed Debian distribution> and make the databases
which allow querying and searching capabilities for the installed
distribution. 

B<--initdb> is run when the databases do not exist yet, B<--rebuilddb> is
run if the databases have become corrupt, or you want to rebuild the
databases instead of updating them. 

B<--dbpath> can be specified as an alternative location for where the
databases will be made.  The default location is "F</var/lib/dpkg>".  An
argument like "F</otherstuff>" could be provided, and then the databases
would be made here instead.

B<--root> allows a database to be made for a Debian distribution installed
on a different partition.  If the distribution is mounted on
F</New_Debian>, "F</New_Debian>" would be the argument to root.  The
databases would be made for the Debian distribution installed on the
"F</New_Debian>" partition. 

B<--dbpath> and B<--root> can be used together.  Given the previous two
examples, the databases would be made on "F</New_Debian/otherstuff>",
assuming "F</New_Debian/otherstuff>" actually existed.

B<--lowmem> uses a method which uses a small amount of memory to make the
databases.  By default B<--initdb> and B<--rebuilddb> use a method which
fully takes advantage of memory, this is a good thing, because it means
the databases are made in a quicker manner.  On a computer with a K6-200
CPU, 64MB of memory, and 1500 installed packages, the databases can be
made in 4.5 minutes using the default method, and 11 minutes using the low
memory method. The high memory method is the default because in general
the size of a distribution is related to how much resources a computer
has, and probably a large installation is unusual.  If you get an "out of
memory"  when you use the default method, or if your system is overloaded
to begin with, the B<--lowmem method> is the prefered way. 

B<--split_data> determines the size of the files in the temporary
directory used to contruct the database.  The default is 25000 lines per
file.  If you are using the B<--lowmem method> you may want to provide a
different argument to B<--split_data>, like "B<--split_data 10000>".  This
is a subject of experimentation.

=head2 UPDATING

usage: B<swim --db>

options: B<[--dbpath> <B<dir>>B<] [--root> <B<dir>>B<] [--check]>

B<--db> allows you to update the databases by hand when packages have been
removed, added, or changed.  swim will automatically run B<--db> under
certain conditions.  

B<--check> prints out the changes to STDERR, and the total to STDOUT
without proceeding with the update. 

See B<--initdb> for options B<--dbpath> and B<--root>. 

=head2 REBUILDING THE SEARCH

usage:  B<swim --rebuildflatdb>

options: B<[--dbpath> <B<dir>>B<] [--root> <B<dir>>B<]>

swim makes the flat databases F<searchindex.deb> and F<dirindex.deb> for
doing I<powersearches>.  Instead of rebuilding these databases everytime
B<--db> is run, new information is just appended to these databases, and
old information is kept.  Generally, this is not a problem because only
files and directories which the other databases actually know something
about will be refered to.  But in a situation where a file has changed
into a directory, the I<powersearch> may not work properly, because the
old file name remains in F<searchindex.deb>, and the new directory name is
now in F<dirindex.deb> directory.  In general, it takes a lot of changes
to the installed system before it is really becomes necessary to rebuild
the flat databases.  This process takes less than a minute on a K6-200
with 1500 packages. 

See B<--initdb> for options B<--dbpath> and B<--root>. 


=head2 FILES

Databases which are made:

 packages.deb
 fileindex.deb
 statusindex.deb
 groupindex.deb
 searchindex.deb
 dirindex.deb

=head1 IMPORTANT DEBIAN DATABASES FOR NOT-INSTALLED DATABASES

=head2 A. downloading the important databases with --ftp.

usage: B<swim --ftp>

options: B<--Contents> <B<DF|directory>> 
         B<--Packages> <B<DF|directory>> 
         B<[--dists> <B<distribution>>B<] [--arch> <B<architecture>>B<]>
         B<[--onec] [--Release_only]>


=head2 OVERVIEW

B<swim> provides a method so that all information about an existing Debian
distribution is quickly accessible through databases.  Debian already
provides flat file databases for all its distributions.  One database
called "F<Contents-(architecture)>" provides a complete listing of all the
files associated with each package, the other much more important database
called "F<Packages>" provides everything from the Package's description,
to all the dependencies for that package.  The Packages database is a
crucial database for other important Debian administrative tools like
B<dpkg> and B<apt>. 


=head2 DISTRIBUTION DEFINED

Debian Distributions choose a name which reflect the development state of
that distribution.  The distribution named "I<unstable>" is where the
majority of the development processing occurs, after I<unstable> has
reached a certain level of maturity, it's copied over to a new
distribution called "I<frozen>" which is tested extensively before
becoming the new "I<stable>"  distribution.  The I<frozen distribution>
retains the I<Release version number> of the I<unstable distribution>, and
the I<unstable distribution> receives a new I<Release version number>. 
Eventually, I<frozen> becomes I<stable>, and at this point both I<frozen>,
and the older I<stable distribution> are removed.  Code names are
associated with the I<Release Version number> given for each of the
distributions.  This is much better for mirroring Debian sites. 

B<swim> was designed to ignore these code names, and instead shows the
user the I<Release version number> associated with the distribution.  Swim
users must always use the real distribution name, or swim will not work
properly.  This is a nice feature because it allows user to make decisions
related to the management of their databases, and makes research much more
easier. 

The other Debian distribution which swim recognizes is I<experimental>. 
This distribution I<does not have any Release version number>, and
contains packages which are considered risky because of their development
level. 

=head2 SECTIONS

Each Debian distribution has sections related to the relationship of each
of the packages to the I<Debian's Policy Manual>.  In "I<main>" there are
packages which have a correct relationship with these Policies.  Packages
in "I<contrib>" comply with the I<DFSG> (I<Debian Free Software
Guidelines> found in the I<Debian Policy Manual>) but have various
limitations like requiring a package which is found in non-free, or is not
in the Debian archive.  Packages in "I<non-free>" do not comply with the
I<DFSG> but are electronically distributable across international borders. 
The "I<non-us>" section is found outside of the United States and exists
for packages which have export restrictions.

=head2 ARCHITECTURES

Distributions also have architecture specific sections since not all
packages compiled for one architecture can run on all other
archictectures, however, there are a large percentage of packages which do
run on all architectures.  The architectures are I<alpha>, I<arm>,
I<i386>, I<m68k>, I<powerpc>, I<sparc>, and more recently I<hurd-i386>
which represents packages for the hurd GNU kernel for the i386
architecture. 

=head2 SWIMZ.LIST

B<--ftp> uses a file called F<swimz.list> which has the same type of
format (see format below) as the F<sources.list(5)> which B<apt> uses. 
There are some differences.  The B<first difference> mentioned above
requires that the distribution names never should be the code names for
the I<Release version>.  B<Secondly>, B<apt> only retrieves databases
specific to one archictecture, normally the one you are running B<apt> on. 
With B<swim> though you can fetch databases for any, or every architecture
by adding the architecture to "deb" with a hyphen (deb-hurd-i386).  If deb
has no architecture appended it is assumed that the architecture you want
is the same as the system you are running B<swim> on.  B<Thirdly>, at this
time B<swim> only supports the ftp method.  B<Fourthly>, you can change
F<swimz.list> as often as you want without worrying about databases being
removed so that that the F<swimz.list> and the downloaded databases match. 
This would occur with B<apt's> F<sources.list(5)> if you removed a site. 
B<Fifthly>, databases are kept in a compressed state.  B<Sixthly>, because
the list is used for both Contents and Packages, more flexibility is
provided by only allowing the default distribution/archictecture or
distribution/architecture provided on the commandline to be downloaded.

For B<apt> users:  If you are using B<apt>, and B<swim> together it is a
good strategy to use the real distribution name in the F<sources list(8)>,
and to have an exact copy of the F<sources.list(5)> ftp sites in the
F<swimz.list>.  Packages databases specific to the architecture B<apt> is
using can be retrieved using B<swim --apt --update> (this also will keep
track of the Release version), and then B<swim> can be used to fetch the
architecture specific F<Contents database> as shown below.  It should also
be of interest to note that Packages downloaded by either swim or apt can
be used interchangeably by using 'cp -a' and 'gzip -d' or 'gzip -9'. 

Here is a brief outline of the format required by F<swimz.list>.  

B<deb uri distribution [section ...  ]>

B<deb> - represents a standard Debian distribution.  And is simply written
as deb or with the architecture appended (B<deb> or B<deb-alpha>).

B<uri> - Universal Resource Identifier is exactly how you would enter an
address into a web browser.  This address is the base of a Debian
distribution, generally this is right before the directory called
"F<dists>". So if F<dists> is found in F</stuff/pub/debian/dists>, and the
site is B<somewhere.com> then the uri would be
F<ftp://somewhere.com/stuff/pub/debian>. 

B<distribution> - This can be I<unstable>, I<frozen>, I<stable>,
I<experimental>. Distribution can also be a path which must end with a
slash like F<unstable/binary-i386/>. This is used when there is no section
as in the experimental distribution or in sites which do not have symlinks
to the non-us section.  No section would be mentioned in this situation. 
 
B<section> - I<main>, I<contrib>, I<non-free>, I<non-US> (write it this
way). 


=head2 SWIMZ.LIST EXAMPLES

Examples (each on one line):

B<deb-alpha ftp://somewhere.com/stuff/pub/debian unstable main contrib
non-US>

This will fetch the alpha databases from somewhere.com for the unstable
distribution for the main, contrib and non-US sections.

Note: In these next two examples you can not append any architecture to
deb with a hyphen. 

B<deb ftp://somewhere.com/stuff/pub/debian project/experimental/>

This will fetch the experimental database, but there is 
not a Contents-(architecture) database for this distribution.  Notice that
it ends with a slash.

B<deb ftp://somewhere.com/stuff/pub/debian-non-US stable/binary-i386/>

This will fetch the i386 databases for the stable distribution for non-us,

=head2 FTP OR APT?

How you use major mode B<--ftp> depends on your goals.  Even if you are
using B<apt>, you may be interested in keeping tabs on different
architectures.  In this case you would have to download the I<Packages
databases> specific to these architectures.  If you are only interested in
the architecture which B<apt> is interested in, then you only need to use
B<--ftp> to fetch the I<Contents database(s)>.  But, because it isn't a
requirement to set up a virtual filesystem, you are not required to fetch
the Contents database.  The B<advantages> of fetching the Contents
database is determined by the method you choose to make the database (see
C<--initndb>).  These advantages include the ability to I<view a listing
of the files and directories> associated with a package, the ability to
I<query files and directories> to find out which packages relate to them,
and the ability to perform a I<powersearch> on all the files and
directories to find the associated packages. 

=head2 OPTIONS

B<Remember:>  If you want to download a different 
distribution/architecture other than the default specified in your
configuration file, you must specify this on the commandline.

B<--Packages> determines where you want the Packages database as well as
the Release data put when they are downloaded.  The B<DF argument> implies
that the databases will be put in your default directory (see swimrc(8)).
These databases can later be located by the major modes B<--initndb and
--rebuildndb> just by using B<DF> as an argument.  Alternatively, these
databases can be put in any directory you choose by providing a
B<directory as an argument>.

B<--Contents> determines where you want the F<Content-(architecture)>
database(s) put.  (see --Packages).

B<--onec> will download only one Contents-arch per
distribution/architecture specified on the commandline or by default.

B<--Release_only> will download only the Release data for the
F<swimz.list> or particular F<Package(s)> mentioned on the command line. 

B<--dists> will only find the distribution which corresponds to the
argument provided this option. 

B<--arch> will only find the architecture which corresponds
to the argument provided this option.  The different architecture needs to
be specified in swimz.list with a hyphen and the architecture appended to   
deb (deb-(arch)).

=head2 B. downloading the important databases with apt, and maintenance
options.

usage: B<swim --apt> 

options: B<[--update] [--clean] [--autoclean] [--check]>

Please read "B<A. downloading the important databases with --ftp>" for
more information. 

B<--update> calls B<apt> to download the Packages databases.

B<--clean> is a call to an B<apt> option to remove any packages stored in
B<apt's> storage area for downloaded packages.  The default for this
storage area is F</var/cache/apt/arhives>

B<--autoclean> will only clean out packages which are not
found in apt's cache.
   

B<--check> tests and updates apt's cache.


=head1 MAKING NOT-INSTALLED DATABASES

usage:  B<swim --initndb>
        B<swim --ndb>
        B<swim --rebuildndb>

options: B<[--Contents> <B<target|FDBtarget|DF|FDBDF>>B<]>
         B<[--main] [--contrib] [--non-free] [--non-us]>
         B<[--arch> <B<architecture>>B<]> B<[--dists> <B<distribution>>B<]> 
         B<[--dbpath> <B<dir>>B<] [--root> <B<dir>>B<] [--alt]>
         B<[--split_data> <B<lines>>B<] [-v] [--cron]> 
         B<[targets|APT|DF]>

=head2 OVERVIEW

The B<not-installed database> provides swim with many capabilities like
the searching, and querying of packages which do not actually exist on the
live filesystem, as well as the ability to seamlessly install packages
while searching or quering, or the ability to fetch the packages source
code. The I<virtual filesystem> is optional, but it is highly recommended.
These two major mode options set up these databases, after determining the
level of interaction which you want. 

Whenever B<swim> makes databases it thinks only in terms of one
distribution and one architecture.  This keeps things logical.  B<swim>
does have the ability to take Packages files with multiple architectures,
and distributions, and to extract information for one distribution and one
archictecture to make its databases.  This could provide interesting
information from dumps from B<apt> (C<apt-cache dumpavail>). 

B<--initndb> creates the initial not-installed databases for a particular
architecture and distribution, and B<--rebuildndb> remakes the
not-installed databases for that same architecure and distribution. If not
otherwise specified B<swim> I<will use the values> it finds in F<swimrc>
to determine what architecture and distribution you want to use to make
B<swim's> databases.  Otherwise... 

=head2 OPTIONS

B<--arch> allows an argument to override the B<architecture> found in
F<swimrc>.

B<--dists> allows an argument to override the B<distribution> found in
F<swimrc>.

B<--alt> is used for a distribution with a Debian archival
structure, but which has a different name.  This allows for alternative
distributions.

When B<APT> or B<DF> are provided as arguments (see below), by default the
F<Packages> which pertain to the sections found in F<swimrc> will be
shown.  If you only want certain sections you may specify them on the
command line.  If you are not using B<APT> or B<DF>, it is a good idea to
make sure that either the sections found in F<swimrc> or the sections you
put on the command line match the F<Packages> you a targetting because
this is much more effecient. 

B<--main> will override the sections found in F<swimrc>, and will use this
section. 

B<--contrib> will override the sections found in F<swimrc>, and will use
this section

B<--non-free> will override the sections found in F<swimrc>, and will use
this section

B<--non-us> will override the sections found in F<swimrc>, and will use
this section

Global arguments B<targets|APT|DF> must be used with either of these two
major modes to find the F<Packages> databases.  targets can be a full path
to one or a set of F<Packages>.  B<APT> will use the F<Packages> found in
F</var/state/apt/lists>, and B<DF> will use the Packages found in the
default directory for B<swim> (see C<--ftp>).  If you use either B<APT> or
B<DF> you will be given an B<interface> which allows you to choose one
F<Packages> database for each section you would like to use from the
various sites.  This B<interface> shows the B<site>, B<date>, B<size> and
B<Release version> for each F<Packages>. 

B<--cron> allows you to override the B<interface> produced when B<APT> or
B<DF> is provided as an argument.  This is useful if you want to automate
the database making process.  B<--cron> will choose the newest
database(s), if cron notices that the Release version has changed, cron
will not proceed, but will provide a warning instead.  This allows you to
make the appropriate changes and choices. 

B<--Contents> can be give one of four arguments:  

B<1).> If you have a F<Contents-(architecture)> database in a target
location you know about you may provide a path to the location.  The
F<Contents> database can be compressed. 

B<2).> If you prepend the path with the letters B<FDB> (meaning flat
database)  when the databases for swim are made, instead of using the
Contents database to make:

 nfileindex-arch-dists.deb
 nsearchindex-arch-dists.deb 
 ndirindex-arch-dists.deb

only the F<ncontentsindex-arch-dists.deb.gz> database will be made which
allows the ability to view file/dir listing for not-installed packages,
but does not provide the virtual file system or powersearch capabilities
which the other databases would have provided.  

B<3).> The argument B<DF> may be used if you have used B<--ftp> with the
B<DF> argument to the option B<--Contents> (see C<--ftp>).  In this case
it is assumed you are also using global arguments B<DF> or B<APT> for the
Packages databases. This will give you an B<interface> (if --cron isn't
used) allowing you to choose one F<Contents> database for the particular
distribution you want to make the databases for. 

B<4).> B<FDB> does the same exact thing with B<DF> as it does with the
before mentioned B<FDBtarget>, and provides the B<interface>. 

B<-v> will only work if you have dpkg installed.  It allows swim to verify
B<swim's> own built-in version comparison function with B<dpkg's version
comparison function>.  This is good for debugging purposes, and produces a
report called F<.version_compare> in the same location that B<swim's>
databases are made. 

B<--split_data> is only advantageous if B<--Contents> is being used.  See
B<--initdb> for more information about the B<--split_data> option.

See C<--initdb> for options C<--dbpath> and C<--root>.

=head2 UPDATING

B<--ndb> has the same options as --initndb and --rebuildndb except for
--split_data.  It also has a new option B<--nue> which will never have to
be used unless the experimental distribution or non-us section are found
in Contents (which presently isn't the case).  B<--check> prints out the
changes to STDERR, and the total to STDOUT without proceeding with the
update.  B<--status_only> can be used after a new package has been
installed to update the status, after which -qni and -qi will correlate
properly.

=head2 REBUILDING THE SEARCH 

B<--rebuildflatndb> serves the same purpose that --rebuildflatdb serves.

=head2 FILES

Databases and reports which are made (arch = architecture dists =
distribution): 

 npackages-arch-dists.deb
 nfileindex-arch-dists.deb requires --Contents
 nstatusindex-arch-dists.deb
 ngroupindex-arch-dists.deb
 nsearchindex-arch-dists.deb
 ndirindex-arch-dists.deb
 ncontenstsindex-arch-dists.deb.gz requires --Contents
 .packagesdiff-arch-dists.deb requires --Contents

=head1 PREPARING YOUR INSTALLATION FOR APT

usage: B<swim --audit> 
       B<swim --status>
       B<swim -C>

If you are using B<apt> with B<swim>, and this is the first time you are
using it with your installation, check your live installation with this
major mode.  This is a call to B<dpkg -C (--audit)>, and will show any
packages which are not properly configured or installed.  If you get any
output, make corrections. The goal is to get absolutely no output
whatsoever because it is under these conditions that apt will work
properly.  See the B<--purge>, B<-r>, B<--remove> options for B<-q> to
remove the offending packages. You may have to remove the package by hand
under unusual situations like when it is not just dependencies (see C<-T>)
between packages keeping the package from being removed perhaps due to a
broken script (see C<--scripts>). In an extreme case you could manually
remove the entry for this package from the F</var/lib/dpkg/status>
database, and hunt down and remove all the files associated with the
package with B<swim's -l> option.  When you are done if you still want
some of the packages you removed, use B<apt> to reinstall them with
B<swim's -xyz> option. Also, B<apt> provides its own built-in method to
clean up your system, and will provide instructions, but you still may
have to do some of the cleaning yourself as discussed above. 


=head1 QUERYING THE INSTALLED AND NOT-INSTALLED DATABASES

usage: B<swim -q [-fpgn --dir] [targets | -S]>
       B<swim --query [-fpgn --dir] [targets | -S]>
       B<swim -qa || swim --query -a> 

options: B<[--total -t] [-i] [-l ?> <B<[--df]>>B<] [-d] [-c]>
         B<[--scripts] [--preinst] [--postinst] [--prerm]> 
         B<[--postrm] [-v] [--dbpath> <B<dir>>B<] [--menu -m]> 
         B<[--shlibs] [-T] [--pre_depends] [--depends> 
         B<[--recommends] [--suggests] [--conflicts]> 
         B<[--replaces] [--provides] [--md5sum]]> 
         B<[--copyright] [--changelog] [--allgroups]> 
         B<[--arch> <B<architecture>>B<] [--dists> <B<distribution>>B<]> 
         B<[--ftp ? --source | --source_only ?> <B<[--diff]>>B<]> 
         B<[--stdin] [--extract> <B<ALL|archive|PWD!archive>>B<]>
         B<[-xyrz --remove> <B<[--nz]>>B<] [--purge] [--apt2df]> 
         B<[--df2apt] [--root> <B<dir>>B<]>

global arguments: B<[targets | -S ?> <B<\d{1,}>>B<]>

Quering almost always involves using B<-q or --query> with zero or one or
a combination of the B<minor mode options> (package specification
options), and one or more (only one for C<-g>) targets specific to the
minor mode, or the results of a search (C<-S>). [C<-S> can be provided a
numerical argument pertaining to the past history.]  This can be combined
with one or more options.  The one exception is "B<swim -q --allgroups>". 

B<--query or -q> can be used by itself or with B<-n> to query known
package names or package names with versions.  "B<swim -q test1
test2_0.3-1>"  would produce the output: 

 test1_1.0-2
 test2_0.3-1


=head2 MINOR MODES

B<-n> is the minor mode option to access the I<not-installed system>, it
can be combined with the minor mode options B<-a>, B<-g>, B<-f>, or it can
be used by itself.

B<-a> allows I<every package> on an installed or not-installed (B<-n>) 
system to be queried.  "B<swim -qan>" will show all the package names with
versions for the not-installed system

B<-f> allows I<files or directories> to be queried, when used without any
options the package name with version is shown.  B<--dir> will only query
directories, this is useful if you are not sure whether what you are
quering is a directory or a file.  When a directory is queried, swim shows
all packages which exist below the queried directory.  "B<swim -qf />" is
exactly the same as "B<swim -qa>".  Hint:  "B<swim -qf .>" and "B<swim -qf
*>" are quite different, the first shows all packages which exist below
the current directory, and the second will show the package which each
file in the current directory comes from. 
 
B<-g> will query a I<group> (also called a section, see C<-i>)) of
packages. Groups represent subjects which packages with similiar
characteristics are catagorized by.  To view all the groups found in an
installed or not-installed system use "B<swim -q --allgroups>" or "B<swim
-qn --allgroups>".  "B<swim -qg hamradio>" or "B<swim -qng hamradio>"
shows all the package names for the hamradio group. 

B<-p> is used to query a I<Debian package>, these packages are
distinguished by their "deb" ending, but swim can tell whether a file is a
debian package even without the ending.  Called without any options the
package name with version will be shown. 


=head2 SPECIFYING THE DATABASES TO USE

B<--dists> will use the databases for the argument given, otherwise the 
databases pertaining to the value found in swimrc will be used.

B<--arch> will use the databases for the argument given, otherwise the
databases pertaining to the value found in swimrc will be used.

Example: B<swim -qat --arch hurd-i386 --dists unstable>

Assuming these databases exist this will show all packages and their
versions for the unstable distribution and architecture hurd-i386 even if
the values in F<swimrc> are i386 and stable.

see C<--ftp> and C<--initndb> for more information about the databases.


=head2 OPTIONS

B<--total or -t> are I<used to override the output suppressor>.  The
output suppressor will not show output if a certain number of packages is
exceeded, instead it will show the number of packages you are querying. 
This is useful for two reasons, first, knowing the number of packages you
are quering can be very informative, second, it gives you a chance to add
to the command line a pipe to a pager, ex: "B<swim -qat | less>".  You can
set the number that the output suppressor works at as high or low as you
want in the F<swimrc(8)> file.  By design the B<-t> option will have to be
used if the B<-i> option is used and more than one package is being
queried.  This option can also be used to alter the output of the script
related options (see C<--script>).

B<-i> provides I<information> about each package being queried.  The
format differs slightly for the installed packages versus the
not-installed packages.  See FORMAT: 

B<-l> provides a listing of the files associated with a package.  If the
option B<--df> is provided as an argument, all the directories associated
with package will be shown.  It is important to remember that many
packages provide directories which become important to them after they are
installed, so the option B<--df> often provides necessary information
which B<-l> called by itself would have not. 

B<-d> shows the documentation which the package provides found in
F</usr/doc/*>, F</usr/man/*>, F</usr/info/*>.  Other documentation which
the package may provide in a non-standard location will not be shown. 
B<-d> takes precedence over B<-l>, so if B<-l> is used on the command line
with B<-d>, only the output for B<-d> will be shown. 

B<-v> is a special option which works only with the minor mode B<-p>.  It
can be used with B<-l>, B<--df>, B<-d>, to show the packages files and/or
directories in long format (C<ls -l>). 

B<-c> will show the configuration files packages use.  If the package does
not have a configuration file then nothing will be shown. The output will
show the file and its path indented one space with the B<MD5 checksum>. 
This will not work with B<-n>. 

B<--scripts> shows all scripts associated with a package with the name of
the script presented before each script in this way
B<#####scriptname######>.  If the scripts are called individually by using
the script options B<--preinst>, B<--postinst>, B<--prerm>, or B<--postrm>
no title is shown, this is nice for writing to a file.  If B<-t> is used
with the individual script options a title will be shown, this makes sense
because normally only individual packages would be queried to write a
script to a file, and B<-t> wouldn't be used in this situation.  Scripts
are the soul of Debianized packages allowing packages to be installed,
configured, and removed seamlessly and cleanly under all kinds of
conditions.  These options do no work with B<-n>. 

B<--menu or -m> is used to view menufiles which belong to various
packages. If the package does not have a menufile nothing will be shown. 
This option can be useful in troubleshooting a menu entry which does not
seem to work, or in finding out where the menu entry is.  I<Joost
Witteveen's Debian menu system> is a centralized program which interacts
with all kinds of menus.  I<Please read the documentation> "B<swim -qd
menu>" which comes with the menu package to find out more.  This will not
work with B<-n>.

B<--shlibs> shows a list of shared libraries certain packages supply.  The
I<Debian Packaging Manual> (packaging-manual) provides detailed
information about the format of a shlibs file.  This will not work with
B<-n>.

B<--copyright> does a case insensitive search for copy or license in the
F</usr/doc/packagename> directory.  This should show how the package
relates to I<Debian's Policy Manual>. 

B<--changelog> searches for any files in F</usr/doc/packagename> which
look like changelogs.  Debian packages always have a I<Maintainer's>
changelog for the package.  There may be a separate changelog kept by the
author of the program. 

=head2 PACKAGE RELATIONSHIPS

B<-T> shows all the package relationships of packages.  Individual package
relationships can be viewed using B<--pre_depends>, B<--depends>,
B<--recommends>, B<--suggests>, B<--replaces>, B<--conflicts> or
B<--provides>. Package relationships are the spirit of Debian packages,
here is a quick overview briefly reiterating what can be found in the
I<Debian Packaging Manual>.  I<Package Maintainers> set these
relationships in control file fields of the same name. 

=head2 Dependencies 

I<Pre-depends> - means that the pre-depended package or packages must be
installed before the queried package can be installed.  Most packages
which have pre-dependencies are usually essential and required packages.

I<Depends> - declares an absolute dependency to another package or
packages either I<real or virtual>.  The queried package cannot function
without this other package.

I<Recommends> - declares a strong, but not absolute dependency to another
package or packages either I<real or virtual>.  You would usually find the
recommended package together with the queried package in a normal
installation. 

I<Suggests> - can be one or more packages either I<real or virtual> which
would be useful to the queried package, but are not necessary. 

=head2 Alternative Packages

I<Conflicts> - is a package or packages either I<real or virtual>
which would cause problems with the queried package, and would not be
allowed to be installed while the queried package was installed.

=head2 Overwriting files and Replacing Packages 

I<Replaces> - allows the queried package to replace another package or
packages by overwriting their files, after which the previous package
would be considered to have disappeared. Essentially this allows the
queried package to take over the package or packages.  In a situation
where there was a Conflict between the queried package and these packages
this field would help determine which packages should be removed.

=head2 Virtual Packages 

I<Provides> - declares a virtual package which may be mentioned in
I<Depends>, I<Recommends>, I<Suggests>, or I<Conflicts>.  I<Virtual
packages> allow one or more packages to share the same name of another
package, which means if the queried package has a reference to a virtual
package in one of the before mentioned package relationship fields, then
whatever packages provide the virtual package are also being listed. 
 
B<--md5sum> checks B<MD5 checksums>.  It can be used with B<-l>, B<-d>,
B<-c>, or B<-p>. If there are checksums available the md5sum result will
be either B<OK>, B<FAILED>, or B<MISSING>.  B<MISSING> means that although
a checksum exists, the file can not be found.  The result is put after the
file and its path and the B<MD5 checksum> or the package name and version
and the B<MD5 checksum>. 

=head2 FORMAT

B<1). Installed system>

 Package: name                        Status: hold ok installed
 Version: 1.1-1                       Essential: no
 Section: namers                      Priority: extra
 Installed-Size: 10                   Source: generatename (2.0-1)
 Maintainer: name <name@name.org>
 Description: hostname maker
  A nice way to figure out a hostname nobody
  else has.

B<2) Not-installed system>

 Package: name                        Status: r> hold ok installed (1.1-1)
 Version: 1.1-2                       Essential: no
 Section: names                       Priority: extra
 Installed-Size: 11                   Source: generatename (2.0-1)
 Size: 43000                          Architecture: i386
 Distribution: experimental
 Maintainer: name <name@name.org>
 Description: hostname maker
  A nice way to figure out a hostname nobody
  else has.

There are several things to point out. The difference between the two
outputs relates to the addition of the Distribution, Size, and
Architecture fields for the not-installed query.  Installed-Size is how
many kilobytes the package will occupy when it is unpacked, whereas Size
is the size in bytes of the package.  


=head2 STATUS FIELD 

The Status field provides the installation status of the package, this
holds true for the not-installed query as well.  In a sense, the
not-installed database isn't always not-installed.  If the not-installed
package is actually already installed, and the version numbers are exactly
the same, then the status will be the same for either query.  If the
not-installed package is not installed then the status will be
"not-installed".  In cases where the not-installed package is already
installed, swim uses it's comparison function to figure out whether it is
a newer of older package which is installed.  In the above example, swim
realizes the same package is installed, and only the debian-revision has
changed, hence the only difference is that the revision number is greater
"r>" for the not-installed package.  When only the debian-revision has
changed it can safely be assumed that the author (creator, programmer) of
the same program has not made any changes to the same program, but the
Debian maintainer has made a change to an aspect of the package like a
change in the script the package uses to properly install.  You may have
also noticed that the status field shows the version number of the
installed package enclosed in parenthesis.

=head2 SOURCE FIELD

The Source field is present in these examples, but the Source field will
not always be present for packages.  In cases where the name of the source
package is the same as the the name found in the Package field, and the
version number of the source package is also the same as found in the
Version field, then there will be no Source field.  In the above examples
there is a Source field.  In this case name was probably one of many
packages generated from the source package called generatename.  In this
particular example generatename also has its own unique version number
2.0-1 enclosed in parentheses, if no version number had been mentioned
then the source package would have the same version number as found in the
Version field. 

=head2 SECTION AND PRIORITY 

Section shows the subject which a package is categorized with (see C<-g>). 
Priority shows how important the package is to have installed.  In the
case of the not-installed databases the information for these fields is
almost always available from the Packages databases, but this is not
always the case for Debian packages.  For packages which do no provide
this information swim will do its best to fill in the blanks from
information found in the installed and not-installed databases.  If proper
information can not be found it will be indicated as "unavailable" or
"unknown." Unavailable would indicate that information about the package
exists, but it is from a different version (includes debian-revision), and
no information exists for this version.  Unknown means no similiar package
exists, and there is absolutely no information about this package in the
databases. 

=head2 DEBIAN PACKAGE OUTPUT

When a Debian package is queried using the B<-p> option you will get
output like the first example shows, the status field is also calculated. 

=head2 VIRTUAL OPTIONS

=head2 FTP 

For ftp capabilities swim uses the F<swimz.list> to determine which sites
it will check for the requested packages.  The first site which fills the
request will be used, otherwise B<swim> will go through all the sites
avoiding repeats, and if no sites can fill the request, B<swim> will
either quit or proceed on to check for another request. 

B<--ftp> allows the queried package, its source package, or just the
source package diff to be downloaded while being queried.  This is refered
to as virtual downloading because the quering and the downloading are
seamless as though the package already exists locally.  This has to be
used with the option B<-n> because packages which which are not part of
the not-installed database are considered to already have been downloaded. 
Packages which are already installed can be downloaded or their source
retrieved by setting up a database which corresponds to these packages; if
the installed packages belong to the stable distribution, set-up the
not-installed stable databases. 

Packages or source code are placed in an area below the default directory
mirroring the remote directory they were downloaded from after their size
and modification times are checked for correct values.  This area is
called the B<DF> directory, and although this directory mirrors remote
directories, it is not an exact mirror, but specific to the requirements
of swim because code names for Release versions are not taken into
account.  For real mirroring capabilities there exist many excellent
programs.  If a package has a B<MD5 checksum>, B<--md5sum> will
automatically be run and the value shown.  Regardless of whether or not
the md5sum check is B<OK> or not, the package will still be put in the
B<DF> directory to allow the package to be looked at, so watch the output
from B<--ftp> to check for B<FAILED md5sums>. 

Packages or source code packages will not be downloaded again if they are
found in the B<DF> directory unless their I<upstream-version> has changed
in the not-installed database, if the packages are not in the DF directory
and the remote I<upstream-version> is different than the not-installed
I<upstream-version> then the packages will not be downloaded until the
not-installed database is updated or rebuilt to reflect the version
change. Changes in the package's I<upstream-version> indicates that the
author(s) of the program have made changes to the computer code for the
program contained in the package or the source code package.  On the other
hand, swim will check for a I<debian-revision> change at the remote site
if the package can not immediately be found.  If the package's
I<debian-revision> has changed and the package does not exist locally in
the B<DF> directory, it will be downloaded.  This is a nice feature,
especially for the unstable distribution, because it tends to extend the
time needed before the not-installed database has to be updated or rebuilt
to match the changes at remote sites. 

B<--source> is used with B<--ftp> to download the source code package. 
B<--source_only> will download the source code package without the deb
package.  I<Source packages consist of three files>.  The I<source control
file> which ends in "dsc", the I<original source archive> which is a
compressed tar file, and the I<unified context diff> showing the changes
necessary to make the original source into Debian source.  The diff can be
downloaded by itself if B<--diff> is provided as an argument to B<--source
or --source_only>. 

For B<apt> users: B<apt> allows packages to be downloaded, but if more
than one package is required for the package relationships to be proper,
B<apt> will download all these packages.  B<--ftp> allows specific
packages to be downloaded, packages from other architectures, and source
packages to be downloaded, here lies the advantage of this option over
using B<-xyz --nz> (see below).  If a particular package has been
dowloaded into the B<DF> directory and it is needed by B<apt> for
installation, simply copy or move the package from the B<DF> directory to
F</var/cache/apt/archives> before running B<apt>, and the package will not
be downloaded by B<apt> again; future versions of B<swim> will have an
option to automatically accomplish this (see C<--df2apt>). 

=head2 APT

apt-get(8) is a nice package relationship checker from the B<apt> package
which figures out what needs to be done to properly install a package or
packages when one or more package names are provided to it.  B<apt-get>
will get all packages which are needed using a variety of methods, and
then B<apt-get> interacts with B<dpkg> in a way which allows for a
successful installation. 

B<-xyrz, --remove and --nz> can be used if B<apt-get> from the B<apt>
package is installed.  These options allow for what is refered to as
virtual installation/removal.  It is prudent to always test what will
happen by using the B<-x> option alone before actually proceeding with the
installation with the B<-z> option.  B<-x> will actually simulate what
would happen in an installation, showing which and how many packages will
be changed, which and how many new packages will need to be installed,
which and how many packages will need to be removed, any conflicts, and
what needs to be configured.  B<-y> will automatically answer yes to any
prompts B<apt-get> may produce allowing B<apt-get> to run
non-interactively.  B<-z> as mentioned before actually proceeds with the
installation using B<dpkg> after the B<apt-get> gets the packages.  You
can append a minus sign to a package name to cause it to be removed.
B<--nz> when used as an optional argument with B<-xz or -xyz> will only
download the packages into F</var/cache/apt/archives> or into whatever
directory you configured for holding archives for B<apt>. 

B<IMPORTANT>:  B<apt> makes it so easy to make changes to your
installation that it is highly recommended to do your research with swim
first.  This can be done by checking package relationships, file/dir
listings, comparing the not-installed package to an installed package if
such exists, checking B<--md5sum> and B<-c> for the installed package, and
checking the Source field by running a B<--search> (see below) to check to
see how the source package has been split into binary packages for the
not-installed package versus an installed package if such exists. 
Ofcourse, there are many other things you could look at, and you can
always do your research after the fact.  Presently B<--db> is run only by
hand, so you can check the old state after an installation if you have not
already run B<--db>, yourself.

=head2 REMOVING AN INSTALLED PACKAGE 

B<--purge> uses B<dpkg> to remove an installed package or packages and the
configuration files as shown with "B<swim -qc packagename>". 

B<-r or --remove> removes an installed package or packages with B<apt>,
but not the configuration files as shown with "B<swim -qc packagename>". 
You may also append a plus sign to a package name to cause it to be
installed.  This option is used with -x or -x(y)z. 

=head2 STDIN 

B<--stdin> works with either B<--ftp>, B<-x>, B<-xyz>, B<-xz>, B<--purge>,
B<-r>, or B<--remove>. 

B<--stdin> provides the I<readline capabilities> commonly found in shells
allowing you to edit what is on the command line. You can edit the command
line, press enter and then recall the history, and make more changes, or
I<type in exit to process the changed or unchanged command line>. To find
out more about what readline commands your shell supports please read the
man pages which apply to your shell.  Information for the bash shell can
be found in bash(1) under the title "B<Readline Command Names>".

Example: "B<swim -qgnx --stdin hamradio>" will list all the packages from
the not-installed hamradio group on the command line, this list can be
edited then submitted to B<apt-get> for a simulated installation.  Another
instance of B<swim> can be run at the same time, perhaps "B<swim -qinTg
hamradio>" to help in making editing decisions for B<--stdin>. 

=head2 PACKAGE MANIPULATION

B<--extract> only works with the B<minor mode -p> to extract parts or all
of a Debian package.  If the B<argument ALL> is provided then I<everything
found in the package will be extracted> below the current directory in the
exact directories found in the package.  A particular I<file may be
extracted in its exact location> below the current directory by I<entering
the exact path for the file> as shown by "B<swim -qpl>" or "B<swim -qpd>"
as the argument.  Alternativily, a I<file may be extracted in the current
directory> regardless of its proper location by I<prepending PWD\! before
the path> shown by "B<swim -qpl>" or "B<swim -qpd>".  Notice the backslash
before the exclamation point, this is because shells consider ! a special
character, so it has to be backslashed so that the shell knows that it is
not such a special character.  Example: "B<swim -qpi --extract
PWD\!usr/bin/name --scripts name_1.1-2.deb>" will extract the binary name
in the current directory from the name package, show information for the
name package, and show any scripts for the name package.

=head2 DATABASE LOCATIONS

B<--dbpath> can be specified as an alternative location for where the
databases would be found.  The default location is "F</var/lib/dpkg>".  An
argument like "F</otherstuff>" can be provided, and then the databases
would be found here instead.

B<--root> allows a database to be found for a Debian distribution
installed on a different partition.  If the distribution is mounted on
F</New_Debian>, "F</New_Debian>" would be the argument to root.  The
databases would be found for the Debian distribution installed on the
"F</New_Debian>" partition.

B<--dbpath and --root> can be used together.  Given the previous two
examples, the databases would be found on "F</New_Debian/otherstuff>",
assuming "F</New_Debian/otherstuff>" actually existed.



=head1 UPGRADING WITH APT

usage: B<swim --apt>

options: B<[-xyz] [--upgrade] [--dist_upgrade]>

B<apt-get> provides powerful methods to change an installion. When these
methods are called using B<--apt>, B<swim> will not allow you to proceed
until you are absolutely sure this is what you want to do.  Before using
these methods do a "B<swim --apt --update>" so that B<apt-get> knows the
newest versions of available packages.  This major mode requires a
combination of B<-x>, B<-xz> or B<-xyz> to be used along with either
B<--upgrade> or B<--dist_upgrade>.  B<-x> used alone will simulate what
would happen if B<-xz or -xyz> were used (also see C<-xyz> above). 

B<--upgrade> is somewhat similiar to doing "B<swim -qatxz>" except that it
is a more intelligent method because B<apt> does some behind the scene
calculations in regards to package relationships, in fact the "B<swim
-qatxz>" approach will provide totally different results, or maybe these
were the results you really wanted. "B<swim --apt --upgrade -xz>" is the
prefered, proper, and built-in way provided by B<apt-get> to install the
newest versions for all packages installed on your system.  This method
will not install any newer versions of packages which would change the
install status of other packages.  Note: It is not recommended to combine
the query option B<-a> with B<-xz or -xyz>, but combining the query option
B<-a> just with B<-x> can be educational. 

B<--dist_upgrade> combines an B<--upgrade> with the installation of
packages which are not installed.  This method carefully examines
dependencies, and resolves conflicts, and given these factors it will
upgrade the most important packages before considering the installation of
less important packages.  Less important packages will be installed only
if there are not any conflicts. 

=head1 SEARCHING

usage: B<swim --search ? (--research || --refinesearch)> 
       B<swim --powersearch ? (--research || --refinesearch)> 
       B<swim --ps ? (--research || --refinesearch)> 
       <B<pattern(s)>>
        
options: B<[-g] [-n] [--dbpath> <B<dir>>B<] [--root> <B<dir>>B<]>
         B<[--arch> <B<architecture>>B<] [--dists> <B<distribution>>B<]>
         B<[--ftp ? --source | --source_only --diff]> 
         B<[-xyrz --remove ?> <B<[--nz]>>B<] [--stdin] [--apt2df]> 
         B<[--no] [--df2apt] [--purge] [>B<\d{1,}>B<]> 
 
         B<[--dir]> and no B<[-g]> for B<--powersearch or --ps>


=head2 OVERVIEW

B<swim> provides two major types of searches.  A search with B<--search>
I<searches package information>, and a search with B<--powersearch or
--ps> I<searches package information, and all files and/or directories
associated with each package>.  

The results of either of these searches can be I<narrowed down> by running
a test search with B<--research> (this step can be skipped) and/or setting
the results in stone with B<--refinesearch>.  B<--search> can be
I<narrowed down> initially by specifying a particular I<group>, and
B<--powersearch> can be I<expanded> initially by specifying that
I<directories> be searched as well as files. Both searches can I<use the
same virtual options> which the major mode B<-q or --query> use.
Generally, it is preferable to run a search, and then to provide the
results of a search (B<using -S>) as an argument to B<-q or --query>; this
allows the results of a search to be queried.  Every time a search is run
the results are appended to the history, past searches can be refined or
researched by providing the numerical argument pertaining to the history.
\d{1,} is simply Perl notation meaning a number with one of more digits. 

I<Perl regexps> (see perlre(1p)) can be used to define the pattern
(string) provided as an argument to a search.  Do not surround a pattern
in slashes, a slash is only used after all patterns and before the
I<modifiers i and/or m> (swim supports these two modifiers).  To search
for more than one pattern, patterns are separated with I<bars (|)>. 
Patterns may include I<quatifiers, and metacharacters>, also found in
egrep(1). 

If a search finds any packages which match the search, the package
information will be displayed as the package is found.  The package will
only be shown once regardless of how many times it is found while the
search progresses. When the search is over the number of packages found is
shown. 

B<--search> provides a search of package information.  This is similiar to
grepping "B<swim -qait>" or "B<swim -qaint>", but it is significantly
faster. A search can be performed on a particular group by using B<-g>
with a group as an argument

B<--powersearch> is somewhat similiar to "B<dpkg --search>" which searches
all files and directories on an installed system, but it combines
B<--search> with the file and/or directory search, and can also be
performed on a not-installed system. A I<powersearch> is significantly
faster than the search which B<dpkg> provides (even more so when "C<swim
--ramdiskon --searchfile>" is used)  and even more importantly provides a
logical output of the search (like "C<swim -qi packagename>").  By default
a search of all directories is not performed because usually this is
redundant except in rare cases.  To enable a search of all directories use
the B<--dir> option.

=head2 NARROWING A PREVIOUS SEARCH

B<--research> allows the results of a previous search to be researched
without making the new results permanent. 

B<--refinesearch> allows the results of a previous search to be researched
while making the new results permanent.

B<\d{1,}> is a numerical argument to refine or research a   
past search from the history.

=head2 MINOR MODES

B<-n> allows the not-installed databases to be searched.  These databases
will not exist if the not-installed databases were made with the FDB
argument (see C<--initndb>).

B<-g> (see C<--search>)

=head2 OTHER OPTIONS

B<--no> prevents normal output from a search, but does show how many
packages were found.

See the section "B<SPECIFYING THE DATABASES TO USE>" for options
B<--arch>, B<-dists>.

See the section "B<VIRTUAL OPTIONS>" for options B<--ftp>,
B<--source>, B<--source_only>, B<--diff>, B<-xyz>, B<--nz>, B<--stdin>,
B<--purge>, B<--remove>, B<-r>. 

See the section "B<DATABASE LOCATIONS>" for options B<--dbpath>
and B<--root>.

=head2 EXAMPLES

B<swim -gn hamradio --search "radio network/i" --dbpath /test --arch alpha>

will search the alpha architecture not-installed system databases in the
/test directory for all package information from the hamradio group using
the case insensitive pattern "radio network".

B<swim --powersearch dpkg -xn>

will search the not-installed system databases for all package information
and all files using the case sensitive pattern dpkg, after which apt-get
will run a simulation of what would happen if it got and installed these
packages.


=head1 RAMDISK

usage: B<swim --ramdiskon>
       B<swim --ramdiskoff>

options: B<[-n] [--searchfile] [--arch> <B<architecture>>B<]> 
         B<[--dists> <B<distribution>>B<] [--dbpath] [--root]>
 
         no options for B<--ramdiskoff>


=head2 OVERVIEW

A ramdisk can be mounted below the default path or the specified path for
the databases in the dramdisk directory.  The ramdisk is used to speed up
powersearchs and/or file/dir listings for packages from the not-installed
system.  Also, this is useful if a computer system is heavily loaded with
other processes using the memory, and the ramdisk tends to persist even
after being unmounted. Modern kernels usually are built with support for
ramdisks. If these options do not work the kernel will need to be compiled
to support ramdisks by answering yes to RAM disk support.  Perhaps the
best F<README> showing how to configure and compile a kernel comes with
the F<kernel sources> in the main directory.

B<--ramdiskon> allows a ramdisk to be created and mounted.  If called with
B<-n> (not-installed databases) F<ncontents-arch-dists.deb.gz> will
automatically be written to the mounted ramdisk.  This provides faster
file/dir listing capabilities when using B<-l>, B<--df>, or B<-d> when
querying the not-installed system.  Faster powersearch capabilities are
available through the option B<--searchfile>.  If the search databases are
not already compressed, they will now be compressed, this usually only
needs to be done once or until the databases are updated or rebuilt again. 
The search databases will then be written to the mounted ramdisk.  An
installed system only writes the search databases to the mounted ramdisk,
so always use --searchfile when specifying installed system databases.

B<--ramdiskoff> is used to unmount the ramdisk.  The not-installed
databases and the installed databases can not be simultaneously provided
by a mounted ramdisk, use B<--ramdiskoff> first, then B<--ramdiskon> to
install the other databases of choice.  This also pertains to different
distributions and/or architectures.

See the section "B<SPECIFYING THE DATABASES TO USE>" for options
B<--arch>, B<-dists>.

See the section "B<DATABASE LOCATIONS>" for options B<--dbpath>
and B<--root>.

=head1 FILES

 Configuration files: 

 swimz.list
 swimrc

=head1 SEE ALSO

swimrc(5), apt-get(8), sources.list(5), dpkg(8)

=head1 BUGS

Send directly to mttrader@access.mountain.net

=head1 AUTHOR

Jonathan D. Rosenbaum <mttrader@access.mountain.net>

=head1 COPYRIGHT

Copyright (c) 1999 Jonathan Rosenbaum. All rights reserved. This program
is free software; you can redistribute it and/or modify it under the GPL. 

=cut