lenny/en/release-notes.dbk

<!DOCTYPE debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN" [
  <!entity % dynamicdata  SYSTEM "../dynamic.ent"       > %dynamicdata;
  <!entity % shareddata   SYSTEM "../release-notes.ent" > %shareddata;
  <!entity docid "$Id: release-notes.en.sgml,v 1.7 2004-12-05 16:10:39 robster Exp $">
]>

<debiandoc>
  <book>
  <titlepag>
    <title>Release Notes for &debian; &release; (`&releasename'), &arch-title;</title>
      <author>
        <name>Josip Rodin, Bob Hilliard, Adam Di Carlo, Anne Bezemer, Rob
        Bradford (current)</name><email></email>
      </author>
      <author>
        <name></name><email>debian-doc@lists.debian.org</email>
      </author>
      <version>&docid;</version>
    </titlepag>
    <toc detail="sect1">
      <chapt id="about"><heading>What's New in the Release Notes</heading>
       
        <p>[The most recent version of this document is always available at
        <url id="&url-release-notes;">. If your version is more than a month
        old, you might wish to download the latest version.]</p>

        <p>Please note that previous editions of the release notes contained
        information about upgrading from releases older than than the previous
        release. However such content often complicated the documentation so we
        have decided to only discuss upgrades from &debian; 3.0 ('woody'). If
        you need to upgrade from older releases please read previous editions of
        the release notes.</p>

      </chapt>
      <chapt id="whats-new"><heading>What's New in &debian; &release;</heading>

        <p>The list of supported architectures has not changed since the
        previous release, &debian; 3.0 ('woody'). Here is the full list of
        architectures for this release.</p>
        
        <p>
          <list>
            <item><p>Intel x86 ('i386')</p></item>
            <item><p>Motorola 680x0 ('m68k')</p></item>
            <item><p>Alpha ('alpha')</p></item>
            <item><p>SPARC ('sparc')</p></item>
            <item><p>PowerPC ('powerpc')</p></item>
            <item><p>ARM ('arm')</p></item>
            <item><p>MIPS ('mips' (Big endian) and 'mipsel' (Little endian))</p></item>
            <item><p>Intel Itanium ('ia64')</p></item>
            <item><p>HP PA-RISC ('hppa')</p></item>
            <item><p>S/390 ('s390')</p></item>
          </list>
        </p>

<![ %not-i386 [ 
          
<!-- i386 doesn't have a port page - or do they now? -->

          <p>You can read more about port status, and port-specific
          information for your architecture at the <url id="&url-ports;"
          name="Debian port web pages">.</p>
 
]]>

<![ %hppa %s390 %mips %mipsel %ia64 [ 

          <p>This is only the second official release of &debian; for the
          &arch-title; architecture. We feel that it has proven itself
          sufficiently to be released. However, because it has not had the
          exposure (and hence testing by users) that our other releases on
          other architectures have had, you may encounter a few bugs. Please
          use our <url id="&url-bts;" name="bug tracking system"> to report
          any problems; make sure to mention the fact that the bug is on the
          &architecture; platform.</p>

]]>

          <p>&debian; &release; for the &arch-title; architecture ships with
          kernel version &kernelversion;.</p>
<![ %available-2.6 [
          
          <p>On the &arch-title; architecture a 2.6 kernel is also available,
          this has kernel version &kernelversion-2.6;. Note that Debian's 2.6.8
          kernel packages include the 2.6.8.1 kernel release and selected other
          patches.</p>
]]>
        
        <sect id="newinst"><heading>What's New in the Installation System?</heading>

          <p>The old &debian; installation system has been replaced by a
          completely new installation system called
          <prgn>debian-installer</prgn>. The new installation system is
          modular in design and so has been developed with extensibility in
          mind.</p>
          
          <p>Some of the new features in the installation system include
          support for booting off USB flash devices, choosing
          <prgn>aptitude</prgn> to install packages in the first-boot stage
          and support for the <prgn>XFS</prgn> file system and
          <prgn>LVM</prgn> (a volume management tool.)</p>

          <p>For full details of the new Debian installation system, users
          are advised to read the Debian installation guide included on the
          first CD or at <url id="&url-install-manual;">.</p>

<![ %i386 [ 

          <p>Kernel images are available in various "flavours". These
          flavours each support a different set of hardware. The flavours
          available in &debian; &release; for &arch-title; are:</p>

          <p>
            <taglist>
              <tag>vanilla</tag>
              <item><p>The standard kernel package available in Debian. This
              includes almost all drivers supported by Linux built as
              modules. Including drivers for network devices, SCSI devices,
              sound cards, Video4Linux devices, etc. The
             `vanilla' flavour includes one boot, one root and two
              driver disks.</p></item>
              
              <tag>speakup</tag>
              <item><p>This is almost the same as the vanilla kernel above
              but with support for braille displays. A complete list of
              supported models may be found in the brltty documentation.
              This flavour includes one boot, one root and one driver floppy
              disk image.<p></item>
             
            </taglist>
<!-- FJP: I feel the info about floppies should be removed from this table as
          floppies are no longer the most used installation method. -->

          <p>The kernel config files for these flavours can be found in their
          respective directories in a file named 'kernel-config'.</p>

]]>

