`dselect' Documentation for Beginners
                   -------------------------------------

       Stéphane Bortzmeyer and others <debian-doc@lists.debian.org>


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


Abstract
--------

     This document contains is a short tutorial for first-time users of
     `dselect', console Debian package handling frontend.  It supplements
     the Installation Manual for Debian GNU/Linux 3.0
     (http://www.debian.org/releases/woody/powerpc/install).


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


Contents
--------

     1.        Introduction

     2.        Once `dselect' is Launched
     2.1.      ``Access''
     2.2.      ``Update''
     2.3.      ``Select''
     2.4.      ``Install''
     2.5.      ``Configure''
     2.6.      ``Remove''
     2.7.      ``Quit''

     3.        A Few Hints in Conclusion

     4.        Glossary


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


1. Introduction
---------------

     Please note that newer versions of this file can always be found at
     http://www.debian.org/releases/woody/powerpc/dselect-beginner.

     This file documents `dselect' for first-time users, and is intended to
     help in getting Debian installed successfully.  It makes no attempt to
     explain everything, so when you first encounter `dselect', read
     through the help screens.

     If you are eager to get Debian running as soon as possible, well, you
     shouldn't use `dselect' :-) Debian installation procedure allows you
     to run `tasksel' which provides some generalized tasks that you can
     select and be done with it.

     `dselect' is used to select which packages you wish to install (there
     are currently around 8000 packages in Debian 3.0).  It will be run for
     you during the install and as it is a very powerful and somewhat
     complex thing which can be used for good or for evil; some knowledge
     of it beforehand is highly recommended.  Careless use of `dselect' can
     severely mess up your system.

     `dselect' will guide you through the package installation process as
     follows:

        * Choose the access method to use.

        * Update list of available packages, if possible.

        * Request which packages you want on your system.

        * Install and upgrade wanted packages.

        * Configure any packages that are unconfigured.

        * Remove unwanted software.

     As each step is completed successfully it will lead you on to the
     next.  Go through them in order without skipping any steps.

     Here and there in this document we talk of starting another shell.
     Linux has 6 console sessions or shells available at any one time.  You
     switch betwen them by hitting _Left Alt-F1_ through _Left Alt-F6_,
     after which you log in on your new shell and go ahead.  The console
     used by the install process is the first one, a.k.a., tty1, so hit
     _Left Alt-F1_ when you want to return to that process.


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


