Final draft

Author: jgg
Date: 1998-12-06 04:36:25 GMT
Final draft

5 files changed, 205 insertions, 17 deletions

diff --git a/doc/apt-cache.8.yo b/doc/apt-cache.8.yo
index 61248a8c0..2bd4ab031 100644
--- a/doc/apt-cache.8.yo
+++ b/doc/apt-cache.8.yo
@@ -138,6 +138,10 @@ Do not use it.
 enddit()
 
 manpageoptions()
+All command line options may be set using the configuration file, the
+descriptions indicate the configuration option to set. For boolean
+options you can override the config file by using something like bf(-f-),
+bf(--no-f), bf(-f=no) or several other variations.
 
 startdit()
 dit(bf(-h, --help))
@@ -146,21 +150,25 @@ Show a short usage summary.
 dit(bf(-p --pkg-cache))
 Select the file to store the package cache. The package cache is the primary
 cache used by all operations.
+See bf(Dir::Cache::pkgcache).
 
 dit(bf(-s --src-cache))
 Select the file to store the source cache. The source is used only by
 bf(gencaches) and it stores a parsed version of the package information from
 remote sources. When building the package cache the source cache is used
 to advoid reparsing all of the package files.
+See bf(Dir::Cache::srcpkgcache).
 
 dit(bf(-q, --quiet))
 Quiet; produces output suitable for logging, omitting progress indicators.
 More qs will produce more quite up to a maximum of 2. You can also use
 bf(-q=#) to set the quiet level, overriding the configuration file.
+See bf(quiet).
 
 dit(bf(-i --important))
 Print only important deps; for use with unmet causes only em(Depends) and 
 em(Pre-Depends) relations to be printed.
+See bf(APT::Cache::Important).
 
 dit(bf(-c, --config-file))
 Configuration File; Specify a configuration file to use. bf(apt-get) will
@@ -186,10 +194,9 @@ itemize(
 )
 
 manpageseealso()
-apt-get (8),
-dpkg (8),
-dselect (8),
-sources.list (5)
+apt-get(8),
+sources.list(5),
+apt.conf(5)
 
 manpagediagnostics()
 apt-cache returns zero on normal operation, decimal 100 on error.
diff --git a/doc/apt-cdrom.8.yo b/doc/apt-cdrom.8.yo
index 27af39f79..5c1f13b6f 100644
--- a/doc/apt-cdrom.8.yo
+++ b/doc/apt-cdrom.8.yo
@@ -34,6 +34,10 @@ maintains a database of these IDs in bf(/var/state/apt/cdroms.list)
 enddit()
 
 manpageoptions()
+All command line options may be set using the configuration file, the
+descriptions indicate the configuration option to set. For boolean
+options you can override the config file by using something like bf(-f-),
+bf(--no-f), bf(-f=no) or several other variations.
 
 startdit()
 dit(bf(-h, --help))
@@ -41,24 +45,29 @@ Show a short usage summary.
 
 dit(bf(-d --cdrom))
 Mount point; specify the location to mount the cdrom. This mount point must
-be listed in bf(/etc/fstab) and propely configured.
+be listed in bf(/etc/fstab) and propely configured. 
+See bf(Acquire::cdrom::mount).
 
 dit(bf(-r --rename))
 Rename a disc; change the label of a disk or override the disks given label.
 This option will cause bf(apt-cdrom) to prompt for a new label
+See bf(APT::CDROM::Rename).
 
 dit(bf(-m, --no-mount))
 No mounting; prevent bf(apt-cdrom) from mounting and unmounting the mount
 point.
+See bf(APT::CDROM::NoMount).
 
 dit(bf(-f, --fast))
 Fast Copy; Assume the package files are valid and do not check every package.
 This option should be used only if bf(apt-cdrom) has been run on this disc
 before and did not detect any errors.
+See bf(APT::CDROM::Fast).
  
 dit(bf(-n --just-print, --recon, --no-act))
 No Changes; Do not change the sources.list and do not write package files. 
 Everything is still checked however.
+See bf(APT::CDROM::NoAct).
 
 dit(bf(-c, --config-file))
 Configuration File; Specify a configuration file to use. bf(apt-get) will
@@ -87,8 +96,8 @@ itemize(
 )
 
 manpageseealso()
-apt-get (8),
-sources.list (5),
+apt-get(8),
+sources.list(5),
 apt.conf(5)
 
 manpagediagnostics()
diff --git a/doc/apt-get.8.yo b/doc/apt-get.8.yo
index f77795a7b..604051312 100644
--- a/doc/apt-get.8.yo
+++ b/doc/apt-get.8.yo
@@ -92,10 +92,15 @@ from time to time to free up disk space.
 enddit()
 
 manpageoptions()
+All command line options may be set using the configuration file, the
+descriptions indicate the configuration option to set. For boolean
+options you can override the config file by using something like bf(-f-),
+bf(--no-f), bf(-f=no) or several other variations.
 
 startdit()
 dit(bf(-d, --download-only))
 Download only; package files are only retrieved, not unpacked or installed.
+See bf(APT::Get::Download-Only).
 
 dit(bf(-f, --fix-broken))
 Fix; attempt to correct a system with broken dependencies in            
@@ -106,7 +111,7 @@ exist on a system. It is possible that a system's dependency structure
 can be so corrupt as to require manual intervention (which usually
 means using dselect or dpkg --remove to eliminate some of the offending 
 packages). Use of this option together with -m may produce an error in
-some situations.
+some situations. See bf(APT::Get::Fix-Broken).
 
 dit(bf(-h, --help))
 Help; display a helpful usage message and exits.
@@ -115,42 +120,43 @@ dit(bf(-m, --ignore-missing))
 Ignore missing packages; If packages cannot be retrieved or fail the    
 integrity check after retrieval (corrupted package files), hold back    
 those packages and handle the result. Use of this option together with  
--f is discouraged.
+-f is discouraged. See bf(ignore-missing).
 
 dit(bf(-q, --quiet))
 Quiet; produces output suitable for logging, omitting progress indicators.
 More qs will produce more quite up to a maximum of 2. You can also use
 bf(-q=#) to set the quiet level, overriding the configuration file.
+See bf(quiet)
 
 dit(bf(-s, --simulate, --just-print, --dry-run, --recon, --no-act))
 No action; perform a simulation of events that would occur but do not
-actually change the system.
+actually change the system. See bf(APT::Get::Simulate).
 
 dit(bf(-y, --yes, --assume-yes))
 Automatic yes to prompts; assume "yes" as answer to all prompts and run
 non-interactively. If an undesireable situation, such as changing a held
 package or removing an essential package occures then bf(apt-get) will
-abort.
+abort. See bf(APT::Get::Assume-Yes).
 
 dit(bf(-u, --show-upgraded))
 Show upgraded packages; Print out a list of all packages that are to be
-upgraded.
+upgraded. See bf(APT::Get::Show-Upgraded).
 
 dit(bf(--ignore-hold))
 Ignore package Holds; This causes bf(apt-get) to ignore a hold placed on 
 a package. This may be usefull in conjunction with bf(dist-upgrade) to
-override a large number of undesired holds.
+override a large number of undesired holds. See bf(APT::Ingore-Hold).
 
 dit(bf(--no-upgrade))
 Do not upgrade packages; When used in conjunction with bf(install)
 bf(no-upgrade) will prevent packages listed from being upgraded if they
-are already installed.
+are already installed. See bf(APT::Get::no-upgrade).
 
 dit(bf(--force-yes))
 Force yes; This is a dangerous option that will cause apt to continue without
 prompting if it is doing something potentially harmfull. It should not be used
 except in very special situations. Using bf(force-yes) can potentially destroy
-your system!
+your system! See bf(APT::Get::force-yes).
 
 dit(bf(-c, --config-file))
 Configuration File; Specify a configuration file to use. bf(apt-get) will
@@ -186,6 +192,7 @@ apt-cache(8),
 dpkg(8),
 dselect(8),
 sources.list(5),
+apt.conf(5),
 The APT Users Guide in /usr/doc/apt/
 
 manpagediagnostics()
diff --git a/doc/apt.conf.5.yo b/doc/apt.conf.5.yo
new file mode 100644
index 000000000..5c4a9d429
--- /dev/null
+++ b/doc/apt.conf.5.yo
@@ -0,0 +1,153 @@
+mailto(apt@packages.debian.org)
+manpage(apt.conf)(5)(5 Dec 1998)(apt)()
+manpagename(apt.conf)(configuration file for APT)
+
+manpagedescription()
+bf(apt.conf) is the main configuration file for the APT suite of
+tools, all tools make use of the configuration file and a common command line
+parser to provide a uniform environment. When an APT tool starts up it will
+read bf(/etc/apt/apt.conf), then read the configuration specified by the
+bf($APT_CONFIG) environment variable and then finally apply the command line
+options to override the configuration directives, possibly loading more 
+config files.
+
+The configuration file is organized in a tree with options organized into
+functional groups. Option specification is given with a double colon
+notation, for instance em(APT::Get::Assume-Yes) is an option within the
+APT tool group, for the Get tool. Options do not inherit from their parent
+groups.
+
+Syntacticly the configuration language is modeled after what the ISC tools
+such as bind and dhcp use. Each line is of the form
+quote(APT::Get::Assume-Yes "true";) The trailing semicolon is required and
+the quotes are optional. A new em(scope) can be opened with curly braces,
+like: 
+verb(APT {
+  Get {
+    Assume-Yes "true";
+    Fix-Broken "true";
+  };
+};
+)
+with newlines placed to make
+it more readable. In general the sample configuration file in
+em(/usr/doc/apt/examples/apt.conf) is a good guide for how it should look.
+
+manpagesection(The APT Group)
+This group of options controls general APT behavoir as well as holding the
+options for all of the tools.
+
+startdit()
+dit(bf(Architecture))
+System Architecture; sets the architecture to use when fetching files and
+parsing package lists. The internal default is the architecture apt was 
+compiled for.
+
+dit(bf(Ignore-Hold))
+Ignore Held packages; This global options causes the problem resolver to
+ignore held packages in its decision making. 
+
+dit(bf(Get))
+The Get subsection controls the bf(apt-get(8)) tool, please see its
+documentation for more information about the options here.
+
+dit(bf(Cache))
+The Cache subsection controls the bf(apt-cache(8)) tool, please see it
+sdocumentation for more information about the options here.
+
+dit(bf(CDROM))
+The CDROM subsection controls the bf(apt-cdrom(8)) tool, please see it
+sdocumentation for more information about the options here.
+
+enddit()
+
+manpagesection(The Acquire Group)
+The bf(Acquire) group of options controls the download of packages and the 
+URI handlers. 
+
+startdit()
+dit(bf(Queue-Mode))
+Queuing mode; bf(Queue-Mode) can be one of bf(host) or bf(access) which 
+determins how APT parallelizesoutgoing connections. bf(host) means that
+one connection per target host will be opened, bf(access) means that one
+connection per URI type will be opened.
+
+dit(bf(http))
+HTTP URIs; http::Proxy is the default http proxy to use. It is in the standard
+form of em(http://[[user][:pass]@]host[:port]/). Per host proxies can also
+be specified by using the form http::Proxy::<host> with the special keyword
+em(DIRECT) meaning to use no proxies. The em($http_proxy) environment variable
+will override all settings.
+
+dit(bf(cdrom))
+CDROM URIs; the only setting for CDROM URIs is the mount point, cdrom::Mount
+which must be the mount point for the CDROM drive as specified in /etc/fstab.
+
+enddit()
+
+manpagesection(Directories)
+The bf(Dir::State) section has directories that pertain to local state
+information. bf(lists) is the directory to place downloaded package lists
+in and bf(status) is the name of the dpkg status file. bf(Dir::State)
+contains the default directory to prefix on all sub items if they do not
+start with em(/) or em(./). bf(xstatus) and bf(userstatus) are for future
+use.
+
+bf(Dir::Cache) contains locations pertaining to local cache information, such
+as the two package caches bf(srcpkgcache) and bf(pkgcache) as well as the
+location to place downloaded archives, bf(Dir::Cache::archives). Like 
+bf(Dir::State) the default directory is contained in bf(Dir::Cache)
+
+bf(Dir::Etc) contains the location of configuration files, bd(sourcelist)
+gives the location of the sourcelist and bf(main) is the default configuration
+file (setting has no effect)
+
+Binary programs are pointed to by bf(Dir::Bin). bf(methods) specifies the
+location of the method handlers and bf(gzip), bf(dpkg), bf(apt-get), and
+bf(apt-cache) specify the location of the respective programs.
+
+manpagesection(APT in DSelect)
+When APT is used as a bf(dselect(8)) method several configuration directives
+control the default behavoir. These are in the bf(DSelect) section.
+
+startdit()
+dit(bf(Clean))
+Cache Clean mode; this value may be one of always, auto, prompt and never.
+Currently always and auto are identical but their meanings may diverge in
+future to have auto only clean useless archives and always clean all archives.
+
+dit(bf(Options))
+The contents of this variable is passed to bf(apt-get(8)) as command line
+options when it is run for the install phase.
+
+dit(bf(UpdateOptions))
+The contents of this variable is passed to bf(apt-get(8)) as command line
+options when it is run for the update phase.
+
+dit(bf(PromptAfterUpdate))
+If true the [U]pdate operation in dselect will always prompt to continue. 
+The default is to prompt only on error.
+enddit()
+
+manpagesection(Debug Options)
+Most of the options in the bf(debug) section are not interesting to the
+normal user, however bf(Debug::pkgProblemResolver) shows interesting
+output about the decisions dist-upgrade makes. bf(Debug::NoLocking)
+disables file locking so apt can do some operations as non-root and
+bf(Debug::pkgDPkgPM) will print out the command line for each dpkg invokation.
+
+manpagesection(EXAMPLES)
+bf(/usr/doc/apt/examples/apt.conf) contains a sample configuration file
+showing the default values for all possible options.
+
+manpageseealso()
+apt-cache (8),
+apt.conf (5)
+
+manpagebugs()
+See http://www.debian.org/Bugs/db/pa/lapt.html.  If you wish to report a
+bug in bf(apt-get), please see bf(/usr/doc/debian/bug-reporting.txt)
+or the bf(bug(1)) command.
+
+manpageauthor()
+apt-get was written by the APT team <apt@packages.debian.org>.
diff --git a/doc/examples/apt.conf b/doc/examples/apt.conf
index 3fbf93efe..18292f6f6 100644
--- a/doc/examples/apt.conf
+++ b/doc/examples/apt.conf
@@ -1,4 +1,4 @@
-// $Id: apt.conf,v 1.16 1998/11/28 00:03:09 jgg Exp $
+// $Id: apt.conf,v 1.17 1998/12/06 04:36:33 jgg Exp $
 /* This file is an index of all APT configuration directives. It should
    NOT actually be used as a real config file, though it is a completely
    valid file.
@@ -28,8 +28,20 @@ APT {
      Fix-Broken "false";  
      Fix-Missing "false";     
      Show-Upgraded "false";
+     No-Upgrade "false";
+  };
+
+  Cache {
+     Important "false";
   };
   
+  CDROM {
+     Rename "false";
+     NoMount "false";
+     Fast "false";
+     NoAct "false";
+  };
+
   // Some general options
   Ingore-Hold "false";
 };
@@ -79,7 +91,7 @@ Dir
   
   // Locations of binaries
   Bin {
-     methods "/home/jgg/work/apt/build/bin/methods/";
+     methods "/usr/lib/apt/methods/";
      gzip "/bin/gzip";
      dpkg "/usr/bin/dpkg";
      apt-get "/usr/bin/apt-get";