dswim/swim-doc/swimrc.text

                     swimrc - swim configuration file
                     --------------------------------
            Jonathan D. Rosenbaum<mttrader@access.mountain.net>
                                27 May 1999

0.1 Contents
------------

     1.        DESCRIPTION 

     2.        USAGE 

     3.        VARIABLES 
     3.1.      OUTPUT VARIABLE 
     3.2.      HISTORY 
     3.3.      AR or DPKG? 
     3.4.      APT 
     3.5.      PAGER 
     3.6.      NOT-INSTALLED VARIABLES 
     3.7.      DF LOCATION 
     3.8.      TEMPORARY DIRECTORY 
     3.9.      FTP 

     4.        OTHER VARIABLES 

     5.        FILES 

     6.        BUGS

0.2 Copyright Notice
--------------------

     Copyright � 1999 Jonathan D. Rosenbaum 

     SWIM, including this manual, is free software; you may redistribute it
     and/or modify it under the terms of the GNU General Public License as
     published by the Free Software Foundation; either version 2, or (at
     your option) any later version. 

     This is distributed in the hope that it will be useful, but *without
     any warranty*; without even the implied warranty of merchantability or
     fitness for a particular purpose. See the GNU General Public License
     for more details. 

     You should have received a copy of the GNU General Public License with
     the swim source as the file `COPYING'. If not, write to the Free
     Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 


-------------------------------------------------------------------------------


1. DESCRIPTION 
---------------

     swimrc is the configuartion file for swim allowing many default values
     to be set so that they do not have to be mentioned on the command
     line. Swimrc interacts directly with Perl allowing a wide variety of
     variables found in SWIW::Conf to be altered. 


-------------------------------------------------------------------------------


2. USAGE 
---------

     Values for variable can be altered for *swim* by assigning different
     values enclosed in quotes or quoted whitespace (qw()), and ending with
     a semi-colon. 

     ` $variable = ``value'';'

     `$variable = ``(value1 value2 ..)'';' 



-------------------------------------------------------------------------------


3. VARIABLES 
-------------

     This is a list of variables with explanations. The default values for
     *swim* are shown. 


3.1. OUTPUT VARIABLE 
---------------------

     `$my_number' can be changed to how many lines you would like ``swim
     -qf <>'' to print out, before the program asks for `-t' or `--total'.
     Exception: If `-i' is used in the query and there is more than one
     package then the total will be presented. 

     Hint: `-t' can be used with all the various `--scripts' family members
     to view the title of the script file regardless of this variable
     setting, and if `-t' has to be used, the titles will be displayed,
     which makes sense. 

     *$my_number = 23;* 


3.2. HISTORY 
-------------

     This is a shell-like history kept in relation to searches and the most
     recent edit when `--stdin' is used. 

     *$HISTORY = 10;* 


3.3. AR or DPKG? 
-----------------

     Debian packages are ar archives. If you are using a Debian
     Distribution assign ``dpkg'' to $package_tool, otherwise assign ``ar''
     to $package_tool. 

     *$package_tool = "/usr/bin/ar";* 


3.4. APT 
---------

     *Swim* does not assign a value for apt. To use `--apt' and `-xyz'
     assign `$apt' the value ``yes''. 

     Example: *$apt = "yes";* 


3.5. PAGER 
-----------

     *less* is a nice pager, unless you like *more*! Pager is used for
     `--help' and *swim* called without any options. There is an option
     `--nopager' or `-n'. *more* comes from the required package
     util-linux, whereas *less* comes from a standard package called less.
     Values: ``less'', ``more'', or ``most'' or... 

     *$ENV{PAGER} = "less";* 