<!-- FJP: Maybe a short description of available installation methods could be
          added here: floppy, CD (netinst/business-card/full set), netboot,
          hd-media, USB-stick. -->

<![ %available-2.6 [
          <p>An installer using a 2.6 based kernel is available for
          &arch-title;. For more details on how to use it please consult the
          installation guide.</p>
]]>          
           
        </sect>
        <sect id="newdistro"><heading>What's New in the Distribution?</heading> 
           
           <p>To replace the aging, much-maligned, yet still popular
           <package>dselect</package>, many apt frontends have been in
           development during the woody release cycle. Interested users
           should investigate the <package>aptitude</package> and
           <package>synaptic</package> packages.</p>
       
           <p>This release of &debian; contains the much improved XFree86
           4.3 release, which includes support for a greater range of
           hardware, better autodetection support, and improved support for
           advanced technologies such as Xinerama and 3D acceleration.</p>
           
           <p>&debian; is more desktop orientated than ever in this new release,
           it now includes GNOME 2.6 and KDE 3.2. Also included for the
           first time is a complete office suite in the form of OpenOffice.Org
           1.1, other productivity tools included in the release are the
           Evolution groupware software and GAIM instant messaging client.
           
           <p>The official &debian; distribution now ships on thirteen
           binary CDs with a similar number of source CDs, and a DVD version
           of the distribution is now also available.</p></sect>

      </chapt>

      <chapt id="installing"><heading>New Installations</heading>

        <p>If you are making a new installation of Debian, you should read
        the installation manual, which is available on the Official CD at:

        <example>        
          /dists/&releasename;/main/disks-&architecture;/current/doc/install.txt
          (or .html)
        
        </example></p>

        <p>or on the Internet at: <url id="&url-install-manual;">.</p>

        <p>The old &debian; installation system called
        <prgn>boot-floppies</prgn> has been replaced by a new componentized and
        more powerful installation system called <prgn>debian-installer</prgn>.</p>
      
      </chapt>


      <chapt id="upgrading"><heading>Upgrades from Previous Releases</heading>

<!-- For doc-writers' convenience:
Debian Supported
release: architectures:

1.3.1 or less i386
2.0           i386,m68k
2.1           i386,m68k,alpha,sparc
2.2           i386,m68k,alpha,sparc,powerpc,arm
3.0             + hppa s390 mips mipsel ia64
-->

        <sect id="information"><heading>Detailed Changes to the System</heading>

        <sect1 id="syntax"><heading>Important program syntax changes</heading>
          <p>Debian attempts to avoid changing upstream packages, therefore
          any changes in the upstream package will be present in the version in
          &debian;. This can mean that program behaviour may change between
          releases of &debian;. </p>

          <p><em>No changes yet reported.</em></p>
        
        </sect1>
        
        </sect>
        <sect id="backup"><heading>Preparing for the Upgrade</heading>

          <p>Before upgrading your system, it is strongly recommended that
          you make a full backup, or at least backup any data or
          configuration information you can't afford to lose. The upgrade
          tools and process are quite reliable, but a hardware failure in
          the middle of an upgrade could result in a severely damaged
          system.</p>

          <p>The main things you'll want to back up are the contents of
          <file>/etc</file>, <file>/var/lib/dpkg</file> and the output of
          <tt>dpkg --get-selections \*</tt>.</p>

          <p>It's wise to inform all users in advance of any upgrades you're
          planning, although users accessing your system via SSH (at least)
          shouldn't notice much during the upgrade, and may want to continue
          working. If you wish to take extra precautions, back up or unmount
          user's partitions (<file>/home</file>) before upgrading. A reboot
          will not normally be necessary.</p>

          <p>Distribution upgrade should be done either locally from a
          textmode virtual console (or a directly connected serial
          terminal), or remotely via an <prgn/ssh/ link.</p>

          <p><em/Important/: You should <em/not/ upgrade using <prgn/telnet/,
          <prgn/rlogin/, <prgn/rsh/, or from an X session managed by <prgn/xdm/,
          <prgn/gdm/ or <prgn/kdm/ etc on the machine you are upgrading. That is
          because each of those services may well be terminated during the
          upgrade, which can result in an <em/inaccessible/ system that is only
          half-upgraded.</p>

        <sect1><heading>Disabling APT Pinning</heading>

          <p>If you have configured APT to install certain packages from a
          distribution other than stable (e.g from testing), you may have to
          change your APT pinning configuration (stored in
          <file>/etc/apt/preferences</file>) to allow the upgrade of packages to
          the versions in the new stable release. Further information on APT
          pinning can be found in <manref name="apt_preferences" section="5">.</p>