2. Once `dselect' is Launched
-----------------------------

     Once in `dselect' you will get this screen:

          Debian `dselect' package handling frontend.
          
             0. [A]ccess    Choose the access method to use.
             1. [U]pdate    Update list of available packages, if possible.
             2. [S]elect    Request which packages you want on your system.
             3. [I]nstall   Install and upgrade wanted packages.
             4. [C]onfig    Configure any packages that are unconfigured.
             5. [R]emove    Remove unwanted software.
             6. [Q]uit      Quit dselect.
          
          [some other stuff]

     Let's look at these one by one.


2.1. ``Access''
---------------

     Here's the access screen:

dselect - list of access methods
  Abbrev.        Description
  cdrom          Install from a CD-ROM.
* multi_cd       Install from a CD-ROM set.
  nfs            Install from an NFS server (not yet mounted).
  multi_nfs      Install from an NFS server (using the CD-ROM set) (not yet mounted).
  harddisk       Install from a hard disk partition (not yet mounted).
  mounted        Install from a filesystem which is already mounted.
  multi_mount    Install from a mounted partition with changing contents.
  floppy         Install from a pile of floppy disks.
  apt            APT Acquisition [file,http,ftp]

     Here we tell `dselect' where our packages are.  Please ignore the
     order that these appear in.  It is very important that you select the
     proper method for installation.  You may have a few more methods
     listed, or a few less, or see them listed in a different order; just
     don't worry about it.  In the following list, we describe the
     different methods.

     apt
          One of the best options for installation from a local mirror of
          the Debian archive, or from the network.  This method uses the
          ``apt'' (see apt(8)) system to do complete dependency analysis
          and ordering, so it's most likely to install packages in the
          optimal order.

          Configuration of this method is straight-forward; you may select
          any number of different locations, mixing and matching `file:'
          URLs (local disks or NFS mounted disks), `http:' URLs, or `ftp:'
          URLs.  You can also include CD-ROM/DVD media with `apt-cdrom'.

          Please see the sources.list(5) manual page for more information
          on the format of the `/etc/apt/sources.list' file.

          If you have proxy server for either HTTP or FTP (or both), make
          sure you set the `http_proxy' or `ftp_proxy' environment
          variables, respectively.  Set them from your shell before
          starting dselect, e.g.:

               # export http_proxy=http://gateway:3128/
               # dselect

     multi_cd
          Quite large and powerful, this complex method is the recommended
          way of installing a recent version of Debian from a set of
          multiple binary CDs.  Each of these CDs should contain
          information about the packages in itself and all prior CDs (in
          the file `Packages.cd').  When you first select this method, be
          sure the CD-ROM you will be using is not mounted.  Place the last
          _binary_ disk of the set (we don't need the source CDs) in the
          drive and answer the questions you are asked:

             * CD-ROM drive location

             * Confirmation that you are using a multi-cd set

             * The location of the Debian distribution on the disk(s)

             * [ Possibly ] the location(s) of the Packages file(s)

          Once you have updated the available list and selected the
          packages to be installed, the multi-cd method diverges from
          normal procedure.  You will need to run an ``install'' step for
          each of the CDs you have in turn.  Unfortunately due to the
          limitations of dselect it will not be able to prompt you for a
          new disk at each stage; the way to work for each disk is

             * Insert the CD in your CD-ROM drive.

             * From the main dselect menu, select ``Install''.

             * Wait until dpkg finishes installing from this CD (it may
               report installation successful, or possibly installation
               errors.  Don't worry about these until later).

             * Hit [_Enter_] to go back to the main dselect menu.

             * Repeat with the next CD in the set...

          It may be neccesary to run the installation step more than once
          to cover the order of package installation - some packages
          installed early may need to have later packages installed before
          they will configure properly.

          Running a ``Configure'' step is recommended, to help fix any
          packages that may end up in this state.

     multi_nfs, multi_mount
          These are very similar to the multi_cd method above, and are
          refinements on the theme of coping with changing media, for
          example if installing off a multi-cd set exported via NFS from
          another machine's CD-ROM drive.

     floppy
          Caters for those people without CD-ROM or network access.  Not
          recommended as a viable installation option anymore if you are
          using traditionally-sized floppies, but may work better for
          LS/120 or Zip drives.  Specify the location of your floppy drive,
          then feed floppies.  The first one should contain the Packages
          file.  This method is slow and may be unreliable due to media
          problems.

     nfs
          _DEPRECATED METHOD -- use apt or multi_nfs instead.  Only try
          this method if all else fails._

          This is a simple installation method, with simple requirements:
          give it the address of the NFS server, the location of the Debian
          distribution on the server and (maybe) the Packages file(s).
          Then `dselect' will install the various sections in turn from the
          server.  Slow but easy; does not use proper ordering, so it will
          take many runs of the ``Install'' and/or ``Configure'' steps.
          Obviously only appropriate for NFS based installation.

     harddisk
          _DEPRECATED METHOD -- use apt or multi_mount instead.  Only try
          this method if all else fails!_

          Supply the block device of the hard drive partition to use, and
          the locations of the Debian files on that partition, as usual.
          Slow and easy.  Does not use proper ordering, so it will take
          many runs of the ``Install'' and/or ``Configure'' steps.  Not
          recommended, since the ``apt'' method supports this
          functionality, with proper ordering.

     mounted
          _DEPRECATED METHOD -- use apt or multi_mount instead.  Only try
          this method if all else fails!_

          Simply specify the location(s) of the Debian files in your
          filesystem.  Possibly the easiest method, but slow.  Does not use
          proper ordering, so it will take many runs of the ``Install''
          and/or ``Configure'' steps.

     cdrom
          _DEPRECATED METHOD -- use multi_cd instead.  This method simply
          does not work with multiple CD sets, such as are included in
          Debian 3.0._

          Designed for single-CD installations, this simple method will ask
          for the location of your CD-ROM drive, the location of the Debian
          distribution on that disk and then (if necessary) the location(s)
          of the Packages file(s) on the disk.  Simple but quite slow.
          Does not use proper ordering, so it will take many runs of the
          ``Install'' and/or ``Configure'' steps.  Not recommended, because
          it assumes the distribution is on a single CD-ROM, which is no
          longer the case.  Use the ``multi_cd'' method instead.

     If you run into any problems -- maybe Linux can not see your CD-ROM,
     your NFS mount is not working or you have forgotten which partition
     the packages are on -- you have a couple of options:

        * Start another shell.  Fix the problem and then return to the main
          shell.

        * Quit `dselect' and run it again later.  You might even need to
          shut down the computer to solve some problem.  This is quite ok
          but when you come back to `dselect' run it as root.  It will not
          be run automatically after the first time.

     After you choose the access method `dselect' will get you to indicate
     the precise location of the packages.  If you do not get this right
     the first time hit _Control-C_ and return to the ``Access'' item.

     Once you are finished here, you will be returned to the main screen.


2.2. ``Update''
---------------

     `dselect' will read the `Packages' or `Packages.gz' files from the
     mirror and create a database on your system of all available packages.
     This may take a while as it downloads and processes the files.


2.3. ``Select''
---------------

     Hang on to your hat.  This is where it all happens.  The purpose of
     this step is to select just which packages you wish to have installed.

     Hit _Enter_.  If you have a slow machine be aware that the screen will
     clear and can remain blank for some 15 seconds, so don't start bashing
     keys at this point, just be patient.

     The first thing that comes up on the screen is page 1 of the Help
     file.  You can get to this help by hitting _?_ at any time in the
     ``Select'' screens and you can page through the help screens by
     hitting the _._ (full stop) key.

     Please be prepared to take an hour or so as you have to learn your way
     around and then get it right.  When you enter the ``Select'' screen
     for the first time, don't make _ANY_ selections at all -- just hit
     _Enter_ and see what dependency problems there are.  Try fixing them.
     If you find yourself back at the main screen, enter Section 2.3,
     ```Select''' again.

     Before you dive in, note these points:

        * To exit the ``Select'' screen after all selections are complete,
          hit _Enter_.  This will return you to the main screen if there is
          no problem with your selection.  Otherwise, you will be asked to
          deal with that problem.  When you are happy with any given
          screen, hit _Enter_ to get out.

        * Problems are quite normal and are to be expected.  If you select
          package <A> and that package requires package <B> to run, then
          `dselect' will warn you of the problem and will most likely
          suggest a solution.  If package <A> conflicts with package <B>
          (i.e., if they are mutually exclusive) you will be asked to
          decide between them.

     Let's look at the top two lines of the ``Select'' screen.

dselect - main package listing (avail., priority)    mark:+/=/- verbose:v help:?
EIOM Pri Section  Package      Inst.ver    Avail.ver   Description

     This header reminds us of some of the special keys:

     `+'
          Select a package for installation.

     `='
          Place a package on hold -- useful on a broken package.  You can
          reinstall an older version and place it on hold while you wait
          for a new one to appear.  (These things rarely happen with stable
          Debian, though.)

     `-' Remove a package.
     `_'
          Purge a package: remove both the package and its configuration
          files.

     `i,I'
          Toggle/cycle display of additional information (in the bottom
          part of the screen).

     `o,O'
          Cycle through the sort options (in the top part of the screen).

     `v,V'
          A terse/verbose toggle.  When you press this, you will find out
          what do the letters EIOM on the second line mean.  But here's a
          summary:

               Flag   Meaning           Possible values
               E      Error             Space, R, I
               I      Installed state   Space, *, -, U, C, I
               O      Old mark          *, -, =, _, n
               M      Mark              *, -, =, _, n

          (Note that upper and lower case keys are quite different in
          effect.)

     Rather that spell all this out here, I will refer you to the Help
     screens where everything will be revealed to you.  One example,
     though:

     You enter `dselect' and find a line like this:

EIOM Pri  Section  Package   Description
  ** Opt  misc     loadlin   a loader (running under DOS) for LINUX kernel

     This means that loadlin was selected when you last ran `dselect' and
     that it is still selected, but it is not installed.  Why not?  The
     answer must be that the loadlin package is not physically available,
     that is, it must be missing from your mirror.

     The information which `dselect' uses to get all the right packages
     installed is buried in the Packages files (the thing you downloaded in
     the [U]pdate step).  These files are generated from the packages
     themselves.

     Nothing in this world is perfect and it sometimes happens that the
     dependencies built into a package are incorrect, which can cause a
     situation that `dselect' simply cannot resolve.  However, you can get
     out of such a loop by using the commands _Q_ and _X_.

     _Q_
          An override.  Forces `dselect' to ignore the built-in
          dependencies and to do what you have specified.  This could, of
          course, turn out to be a bad idea.

     _X_
          Use _X_ if you get totally lost.  It puts things back the way
          they were and exits.

     Keys which help you _not_ to get lost (!) are _R_, _U_ and _D_.

     _R_
          Cancels all selections at this level.  Does not affect selections
          made at the previous level.

     _U_
          If `dselect' had proposed changes and then you made additional
          changes, _U_ will restore `dselect''s selections.

     _D_
          Removes the selections made by `dselect', leaving only yours.

     An example follows.  The `xmms' package (chosen because it has a lot
     of dependencies) depends on these packages:

        * `libc6'

        * `libglib1.2'

        * `libgtk1.2'

        * `xlibs'

     The following packages should also be installed.  These are not,
     however, essential:

        * `libaudiofile0'

        * `libesd0'

        * `libgl1'

        * `libmikmod2'

        * `libogg0'

        * `libvorbis0'

        * `libxml1'

        * `zlib1g'

     So, when I select `xmms', I get a screen like this:

dselect - recursive package listing                  mark:+/=/- verbose:v help:?
EIOM Pri Section  Package      Description
  _* Opt sound    xmms         Versatile X audio player that looks like Winamp
  _* Opt libs     libglib1.2   The GLib library of C routines
  _* Opt libs     libgtk1.2    The GIMP Toolkit set of widgets for X
  _* Opt libs     libmikmod2   A portable sound library
  _* Opt libs     libogg0      Ogg Bitstream Library
  _* Opt libs     libvorbis0   The OGG Vorbis lossy audio compression codec.

     (Other packages may or may not appear, depending on what is already in
     your system).  You'll notice that all the required packages have been
     selected for me, along with the recommended ones.

     The _R_ key puts things back to the starting point.

dselect - recursive package listing                  mark:+/=/- verbose:v help:?
EIOM Pri Section  Package      Description
  __ Opt sound    xmms         Versatile X audio player that looks like Winamp
  __ Opt libs     libglib1.2   The GLib library of C routines
  __ Opt libs     libgtk1.2    The GIMP Toolkit set of widgets for X
  __ Opt libs     libmikmod2   A portable sound library
  __ Opt libs     libogg0      Ogg Bitstream Library
  __ Opt libs     libvorbis0   The OGG Vorbis lossy audio compression codec.

     To decide now that you don't want `xmms', just hit _Enter_.

     The _D_key puts things the way I selected them in the first place:

dselect - recursive package listing                  mark:+/=/- verbose:v help:?
EIOM Pri Section  Package      Description
  _* Opt sound    xmms         Versatile X audio player that looks like Winamp
  __ Opt libs     libglib1.2   The GLib library of C routines
  __ Opt libs     libgtk1.2    The GIMP Toolkit set of widgets for X
  __ Opt libs     libmikmod2   A portable sound library
  __ Opt libs     libogg0      Ogg Bitstream Library
  __ Opt libs     libvorbis0   The OGG Vorbis lossy audio compression codec.

     The _U_ key restores `dselect''s selections:

dselect - recursive package listing                  mark:+/=/- verbose:v help:?
EIOM Pri Section  Package      Description
  _* Opt sound    xmms         Versatile X audio player that looks like Winamp
  _* Opt libs     libglib1.2   The GLib library of C routines
  _* Opt libs     libgtk1.2    The GIMP Toolkit set of widgets for X
  _* Opt libs     libmikmod2   A portable sound library
  _* Opt libs     libogg0      Ogg Bitstream Library
  _* Opt libs     libvorbis0   The OGG Vorbis lossy audio compression codec.

     I suggest running with the defaults for now -- you will have ample
     opportunity of adding more later.

     Whatever you decide, hit _Enter_ to accept and return to the main
     screen.  If this results in unresolved problems you will be bounced
     right back to another problem resolution screen.

     The _R_, _U_, and _D_ keys are very useful in ``what if'' situations.
     You can experiment at will and then restore everything and start
     again.  _Don't_ look on them as being in a glass box labelled ``Break
     In Emergency.''

     After making your selections in the ``Select'' screen, hit the _I_ to
     give you a big window, _t_ to take you to the beginning and then use
     the _Page-Down_ key to look quickly through the settings.  This way
     you can check the results of your work and spot glaring errors.  Some
     people have deselected whole groups of packages by mistake and didn't
     notice the error until it was too late.  `dselect' is a _very_
     powerful tool, so you better not misuse it.

     You should now have this situation:

          package category     status
          
          required             all selected
          important            all selected
          standard             mostly selected
          optional             mostly deselected
          extra                mostly deselected

     Happy?  Hit _Enter_ to exit the ``Select'' process.  You can come back
     and run ``Select'' again if you wish.


2.4. ``Install''
----------------

     `dselect' runs through the entire set of 8000 packages and installs
     those selected.  Expect to get asked to make decisions as you go.

     The screen scrolls past fairly quickly on a fast machine.  You can
     stop/start it with _Control-s_/_Control-q_ and at the end of the run
     you will get a list of any uninstalled packages.  If you want to keep
     a record of everything that happens, use common Unix programs for
     capturing output, like tee(1) or script(1).

     It can happen that a package does not get installed because it depends
     on some other package which is listed for installation but is not yet
     installed.  The answer to this is to run ``Install'' again.  It has
     been reported that sometimes it was necessary to run it 4 times before
     everything fit into place.  This will vary by your acquisistion
     method; with the APT method, you will almost never need to run
     ``Install'' again.


2.5. ``Configure''
------------------

     Most packages get configured in step 3, but anything left hanging can
     be configured here.


2.6. ``Remove''
---------------

     Removes packages that are installed but no longer required.


2.7. ``Quit''
-------------

     Exits `dselect'.

     I suggest running `/etc/cron.daily/find' at this point, as you have a
     lot of new files on your system.  After this you'll be able to use
     `locate' to find any given file.


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


3. A Few Hints in Conclusion
----------------------------

     You can get an idea of the size of a package by hitting _i_ twice and
     looking for the ``Size'' figure.  This is the size of the compressed
     package, so the uncompressed files will be a lot bigger (see
     ``Installed-Size'', which is in kilo-bytes, to know it).

     Installing a new Debian system is a fairly complex mission, but
     `dselect' can help you do it, if you are prepared to take the time to
     learn how to `drive' it.  Read the help screens and experiment with
     _i, I, o,_ and _O_.  Use the _R_ key.  It's all there, but it's up to
     you to use it effectively.


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


4. Glossary
-----------

     The following terms are useful to you in this document and in general,
     when talking about Debian.

     Package
          A file which contains everything needed to install and run a
          particular program.

          Debian package names have the <.deb> suffix.  Each package has a
          name and a version.  The version consists of the real version
          (`upstream') and the Debian revision, separated with a hyphen
          (`-').

          Here are some example package names:

             * `efax_08a-1.deb'

             * `lrzsz_0.12b-1.deb'

             * `mgetty_0.99.2-6.deb'

             * `minicom_1.75-1.deb'

             * `term_2.3.5-5.deb'

             * `uucp_1.06.1-2.deb'

             * `uutraf_1.1-1.deb'

             * `xringd_1.10-2.deb'

             * `xtel_3.1-2.deb'

     dpkg
          The program which handles packages is `dpkg'.  `dselect' is a
          front end to `dpkg'.  Experienced users often use `dpkg' to
          install or remove a package because it's quicker.

     package scripts, maintainer scripts
          The programs (usually shell scripts) that dpkg runs before and
          after installing each package.  They are usually quiet, but some
          of them can display warnings or ask you questions.


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


     `dselect' Documentation for Beginners

     Stéphane Bortzmeyer and others <debian-doc@lists.debian.org>