3.6. NOT-INSTALLED VARIABLES 
-----------------------------

     Assign values for `$architecture' and/or `$distribution' to avoid
     having to use `--arch' and `--dists' everytime the not-installed
     databases are accessed with `-n' or made or altered. 

     Architectures are always being added so check with Debian to find a
     list. There is *alpha, arm, hurd-i386 (alternative kernel to linux),
     i386, m68k, powerpc, sparc*. Just use the arch found after the hyphen
     in the Contents-(arch) file. 

     *$architecture = "i386";* 

     The distribution can be either *stable, unstable, frozen, or
     experimental (rare)*. These represent the state of development that
     the packages are under. The unstable distribution can have lot's of
     changes within a very short time period, and frozen may or may not be
     available. 

     *$distribution = "unstable";* 

     Distributions are divided into sections. These sections were called
     distributions in the version 2.4.1.0 packaging manual, because they
     were at one time separate distributions, but this has since changed. 

     You can determine which of the sections *main, non-free, contrib or
     non-US* to pull out of the Contents file if you don't want to use
     `--main', `--contrib', `--non-free', and `--non-us' to selectively
     pick the sections. 

     For efficiency, you should choose the sections which you will be
     pulling out of the Packages `file(s)' being targetted. 

     Rule: Use ``non-US'' not ``non-us''. 

     *@user_defined_section = qw(main contrib non-free non-US);* 


3.7. DF LOCATION 
-----------------

     A little philosophy: *swim* was developed for maximum versatility, so
     whether you are just interested in researching, and keeping tabs on
     the newest packages, or maintaining a Debian virtual distribution on a
     non-Debian distribution, or you are a using *swim* for distribution
     development, *swim* provides a way. 

     The next two variables determine the location of the DF (default
     directory/file system) 

     The default directory keeps track of Contents and/or Packages
     databases retrieved with --ftp. The Contents and Packages databases
     and Release file are give names specific to the distribution and
     architectures they represent using the naming convention found in
     apt's sources directory. You also have the freedom not to use the
     default directory, in which case swim will still do the renaming and
     keeping track of the mtime, but you will have to remember where you
     put the files. 

     *$default_directory = '/root/.swim';* 

     The default root directory (DRD) is the key to easy management of
     binary packages, source, dsc, and diff files received from --ftp, and
     provides an easy way to put together a personalized distribution. This
     directory can be a real ftp site on your computer, or put wherever
     else you are allowed to have directories. The DRD is always placed
     below the value assigned to $default_directory. According to the
     previous assignment to $default_directory, if the DRD is
     ``/pub/a/debian'' then the full path would be
     ``/root/.swim/pub/a/debian''. 

     Example: When a package is downloaded it will be placed in
     dists/distribution/section/architecture/subject below the DRD. 

     Rule: debian must be the final directory before dists, this is because
     other distributions are placed alongside debian, like debian-non-US or
     personal (specialized distribution). 

     *$default_root_directory = '/pub/debian';* 

     Because you may be using a real ftp site, this variable allows you to
     determine what permissions *swim* will assign for directories it
     creates below the DRD. 

     *$permission = '0755';* 


3.8. TEMPORARY DIRECTORY 
-------------------------

     If you want to set an alternative directory for the temporary files
     created when the databases are made, change here. You may want to make
     `$tmp' a RAM disk. See package loadlin for initrd documentation and an
     explanation for making such a disk. There is also documentation in
     /usr/src/kernel-source.version/Documentation. Whether this will speed
     things up is a subject of experimentation. 

     *$tmp = "/tmp";* 


3.9. FTP 
---------

     You can alter the Firewall, Port, Timeout, Debug and Passive
     characteristics of the ftp client as defined in Net::FTP(3pm) by
     providing arguments to these variables. All variables but $timeout are
     set to untrue by default. 
           $firewall = 0; (FTP firewall machine name)
           $port = 0;  (defaults to 23)
           $timeout = 120;  (120 seconds)
           $debug = 0;  (1 will turn on STDERR)
           $passive = 0; (1 will enable)


-------------------------------------------------------------------------------


4. OTHER VARIABLES 
-------------------

     see SWIM::Conf 


-------------------------------------------------------------------------------


5. FILES 
---------

     ` /etc/swim/swimrc'

     `~/.swim/swimrc' 


-------------------------------------------------------------------------------


6. BUGS
-------

     Send directly to mttrader@access.mountain.net. 


-------------------------------------------------------------------------------


     swimrc - swim configuration file
     Jonathan D. Rosenbaum<mttrader@access.mountain.net>        27 May 1999