<!-- FJP: Couldn't the advise to hold such packages prevent the upgrade of e.g.
          libc6 if the package depends on the old version! -->

        </sect1>
        
        <sect1><heading>Checking Packages Status</heading>

          <p>Regardless of the method used for upgrading, it is recommended
          that you check the status of all packages first, and verify that
          all packages are in an upgradable state. The following command
          will show any packages which have a status of Half-Installed or
          Failed-Config, and those with any error status.

          <example>
        
            # dpkg --audit
          
          </example></p>
 
          <p>You could also inspect the state of all packages on your system
          using <prgn/dselect/, <prgn/aptitude/, or with commands such as

          <example>
         
            # dpkg -l | pager 

          </example></p>

          <p>or

          <example>
         
            # dpkg --get-selections &gt; ~/curr-pkgs.txt

          </example></p>

          <p>It is desirable to remove any holds before upgrading. If any
          package that is essential for the upgrade is on hold, the upgrade
          will fail. You can identify packages on hold with
 
          <example>
         
            # dpkg --audit
       
          </example></p>

          <p>If you changed and recompiled a package locally, and didn't rename
          it or put an epoch in the version, you must put it on hold to prevent
          it from being upgraded. The `hold' package state can be changed by
          using <prgn/aptitude/. With 
          
          <example>
          aptitude hold | unhold &lt;package&gt;
          </example>
            </p>
        </sect1>
        <sect1><heading>Special Considerations for SSH Users</heading>

          <p>The commercial SSH located in the <package/ssh/ package before
          release 2.2 or in the <package/ssh-nonfree/ package in release 2.2 has
          been replaced by the DFSG free <package/ssh/ package (OpenSSH) in
          this release. The commercial SSH collection is no longer present. 
          The <package/ssh/ package includes a Debconf question which will
          regenerate a configuration which is OpenSSH compatible.</p>
          
        <sect1><heading>Directories Possibly Needing Attention</heading>

          <p>It is important that the <file>/etc/rcS.d</file> directory
          exists prior to the upgrade; the installation of the
          <package/libc6/ package will fail otherwise.</p>

          <p>The <file>/usr/share/doc</file> directory (if it exists
          already) should not be a symlink (e.g. to <file>/usr/doc</file>),
          since that will cause some packages to break. However, symlinking
          <file>/usr/doc</file> to <file>/usr/share/doc</file> is allowed. 
          Please note that if you use such a symlink there will be numerous
          messages about <file>/usr/doc</file> directories that can't be
          removed. Those are normal, and you can safely ignore them.</p></sect1></sect>


        <sect id="upgrade-process"><heading>Preparing Sources for APT</heading>

          <p>The recommended method of upgrading is to use <prgn/aptitude/, as
          described here. The built-in dependency analysis enables smooth
          upgrades and easy installations.</p>
          
          <p>Any package installation operation must be run with superuser
          privileges, so either login as root or use <prgn/su/ or
          <prgn/sudo/ to gain the necessary access rights.</p>

          <p>Before starting the upgrade you must set up <package/apt/'s
          configuration file for package lists,
          <file>/etc/apt/sources.list</file>.</p>
          
          <p><package/apt/ will consider all packages that can be found via
          any "<tt>deb</tt>" line, and install the package with the highest
          version number, giving priority to the first mentioned lines (that
          way, in case of multiple mirror locations, you'd typically first
          name a local harddisk, then CD-ROMs, and then HTTP/FTP
          mirrors).</p>

         <sect1 id="network"><heading>Adding APT Internet Sources</heading>

           <p>The default configuration is set up for installation from main
           Debian Internet servers, but you may wish to modify
           <file>/etc/apt/sources.list</file> to use other mirrors,
           preferably a mirror that is network-wise closest to you.</p>

<!-- FJP: Why is 'default configuration' relevant here? We are talking about
          upgrading existing installations; we really have no idea what
          apt-sources users will have set up here (maybe just a Woody CD-set).
          Note: D-I sets the default configuration to a mirror based on
          the selected country and not the 'main' servers. -->

           <p>Debian HTTP or FTP mirror addresses can be found at
           <url id="&url-debian-mirrors;"> (look at the "Full list of
           mirrors" section). HTTP mirrors are generally speedier than FTP
           mirrors.</p>
<!-- FJP: 'Otherwise' does not refer back to anything here, so I deleted it
          (unless the intention was to refer to local intr_a_net HTTP
          servers in the previous para). -->

           <p>For example, suppose your closest Debian mirror is
           <tt>&url-debian-mirror-eg;/</tt>. When inspecting that mirror
           with a web browser or FTP program, you will notice that the main
           directories are organized like this:

           <example>
           
             &url-debian-mirror-eg;/dists/stable/main/binary-&architecture;/...
             &url-debian-mirror-eg;/dists/stable/contrib/binary-&architecture;/...
       
           </example></p>

           <p>To use this mirror with <prgn/apt/, you add this line to your
           <file/sources.list/ file:

           <example>
           
             deb &url-debian-mirror-eg; &releasename; main contrib
 
           </example></p>

           <p>Note that the `<tt>dists</tt>' is added implicitly, and the
           arguments after the release name are used to expand the path into
           multiple directories.</p>

           <p>After adding your new sources, disable the previously existing
           "<tt/deb/" lines in <file/sources.list/, by placing a hash sign
           (<tt/#/) in front of them.</p>

           <p>Any package needed for installation that is fetched from the
           network is stored in <file>/var/cache/apt/archives</file>
           (and the <file>partial/</file> subdirectory, during download), so
           you must make sure you have enough space before attempting to
           start the installation. With a reasonably extended Debian
           installation, you can expect at least 300 MB of downloaded
           data.</p>
           
         </sect1>

         <sect1 id="localmirror"><heading>Adding APT Local Mirror Sources</heading>

           <p>Instead of using HTTP or FTP packages mirrors, you may wish to
           modify <file>/etc/apt/sources.list</file> to use a mirror on a
           local disk (possibly NFS-mounted).</p>

           <p>For example, your packages mirror may be under
           <file>/var/ftp/debian/</file>, and have main directories like
           this:

           <example>
           
             /var/ftp/debian/dists/stable/main/binary-&architecture;/...
             /var/ftp/debian/dists/stable/contrib/binary-&architecture;/...
           
           </example></p>

           <p>To use this with <prgn/apt/, add this line to your
           <file/sources.list/ file:

           <example>
             deb file:/var/ftp/debian &releasename; main contrib
           </example></p>

           <p>Note that the `<tt>dists</tt>' is added implicitly, and the
           arguments after the release name are used to expand the path into
           multiple directories.</p>

          <p>After adding your new sources, disable the previously
          existing "<tt/deb/" lines in <file/sources.list/, by placing a
          hash sign (<tt/#/) in front of them.</p></sect1>

        <sect1 id="cdroms"><heading>Adding APT CD-ROM Sources</heading>

<!-- FJP: Are these instructions also valid for adding DVD's? -->

          <p>See above if you need to first install the latest version of
          <package/apt/ and <package/dpkg/ packages, as described above.</p>
<!-- FJP: See above [...], as described above is a bit double.
          Also, I don't think the need to update the package tools and how
          to do that has been descibed 'above' yet. -->

          <p>If you want to use CDs <em/only/, comment out the existing
          "<tt/deb/" lines in <file>/etc/apt/sources.list</file> by placing
          a hash sign (<tt/#/) in front of them.</p>

          <p>Make sure there is a line in <file>/etc/fstab</file> that
          enables mounting your CD-ROM drive at the <file>/cdrom</file>
          mount point (the exact <file>/cdrom</file> mount point is required
          for <prgn/apt-cdrom/). For example, if <file>/dev/hdc</file> is
          your CD-ROM drive, <file>/etc/fstab</file> should contain a line
          like:

          <example>
             
             /dev/hdc /cdrom auto defaults,noauto,ro 0 0
             
          </example></p>

          <p>Note that there must be <em/no spaces/ between the words
          <tt>defaults,noauto,ro</tt> in the fourth field.</p>

          <p>To verify it works, insert a CD and try running

          <example>
 
            mount /cdrom (this will mount the CD to the mount point)
            ls -alF /cdrom (this should show the CD's root directory)
            umount /cdrom (this will unmount the CD)
     
          </example></p>

          <p>Next, run:

          <example>
            apt-cdrom add
          </example></p>

          <p>for each Debian Binary CD-ROM you have, to add the data about
          each CD to APT's database.</p>
        </sect1>
        </sect>

        <sect id="upgradingpackages"><heading>Upgrading packages</heading>
          
          <p>The recommended tool for upgrading between &debian; releases is
          to use the package management tool <prgn>aptitude</prgn>. This tool
          makes safer decisions about package installations than running
          <prgn>apt-get</prgn> directly.</p>
          
          <p>Don't forget to mount all needed partitions (notably the root
          and <file>/usr</file> partitions) read-write, with a command
          like:

          <example>
            mount -o remount,rw /<var>mountpoint</var>
          </example></p>

          <p>Next ensure that the APT source entries (in
          <file>/etc/apt/sources.list</file>) refer to the <tt>'stable'</tt>
          distribution and do not refer to it by its codename (e.g.
          <tt>&oldreleasename;</tt>).
          
          <p>It is strongly recommended that you use the
          <prgn>/usr/bin/script</prgn> program to record a transcript of the
          upgrade session. Then if any problems develop, you will have a log of
          what happened, and if needed, can provide exact information in a bug
          report. To start the recording, type:

          <example>
            script -a ~/upgrade-to-sarge.typescript
          </example></p>

          <p>or similar. Do not put the typescript file in a temporary
          directory such as <file>/tmp</file> or <file>/var/tmp</file> (files
          in those directories may be deleted during the upgrade or during any
          restart).</p>
 
          <p>Next the <package>aptitude</package> package needs to be installed.
          This is done with:</p> 
          
          <p><example>
          apt-get install aptitude
          </example></p>

          <p>Provided that you have a working APT configuration as described
          above this will install the &releasename; version of
          <prgn>aptitude</prgn>.</p>
<!-- FJP: Will it really? Haven't we have just instructed users to point
          everything to the new release? -->

          <p>First <prgn>aptitude</prgn> needs to fetch a list of new and
          updated packages for the new release. This is done by executing:</p>
          
          <p><example>
          aptitude update
          </example></p>

          <p>Once <prgn>aptitude</prgn> has information on all the available
          packages, the system is almost ready to be fully upgraded.</p>
<!-- FJP: Why 'almost'? The next command will perform the upgrade.
          'Almost' implies the user needs to do something else first... -->

          <p><example>
          aptitude -f --with-suggests --with-recommends dist-upgrade
          </example></p>

          <p>This will perform a complete upgrade of the system, i.e.  install
          the newest available versions of all packages, and resolve all
          possible dependency changes between packages in different releases.
          If necessary, it will install some new packages (usually new library
          versions, or renamed packages), and remove any conflicting obsoleted
          packages (such as <package>console-tools-libs</package>).</p>

          <p>When upgrading from a set of CD-ROMs, you will be asked to
          insert specific CDs at several points during the upgrade. You
          might have to insert the same CD multiple times; this is due to
          inter-related packages that have been spread out over the CDs.</p>
   
          <p>New versions of currently installed packages that cannot be
          upgraded without changing the install status of another package will
          be left at their current version (displayed as "held back"). This can
          be resolved by either using <prgn>aptitude</prgn> to choose these
          packages for installation or by trying <tt>aptitude -f install
          &lt;package&gt;</tt>.</p>
            
          <p>The <tt/--fix-broken/ (or just <tt/-f/) option causes
          <package/apt/ to attempt to correct a system with broken
          dependencies in place. <package/apt/ does not allow broken package
          dependencies to exist on a system.</p>

        <sect1 id="trouble"><heading>Possible Issues During or After Upgrade</heading>

          <p>Sometimes it's necessary to enable APT::Force-LoopBreak option
          in APT to be able to temporarily remove an essential package due
          to a Conflicts/Pre-Depends loop. <prgn/aptitude/ will alert you of
          this and abort the upgrade. You can work around that by specifying
          <tt>-o APT::Force-LoopBreak=1</tt> option on <prgn/aptitude/
          command line.</p>

          <p>It is possible that a system's dependency structure can be so
          corrupt as to require manual intervention. Usually this means
          using <prgn/aptitude/ or

          <example>
          
            dpkg --remove <var>packagename</var>
          
          </example></p>

          <p>to eliminate some of the offending packages, or
 
          <example>

            aptitude --fix-broken install
            dpkg --configure --pending

          </example></p>

          <p>In extreme cases you might have to force re-installation with a
          command like

          <example>

            dpkg --install /path/to/packagename.deb

          </example></p>

          <p>After fixing things up, you should be able to resume the
          upgrade by repeating the previously described <tt/dist-upgrade/
          commands.</p>

          <p>During the upgrade, you will be asked questions to configure or
          re-configure several packages. When you are asked if any file in
          the <file>/etc/init.d</file> or <file>/etc/terminfo</file>
          directories, or the <file>/etc/manpath.config</file> file should
          be replaced by the package maintainer's version, it's usually
          necessary to answer `yes' to ensure system consistency. You can
          always revert to the old versions, since they will be saved with a
          <tt/.dpkg-old/ extension.</p>

          <p>If you're not sure what to do, write down the name of the
          package or file, and sort things out at a later time. You can
          search in the typescript file to review the information that
          was on the screen during the upgrade.</p></sect1>

        <sect1 id="nownownow"><heading>ToDo Before the Next Reboot</heading>

          <p>When <tt>aptitude dist-upgrade</tt> has finished, the
          "formal" upgrade is complete, but there are some other things
          that should be taken care of <em/before/ the next reboot.</p>
          
  <p>Read
          <file>/usr/share/doc/xfree86-common/README.Debian-upgrade</file> for
          more info on the upgrade of the X window system packages. This is
          relevant for users of all previous Debian releases. In short, you
          need to read it.</p>

        <sect2 id="newkernel"><heading>Upgrading your kernel</heading>
          
          <p>Note that the Linux kernel was <em/not/ upgraded by these
          procedures.You may wish to do so yourself, either by installing one
          of the <package/kernel-image-*/ packages or by compiling a customized
          kernel from sources.</p> 
          
          <![ %available-2.6 [

         <p>&debian; comes with a &kernelversion; kernel which is in the 2.4
         series, the older stable Linux kernel series. You may wish to use a 2.6
         series kernel for better hardware support or improved performance.</p>
         
]]>
         
         <p>To upgrade your kernel you must first choose the kernel most
         apropriate for your subarchitecture. A list of kernels available for
         you to install can be found with:
<!-- FJP: s/subarchitecture/subarchitecture and processor/ ??? -->

         <example>
           
           apt-cache search ^kernel-image

         </example></p>
         
         <p>You should then use <tt/aptitude install/ to install it. Once
         this new kernel is installed you should reboot at the next available
         oppurtunity to get the benefit.</p>

         <p>For the more adventurous there is an easy way to compile your
         own custom kernel on &debian;. Install the
         <package>kernel-package</package> tool and read the documentation
         in <file>/usr/share/doc/kernel-package</file>.</p>
         
         </sect2></sect1></sect>

      </chapt>


      <chapt id="moreinfo">

        <heading>More information on &debian;</heading>

        <sect id="morereading"> <heading>Further Reading</heading>
        <p>Beyond these release notes and the installation guide further
        documentation on &debian; is available from the Debian
        Documentation Project (DDP), whose goal is to create high quality
        documentation for Debian users and developers. Documentation
        including the Debian Guide, Debian New Maintainers Guide, and Debian
        FAQ are available, and many more. For full details of the resources
        available see the DDP website at <url
        id="&url-ddp;">.</p>
 
        <p>Documentation for individual packages is installed into
        <file>/usr/share/doc/<var>package</var></file>, this may include
        copyright information, Debian specific details and any upstream
        documentation.</p>
 
      </sect> 
      
      <sect id="gethelp"> 
        <heading>Getting Help</heading> 
      
        <p> There are many sources of help, advice and support for Debian
        users, but these should only be considered if research into
        documentation of the issue has exhausted all sources. This section
        provides a short introduction into these which may be helpful for
        new Debian users.</p>
        
      <sect1 id="lists">
        <heading>Mailing lists</heading>
        <p>The mailing lists of most interest to Debian users are the
        debian-user list (English) and other debian-user-<var/language/ lists
        (for other languages). For information on these lists and details of
        how to subscribe see <url id="&url-debian-list-archives;">. Please
        check the archives for answers to your question prior to posting and
        also adhere to standard list etiquette.</p>
      </sect1>

      <sect1 id="irc">
        <heading>Internet Relay Chat</heading> 
        
        <p>Debian has an IRC channel dedicated to the support and aid of
        Debian users located on the Open Projects IRC network which is
        dedicated to providing collaborative information sharing resources
        for the Open Source community. To access the channel point your
        favourite IRC client at &opn-irc-server; and join #debian.</p>
        
        <p>Please follow the channel guidelines, respecting other users
        fully. For more information on Open Projects please visit the <url
        id="&url-opn;" name="website">.</p>

      </sect1>
      </sect> 

      <sect id="bugs">
        <heading>Reporting Bugs</heading>
        
        <p>We strive to make Debian GNU/Linux a high quality operating
        system, however that does not mean that the packages we provide are
        totally free of bugs. As our service to our users we provide all the
        information on reported bugs at our own Bug Tracking System (BTS)
        browseable at <url id="&url-bts;" name="bugs.debian.org">, this is
        consistent with Debian's open development.</p>
<!-- FJP: I propose to replace the last sentence by:
        Consistent with Debian's 'open development' philosophy and as a 
        service to our users, we provide all the information on reported bugs
        at our own Bug Tracking System (BTS). The BTS is browseable at
        <url id="&url-bts;" name="bugs.debian.org">.
-->

        <p>If you find a bug in the distribution or in packaged software
        that is part of it, please report it so that it can be properly
        fixed for next releases. Reporting bugs requires a valid email
        address, we ask for this so that we can trace bugs and developers
        can get in contact with submitters should they need more
        information.</p>

        <p>You can submit a bug report using the program
        <package>reportbug</package> or manually using email. 
        You can read more about the Bug Tracking System and how to use it by
        reading the reference cards (available at
        <file>/usr/share/doc/debian</file> in any installed system) or
        online at the <url id="&url-bts;" name="Bug Tracking
        System">.</p>
<!-- FJP: The 'bug' program and package are obsolete. -->

      </sect>

      <sect id="contributing">
        <heading>Contributing to Debian</heading>
        
        <p>You do not need to be an expert to contribute to Debian. By
        assisting users with problems on the various user support <url
        id="&url-debian-list-archives;" name="lists"> you are contributing to
        the community. Identifying (and importantly solving) problems
        related to the development of the distribution by participating on
        the development <url id="&url-debian-list-archives;" name="lists"> is
        also extremely helpful. To maintain Debian's high quality
        distribution <url id="&url-bts;" name="submit bugs">
        and help developers track them down and fix them. If you have a way
        with words then you may want to contribute more actively by helping
        to write <url id="&url-ddp;"
        name="documentation"> or <url
        id="&url-debian-i18n;" name="translate"> existing
        documentation into your own language.</p>

        <p>If you can dedicate more time, you could manage a piece of the
        Free Software collection within Debian. Especially helpful is if
        people adopt or maintain items that people have requested for
        inclusion within Debian, the <url id="&url-wnpp;" name="Work Needing
        and Prospective Packages database"> details this information. If you
        have an interest in specific groups then you may find enjoyment in
        contributing to some of Debian's subprojects which include ports to
        particular architectures, <url id="&url-debian-jr;" name="Debian
        Jr."> and <url id="&url-debian-med;" name="Debian Med">.</p>

        <p>In any case, if you are working in the free software community in
        any way, as a user, programmer, writer or translator you are already
        helping the free software effort. Contributing is rewarding and fun,
        and as well as allowing you to meet new people it gives you that
        warm fuzzy feeling inside.</p></sect>

    </chapt>
  </book>
</debiandoc>

<!-- Keep this comment at the end of the file
Local Variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-namecase-general:t
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:nil
sgml-declaration:nil
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
fill-column: 75
End:
-->
