doc: Convert from DebianDoc SGML to DocBook XML

1 files changed, 0 insertions, 547 deletions

diff --git a/doc/guide.sgml b/doc/guide.sgml
deleted file mode 100644
index 747c5718c..000000000
--- a/doc/guide.sgml
+++ /dev/null
@@ -1,547 +0,0 @@
-<!-- -*- mode: sgml; mode: fold -*- -->
-<!doctype debiandoc  PUBLIC  "-//DebianDoc//DTD DebianDoc//EN">
-<book>
-<title>APT User's Guide</title>
-
-<author>Jason Gunthorpe <email>jgg@debian.org</email></author>
-<version>$Id: guide.sgml,v 1.7 2003/04/26 23:26:13 doogie Exp $</version>
-
-<abstract>
-This document provides an overview of how to use the the APT package manager.
-</abstract>
-
-<copyright>
-Copyright &copy; Jason Gunthorpe, 1998.
-<p>
-"APT" and this document are free software; you can redistribute them and/or
-modify them under the terms of the GNU General Public License as published
-by the Free Software Foundation; either version 2 of the License, or (at your
-option) any later version.
-
-<p>
-For more details, on Debian systems, see the file
-/usr/share/common-licenses/GPL for the full license.
-</copyright>
-
-<toc sect>
-
-<!-- General		                                               {{{ -->
-<!-- ===================================================================== -->
-<chapt>General
-
-<p>
-The APT package currently contains two sections, the APT <prgn>dselect</>
-method and the <prgn>apt-get</> command line user interface. Both provide 
-a way to install and remove packages as well as download new packages from 
-the Internet. 
-
-<sect>Anatomy of the Package System
-<p>
-The Debian packaging system has a large amount of information associated with
-each package to help assure that it integrates cleanly and easily into
-the system. The most prominent of its features is the dependency system.
-
-<p>
-The dependency system allows individual programs to make use of shared 
-elements in the system such as libraries. It simplifies placing infrequently 
-used portions of a program in separate packages to reduce the
-number of things the average user is required to install. Also, it allows
-for choices in mail transport agents, X servers and 
-so on.
-
-<p>
-The first step to understanding the dependency system is to grasp the concept
-of a simple dependency. The meaning of a simple dependency is that a package
-requires another package to be installed at the same time to work properly.
-
-<p>
-For instance, mailcrypt is an emacs extension that aids in encrypting email
-with GPG. Without GPGP installed mailcrypt is useless, so mailcrypt has a
-simple dependency on GPG. Also, because it is an emacs extension it has a 
-simple dependency on emacs, without emacs it is completely useless.
-
-<p>
-The other important dependency to understand is a conflicting dependency. It
-means that a package, when installed with another package, will not work and
-may possibly be extremely harmful to the system. As an example consider a
-mail transport agent such as sendmail, exim or qmail. It is not possible
-to have two mail transport agents installed because both need to listen to
-the network to receive mail. Attempting to install two will seriously
-damage the system so all mail transport agents have a conflicting dependency
-with all other mail transport agents.
-
-<p>
-As an added complication there is the possibility for a package to pretend
-to be another package. Consider that exim and sendmail for many intents are
-identical, they both deliver mail and understand a common interface. Hence,
-the package system has a way for them to declare that they are both
-mail-transport-agents. So, exim and sendmail both declare that they provide a
-mail-transport-agent and other packages that need a mail transport agent
-depend on mail-transport-agent. This can add a great deal of confusion when 
-trying to manually fix packages.
-
-<p>
-At any given time a single dependency may be met by packages that are already
-installed or it may not be. APT attempts to help resolve dependency issues
-by providing a number of automatic algorithms that help in selecting packages
-for installation.
-</sect>
-
-</chapt>
-                                                                  <!-- }}} -->
-<!-- apt-get		                                               {{{ -->
-<!-- ===================================================================== -->
-<chapt>apt-get
-
-<p>
-<prgn>apt-get</> provides a simple way to install packages from the command 
-line. Unlike <prgn>dpkg</>, <prgn>apt-get</> does not understand .deb files, 
-it works with the package's proper name and can only install .deb archives from 
-a <em>Source</>.
-
-<p>
-The first <footnote>If you are using an http proxy server you must set the
-http_proxy environment variable first, see sources.list(5)</footnote> thing that 
-should be done before using <prgn>apt-get</> is to fetch the package lists
-from the <em>Sources</> so that it knows what packages are 
-available. This is done with <tt>apt-get update</>. For instance,
-
-<p>
-<example>
-# apt-get update
-Get http://ftp.de.debian.org/debian-non-US/ stable/binary-i386/ Packages
-Get http://llug.sep.bnl.gov/debian/ testing/contrib Packages
-Reading Package Lists... Done
-Building Dependency Tree... Done
-</example>
-
-<p>
-Once updated there are several commands that can be used:
-<taglist>
-<tag>upgrade<item>
-Upgrade will attempt to gently upgrade the whole system. Upgrade will
-never install a new package or remove an existing package, nor will it
-ever upgrade a package that might cause some other package to break.
-This can be used daily to relatively safely upgrade the system. Upgrade
-will list all of the packages that it could not upgrade, this usually
-means that they depend on new packages or conflict with some other package.
-<prgn>dselect</> or <tt>apt-get install</> can be used to force these
-packages to install.
-
-<tag>install<item>
-Install is used to install packages by name. The package is 
-automatically fetched and installed. This can be useful if you already
-know the name of the package to install and do not want to go into a GUI
-to select it. Any number of packages may be passed to install, they will
-all be fetched. Install automatically attempts to resolve dependency problems
-with the listed packages and will print a summary and ask for confirmation
-if anything other than its arguments are changed.
-
-<tag>dist-upgrade<item>
-Dist-upgrade is a complete upgrader designed to simplify upgrading between
-releases of Debian. It uses a sophisticated algorithm to determine the best
-set of packages to install, upgrade and remove to get as much of the system
-to the newest release. In some situations it may be desired to use dist-upgrade
-rather than spend the time manually resolving dependencies in <prgn>dselect</>.
-Once dist-upgrade has completed then <prgn>dselect</> can be used to install
-any packages that may have been left out.
-
-<p>
-It is important to closely look at what dist-upgrade is going to do, its
-decisions may sometimes be quite surprising.
-</taglist>
-
-<p>
-<prgn>apt-get</> has several command line options that are detailed in its
-man page, <manref name="apt-get" section="8">. The most useful option is 
-<tt>-d</> which does not install the fetched files. If the system has to
-download a large number of package it would be undesired to start installing
-them in case something goes wrong. When <tt>-d</> is used the downloaded
-archives can be installed by simply running the command that caused them to
-be downloaded again without <tt>-d</>.
-
-</chapt>
-                                                                  <!-- }}} -->
-<!-- DSelect		                                               {{{ -->
-<!-- ===================================================================== -->
-<chapt>DSelect
-<p>
-The APT <prgn>dselect</> method provides the complete APT system with 
-the <prgn>dselect</> package selection GUI. <prgn>dselect</> is used to
-select the packages to be installed or removed and APT actually installs them.
-
-<p>
-To enable the APT method you need to select [A]ccess in <prgn>dselect</> 
-and then choose the APT method. You will be prompted for a set of 
-<em>Sources</> which are places to fetch archives from. These can be remote
-Internet sites, local Debian mirrors or CD-ROMs. Each source can provide
-a fragment of the total Debian archive, APT will automatically combine them
-to form a complete set of packages. If you have a CD-ROM then it is a good idea
-to specify it first and then specify a mirror so that you have access to
-the latest bug fixes. APT will automatically use packages on your CD-ROM before
-downloading from the Internet.
-
-<p>
-<example>
-   Set up a list of distribution source locations
-	 
- Please give the base URL of the debian distribution.
- The access schemes I know about are: http file
-	   
- For example:
-      file:/mnt/debian,
-      ftp://ftp.debian.org/debian,
-      http://ftp.de.debian.org/debian,
-      
-      
- URL [http://llug.sep.bnl.gov/debian]: 
-</example>
-
-<p>
-The <em>Sources</> setup starts by asking for the base of the Debian
-archive, defaulting to a HTTP mirror. Next it asks for the distribution to
-get.
-
-<p>
-<example>
- Please give the distribution tag to get or a path to the
- package file ending in a /. The distribution
- tags are typically something like: stable unstable testing non-US
-   
- Distribution [stable]: 
-</example>
-
-<p>
-The distribution refers to the Debian version in the archive, <em>stable</>
-refers to the latest released version and <em>unstable</> refers to the
-developmental version. <em>non-US</> is only available on some mirrors and
-refers to packages that contain encryption technology or other things that
-cannot be exported from the United States. Importing these packages into the
-US is legal however. 
-
-<p>
-<example>
- Please give the components to get
- The components are typically something like: main contrib non-free
-  
- Components [main contrib non-free]:
-</example>
-
-<p>
-The components list refers to the list of sub distributions to fetch. The
-distribution is split up based on software licenses, main being DFSG free
-packages while contrib and non-free contain things that have various 
-restrictions placed on their use and distribution.
-
-<p>
-Any number of sources can be added, the setup script will continue to
-prompt until you have specified all that you want.
-
-<p>
-Before starting to use <prgn>dselect</> it is necessary to update the 
-available list by selecting [U]pdate from the menu. This is a superset of 
-<tt>apt-get update</> that makes the fetched information available to
-<prgn>dselect</>. [U]pdate must be performed even if <tt>apt-get update</>
-has been run before.
-
-<p>
-You can then go on and make your selections using [S]elect and then 
-perform the installation using [I]nstall. When using the APT method
-the [C]onfig and [R]emove commands have no meaning, the [I]nstall command
-performs both of them together. 
-
-<p>
-By default APT will automatically remove the package (.deb) files once they have been
-successfully installed. To change this behavior place <tt>Dselect::clean 
-"prompt";</> in /etc/apt/apt.conf.
-
-</chapt>
-                                                                  <!-- }}} -->
-<!-- The Interfaces						       {{{ -->
-<!-- ===================================================================== -->
-<chapt>The Interface
-
-<p>
-Both that APT <prgn>dselect</> method and <prgn>apt-get</> share the same
-interface. It is a simple system that generally tells you what it will do
-and then goes and does it. 
-<footnote>
-The <prgn>dselect</> method actually is a set of wrapper scripts
-to <prgn>apt-get</>. The method actually provides more functionality than
-is present in <prgn>apt-get</> alone.
-</footnote>
-After printing out a summary of what will happen APT then will print out some
-informative status messages so that you can estimate how far along it is and
-how much is left to do.
-
-<!-- ===================================================================== -->
-<sect>Startup
-
-<p>
-Before all operations except update, APT performs a number of actions to
-prepare its internal state. It also does some checks of the system's state.
-At any time these operations can be performed by running <tt>apt-get check</>.
-<p>
-<example>
-# apt-get check
-Reading Package Lists... Done
-Building Dependency Tree... Done
-</example>
-
-<p>
-The first thing it does is read all the package files into memory. APT
-uses a caching scheme so this operation will be faster the second time it
-is run. If some of the package files are not found then they will be ignored
-and a warning will be printed when apt-get exits. 
-
-<p>
-The final operation performs a detailed analysis of the system's dependencies.
-It checks every dependency of every installed or unpacked package and considers
-if it is OK. Should this find a problem then a report will be printed out and
-<prgn>apt-get</> will refuse to run.
-
-<p>
-<example>
-# apt-get check
-Reading Package Lists... Done
-Building Dependency Tree... Done
-You might want to run apt-get -f install' to correct these.
-Sorry, but the following packages have unmet dependencies:
-  9fonts: Depends: xlib6g but it is not installed
-  uucp: Depends: mailx but it is not installed
-  blast: Depends: xlib6g (>= 3.3-5) but it is not installed
-  adduser: Depends: perl-base but it is not installed
-  aumix: Depends: libgpmg1 but it is not installed
-  debiandoc-sgml: Depends: sgml-base but it is not installed
-  bash-builtins: Depends: bash (>= 2.01) but 2.0-3 is installed
-  cthugha: Depends: svgalibg1 but it is not installed
-           Depends: xlib6g (>= 3.3-5) but it is not installed
-  libreadlineg2: Conflicts:libreadline2 (<< 2.1-2.1)
-</example>
-
-<p>
-In this example the system has many problems, including a serious problem
-with libreadlineg2. For each package that has unmet dependencies a line
-is printed out indicating the package with the problem and the dependencies
-that are unmet. A short explanation of why the package has a dependency
-problem is also included.
-
-<p>
-There are two ways a system can get into a broken state like this. The
-first is caused by <prgn>dpkg</> missing some subtle relationships between 
-packages when performing upgrades. <footnote>APT however considers all known 
-dependencies and attempts to prevent broken packages</footnote>. The second is 
-if a package installation fails during an operation. In this situation a 
-package may have been unpacked without its dependents being installed.
-
-<p>
-The second situation is much less serious than the first because APT places
-certain constraints on the order that packages are installed. In both cases
-supplying the <tt>-f</> option to <prgn>apt-get</> will cause APT to deduce a
-possible solution to the problem and then continue on. The APT <prgn>dselect</> 
-method always supplies the <tt>-f</> option to allow for easy continuation
-of failed maintainer scripts.
-
-<p>
-However, if the <tt>-f</> option is used to correct a seriously broken system
-caused by the first case then it is possible that it will either fail 
-immediately or the installation sequence will fail. In either case it is
-necessary to manually use dpkg (possibly with forcing options) to correct
-the situation enough to allow APT to proceed.
-</sect>
-
-<!-- ===================================================================== -->
-<sect>The Status Report
-
-<p>
-Before proceeding <prgn>apt-get</> will present a report on what will happen.
-Generally the report reflects the type of operation being performed but there
-are several common elements. In all cases the lists reflect the final state
-of things, taking into account the <tt>-f</> option and any other relevant
-activities to the command being executed.
-
-<sect1>The Extra Package list
-<p>
-<example>
-The following extra packages will be installed:
-  libdbd-mysql-perl xlib6 zlib1 xzx libreadline2 libdbd-msql-perl
-  mailpgp xdpkg fileutils pinepgp zlib1g xlib6g perl-base
-  bin86 libgdbm1 libgdbmg1 quake-lib gmp2 bcc xbuffy
-  squake pgp-i python-base debmake ldso perl libreadlineg2
-  ssh
-</example>
-
-<p>
-The Extra Package list shows all of the packages that will be installed 
-or upgraded in excess of the ones mentioned on the command line. It is
-only generated for an <tt>install</> command. The listed packages are
-often the result of an Auto Install.
-</sect1>
-
-<sect1>The Packages to Remove
-<p>
-<example>
-The following packages will be REMOVED:
-  xlib6-dev xpat2 tk40-dev xkeycaps xbattle xonix
-  xdaliclock tk40 tk41 xforms0.86 ghostview xloadimage xcolorsel
-  xadmin xboard perl-debug tkined xtetris libreadline2-dev perl-suid
-  nas xpilot xfig 
-</example>
-
-<p>
-The Packages to Remove list shows all of the packages that will be
-removed from the system. It can be shown for any of the operations and 
-should be given a careful inspection to ensure nothing important is to 
-be taken off. The <tt>-f</> option is especially good at generating packages
-to remove so extreme care should be used in that case. The list may contain
-packages that are going to be removed because they are only 
-partially installed, possibly due to an aborted installation.
-</sect1>
-
-<sect1>The New Packages list
-<p>
-<example>
-The following NEW packages will installed:
-  zlib1g xlib6g perl-base libgdbmg1 quake-lib gmp2 pgp-i python-base
-</example>
-
-<p>
-The New Packages list is simply a reminder of what will happen. The packages
-listed are not presently installed in the system but will be when APT is done.
-</sect1>
-
-<sect1>The Kept Back list
-<p>
-<example>
-The following packages have been kept back
-  compface man-db tetex-base msql libpaper svgalib1
-  gs snmp arena lynx xpat2 groff xscreensaver
-</example>
-
-<p>
-Whenever the whole system is being upgraded there is the possibility that
-new versions of packages cannot be installed because they require new things
-or conflict with already installed things. In this case the package will 
-appear in the Kept Back list. The best way to convince packages listed
-there to install is with <tt>apt-get install</> or by using <prgn>dselect</>
-to resolve their problems.
-</sect1>
-
-<sect1>Held Packages warning
-<p>
-<example>
-The following held packages will be changed:
-  cvs 
-</example>
-
-<p>
-Sometimes you can ask APT to install a package that is on hold, in such a 
-case it prints out a warning that the held package is going to be
-changed. This should only happen during dist-upgrade or install.
-</sect1>
-
-<sect1>Final summary
-<p>
-Finally, APT will print out a summary of all the changes that will occur.
-
-<p>
-<example>
-206 packages upgraded, 8 newly installed, 23 to remove and 51 not upgraded.
-12 packages not fully installed or removed.
-Need to get 65.7M/66.7M of archives. After unpacking 26.5M will be used. 
-</example>
-
-<p>
-The first line of the summary simply is a reduced version of all of the
-lists and includes the number of upgrades - that is packages already 
-installed that have new versions available. The second line indicates the
-number of poorly configured packages, possibly the result of an aborted
-installation. The final line shows the space requirements that the
-installation needs. The first pair of numbers refer to the size of
-the archive files. The first number indicates the number of bytes that
-must be fetched from remote locations and the second indicates the
-total size of all the archives required. The next number indicates the
-size difference between the presently installed packages and the newly
-installed packages. It is roughly equivalent to the space required in 
-/usr after everything is done. If a large number of packages are being
-removed then the value may indicate the amount of space that will be
-freed.
-
-<p>
-Some other reports can be generated by using the -u option to show packages
-to upgrade, they are similar to the previous examples.
-</sect>
-
-<!-- ===================================================================== -->
-<sect>The Status Display
-<p>
-During the download of archives and package files APT prints out a series of
-status messages.
-
-<p>
-<example>
-# apt-get update
-Get:1 http://ftp.de.debian.org/debian-non-US/ stable/non-US/ Packages
-Get:2 http://llug.sep.bnl.gov/debian/ testing/contrib Packages
-Hit http://llug.sep.bnl.gov/debian/ testing/main Packages
-Get:4 http://ftp.de.debian.org/debian-non-US/ unstable/binary-i386/ Packages
-Get:5 http://llug.sep.bnl.gov/debian/ testing/non-free Packages
-11% [5 testing/non-free `Waiting for file' 0/32.1k 0%] 2203b/s 1m52s
-</example>
-
-<p>
-The lines starting with <em>Get</> are printed out when APT begins to fetch 
-a file while the last line indicates the progress of the download. The first 
-percent  value on the progress line indicates the total percent done of all 
-files. Unfortunately since the size of the Package files is unknown 
-<tt>apt-get update</> estimates the percent done which causes some 
-inaccuracies.
-
-<p>
-The next section of the status line is repeated once for each download thread
-and indicates the operation being performed and some useful information
-about what is happening. Sometimes this section will simply read <em>Forking</>
-which means the OS is loading the download module. The first word after the [
-is the fetch number as shown on the history lines. The next word
-is the short form name of the object being downloaded. For archives it will
-contain the name of the package that is being fetched.
-
-<p>
-Inside of the single quote is an informative string indicating the progress
-of the negotiation phase of the download. Typically it progresses from 
-<em>Connecting</> to <em>Waiting for file</> to <em>Downloading</> or
-<em>Resuming</>. The final value is the number of bytes downloaded from the
-remote site. Once the download begins this is represented as <tt>102/10.2k</>
-indicating that 102 bytes have been fetched and 10.2 kilobytes is expected.
-The total size is always shown in 4 figure notation to preserve space. After
-the size display is a percent meter for the file itself.
-The second last element is the instantaneous average speed. This values is 
-updated every 5 seconds and reflects the rate of data transfer for that 
-period. Finally is shown the estimated transfer time. This is updated
-regularly and reflects the time to complete everything at the shown 
-transfer rate.
-
-<p> 
-The status display updates every half second to provide a constant feedback 
-on the download progress while the Get lines scroll back whenever a new
-file is started. Since the status display is constantly updated it is
-unsuitable for logging to a file, use the <tt>-q</> option to remove the
-status display.
-</sect>
-
-<!-- ===================================================================== -->
-<sect>Dpkg
-
-<p>
-APT uses <prgn>dpkg</> for installing the archives and will switch
-over to the <prgn>dpkg</> interface once downloading is completed.
-<prgn>dpkg</> will also ask a number of questions as it processes the packages
-and the packages themselves may also ask several questions. Before each 
-question there is usually a description of what it is asking and the
-questions are too varied to discuss completely here.
-</sect>
-
-</chapt>
-                                                                  <!-- }}} -->
-
-</book>