merged from lp:~donkult/apt/sid

[apt.git] / doc / files.sgml

diff --git a/doc/files.sgml b/doc/files.sgml
index 16367b5500be753237aca0c31456e09dcca80627..2293e204af70d0b76e663af9b35a6b26525b22f2 100644 (file)
--- a/doc/files.sgml
+++ b/doc/files.sgml
@@ -1,10 +1,10 @@
-<!doctype debiandoc system>

 <!-- -*- mode: sgml; mode: fold -*- -->
 <!-- -*- mode: sgml; mode: fold -*- -->

+<!doctype debiandoc  PUBLIC  "-//DebianDoc//DTD DebianDoc//EN">

 <book>
 <title>APT Files</title>
 
 <author>Jason Gunthorpe <email>jgg@debian.org</email></author>
 <book>
 <title>APT Files</title>
 
 <author>Jason Gunthorpe <email>jgg@debian.org</email></author>

-<version>$Id: files.sgml,v 1.5 1998/12/31 05:45:26 jgg Exp $</version>
+<version>$Id: files.sgml,v 1.12 2003/04/26 23:26:13 doogie Exp $</version>

 
 <abstract>
 This document describes the complete implementation and format of the 
 
 <abstract>
 This document describes the complete implementation and format of the 


@@ -13,7 +13,7 @@ views the Debian archive.
 </abstract>
 
 <copyright>
 </abstract>
 
 <copyright>

-Copyright &copy; Jason Gunthorpe, 1998.
+Copyright &copy; Jason Gunthorpe, 1998-1999.

 <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
 <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


@@ -22,7 +22,7 @@ option) any later version.
 
 <p>
 For more details, on Debian GNU/Linux systems, see the file
 
 <p>
 For more details, on Debian GNU/Linux systems, see the file

-/usr/doc/copyright/GPL for the full license.
+/usr/share/common-licenses/GPL for the full license.

 </copyright>
 
 <toc sect>
 </copyright>
 
 <toc sect>


@@ -41,7 +41,7 @@ multiple package files.
 <p>
 The var directory structure is as follows:
 <example>
 <p>
 The var directory structure is as follows:
 <example>

-  /var/state/apt/
+  /var/lib/apt/

                  lists/
                       partial/
                  xstatus
                  lists/
                       partial/
                  xstatus


@@ -66,7 +66,7 @@ The var directory structure is as follows:
 </example>
 
 <p>
 </example>
 
 <p>

-As is specified in the FHS 2.0 /var/state/apt is used for application 
+As is specified in the FHS 2.1 /var/lib/apt is used for application 

 data that is not expected to be user modified. /var/cache/apt is used
 for regeneratable data and is where the package cache and downloaded .debs
 go.
 data that is not expected to be user modified. /var/cache/apt is used
 for regeneratable data and is where the package cache and downloaded .debs
 go.


@@ -97,11 +97,11 @@ which indicates a standard debian archive with a dists dir.
    <p>
    The <em>deb</em> type is to be a typical two level debian distributions,
    dist/<var>distribution</var>/<var>component</var>. Typically distribution
    <p>
    The <em>deb</em> type is to be a typical two level debian distributions,
    dist/<var>distribution</var>/<var>component</var>. Typically distribution

-   is one of stable, unstable or frozen while component is one of main, 
+   is one of stable, unstable or testing while component is one of main, 

    contrib, non-free or non-us. The format for the deb line is as follows:
 
    <p>
    contrib, non-free or non-us. The format for the deb line is as follows:
 
    <p>

-   deb <var>uri</var> <var>distribution</var> <var>compontent</var> 
+   deb <var>uri</var> <var>distribution</var> <var>component</var> 

    [<var>component</var> ...]
 
    <p>
    [<var>component</var> ...]
 
    <p>


@@ -116,7 +116,7 @@ which indicates a standard debian archive with a dists dir.
    necessary to list a number of deb lines for the same URI. APT will
    sort the URI list after it has generated a complete set to allow 
    connection reuse. It is important to order things in the sourcelist
    necessary to list a number of deb lines for the same URI. APT will
    sort the URI list after it has generated a complete set to allow 
    connection reuse. It is important to order things in the sourcelist

-   from most prefered to least prefered (fastest to slowest).
+   from most preferred to least preferred (fastest to slowest).

 </sect1>
 
 <sect1>URI specification
 </sect1>
 
 <sect1>URI specification


@@ -125,12 +125,12 @@ URIs in the source list support a large number of access schemes.
 
 <taglist>
 <tag>cdrom<item>
 
 <taglist>
 <tag>cdrom<item>

-   The cdrom scheme is special in that If Modifed Since queries are never
+   The cdrom scheme is special in that If Modified Since queries are never

    performed and that APT knows how to match a cdrom to the name it
    was given when first inserted. APT also knows all of the possible 
    mount points the cdrom drives and that the user should be prompted
    to insert a CD if it cannot be found. The path is relative to an 
    performed and that APT knows how to match a cdrom to the name it
    was given when first inserted. APT also knows all of the possible 
    mount points the cdrom drives and that the user should be prompted
    to insert a CD if it cannot be found. The path is relative to an 

-   arbitary mount point (of APT's choosing) and must not start with a 
+   arbitrary mount point (of APT's choosing) and must not start with a 

    slash. The first pathname component is the given name and is purely
    descriptive and of the users choice. However, if a file in the root of 
    the cdrom is called '.disk/info' its contents will be used instead of 
    slash. The first pathname component is the given name and is purely
    descriptive and of the users choice. However, if a file in the root of 
    the cdrom is called '.disk/info' its contents will be used instead of 


@@ -140,7 +140,7 @@ URIs in the source list support a large number of access schemes.
    </example>
 
 <tag>http<item>
    </example>
 
 <tag>http<item>

-   This scheme specifies a HTTP server for the debian archive. HTTP is prefered
+   This scheme specifies a HTTP server for the debian archive. HTTP is preferred

    over FTP because If Modified Since queries against the Package file are
    possible as well as deep pipelining and resume capabilities.
    <example>
    over FTP because If Modified Since queries against the Package file are
    possible as well as deep pipelining and resume capabilities.
    <example>


@@ -155,8 +155,8 @@ URIs in the source list support a large number of access schemes.
    </example>
 
 <tag>file<item>
    </example>
 
 <tag>file<item>

-   The file scheme allows an arbitary directory in the file system to be 
-   considered as a debian archive. This is usefull for NFS mounts and 
+   The file scheme allows an arbitrary directory in the file system to be 
+   considered as a debian archive. This is useful for NFS mounts and 

    local mirrors/archives.
    <example>
    file:/var/debian
    local mirrors/archives.
    <example>
    file:/var/debian


@@ -173,20 +173,20 @@ URIs in the source list support a large number of access schemes.
 
 <sect1>Hashing the URI
 <p>
 
 <sect1>Hashing the URI
 <p>

-All permanent information aquired from any of the sources is stored in the
+All permanent information acquired from any of the sources is stored in the

 lists directory. Thus, there must be a way to relate the filename in the
 lists directory to a line in the sourcelist. To simplify things this is
 done by quoting the URI and treating _'s as quoteable characters and
 converting / to _. The URI spec says this is done by converting a 
 sensitive character into %xx where xx is the hexadecimal representation 
 lists directory. Thus, there must be a way to relate the filename in the
 lists directory to a line in the sourcelist. To simplify things this is
 done by quoting the URI and treating _'s as quoteable characters and
 converting / to _. The URI spec says this is done by converting a 
 sensitive character into %xx where xx is the hexadecimal representation 

-from the ascii character set. Examples:
+from the ASCII character set. Examples:

 
 <example>
 http://www.debian.org/archive/dists/stable/binary-i386/Packages 
 
 <example>
 http://www.debian.org/archive/dists/stable/binary-i386/Packages 

-/var/state/apt/lists/www.debian.org_archive_dists_stable_binary-i386_Packages
+/var/lib/apt/lists/www.debian.org_archive_dists_stable_binary-i386_Packages

 
 cdrom:Debian 1.3/debian/Packages
 
 cdrom:Debian 1.3/debian/Packages

-/var/state/apt/info/Debian%201.3_debian_Packages
+/var/lib/apt/info/Debian%201.3_debian_Packages

 </example>
 
 <p> 
 </example>
 
 <p> 


@@ -209,9 +209,9 @@ here as well.
 The extra status file serves the same purpose as the normal dpkg status file
 (/var/lib/dpkg/status) except that it stores information unique to apt.
 This includes the autoflag, target distribution and version and any other
 The extra status file serves the same purpose as the normal dpkg status file
 (/var/lib/dpkg/status) except that it stores information unique to apt.
 This includes the autoflag, target distribution and version and any other

-uniqe features that come up over time. It duplicates nothing from the normal
+unique features that come up over time. It duplicates nothing from the normal

 dpkg status file.  Please see other APT documentation for a discussion
 dpkg status file.  Please see other APT documentation for a discussion

-of the exact internal behavior of these fields. The Package field is
+of the exact internal behaviour of these fields. The Package field is

 placed directly before the new fields to indicate which package they
 apply to. The new fields are as follows:
 
 placed directly before the new fields to indicate which package they
 apply to. The new fields are as follows:
 


@@ -222,7 +222,7 @@ apply to. The new fields are as follows:
 
 <tag>X-TargetDist<item>
    The TargetDist item indicates which distribution versions are offered for
 
 <tag>X-TargetDist<item>
    The TargetDist item indicates which distribution versions are offered for

-   installation from. It should be stable, unstable or frozen.
+   installation from. It should be stable, unstable or testing.

    
 <tag>X-TargetVersion<item>
    The target version item is set if the user selects a specific version, it
    
 <tag>X-TargetVersion<item>
    The target version item is set if the user selects a specific version, it


@@ -251,16 +251,20 @@ change to use a prebuilt version for greater speed.
 <p>
 The archives directory is where all downloaded .deb archives go. When the
 file transfer is initiated the deb is placed in partial. Once the file
 <p>
 The archives directory is where all downloaded .deb archives go. When the
 file transfer is initiated the deb is placed in partial. Once the file

-is fully downloaded and its MD5 hash and size are verifitied it is moved
+is fully downloaded and its MD5 hash and size are verified it is moved

 from partial into archives/. Any files found in archives/ can be assumed 
 to be verified.
 
 <p>
 from partial into archives/. Any files found in archives/ can be assumed 
 to be verified.
 
 <p>

-No dirctory structure is transfered from the receiving site and all .deb
+No directory structure is transfered from the receiving site and all .deb

 file names conform to debian conventions. No short (msdos) filename should
 be placed in archives. If the need arises .debs should be unpacked, scanned
 and renamed to their correct internal names. This is mostly to prevent
 file names conform to debian conventions. No short (msdos) filename should
 be placed in archives. If the need arises .debs should be unpacked, scanned
 and renamed to their correct internal names. This is mostly to prevent

-file name conflicts but other programs may depend on this if convenient.
+file name conflicts but other programs may depend on this if convenient. 
+A conforming .deb is one of the form, name_version_arch.deb. Our archive
+scripts do not handle epochs, but they are necessary and should be re-inserted.
+If necessary _'s and :'s in the fields should be quoted using the % convention.
+It must be possible to extract all 3 fields by examining the file name.

 Downloaded .debs must be found in one of the package lists with an exact
 name + version match..
 </sect>
 Downloaded .debs must be found in one of the package lists with an exact
 name + version match..
 </sect>


@@ -286,7 +290,7 @@ format and style mirror the Package file.
 <taglist>
 <tag>Site<item>
 This is the proper host name of the site. It should not be a host within
 <taglist>
 <tag>Site<item>
 This is the proper host name of the site. It should not be a host within

-debian.org and generally cnames should be advoided here.
+debian.org and generally cnames should be avoided here.

 
 <tag>Aliases<item>
 These list any commonly used aliases for the site. This field is used to make
 
 <tag>Aliases<item>
 These list any commonly used aliases for the site. This field is used to make


@@ -301,7 +305,7 @@ other mirrors are leaf.
 The Archive field gives the path(s) to the debian archive. [access] 
 specifies the access method and may be one of ftp, http, rsync, nfs, or
 smb. For many of the types it is possible to prefix the path with :###
 The Archive field gives the path(s) to the debian archive. [access] 
 specifies the access method and may be one of ftp, http, rsync, nfs, or
 smb. For many of the types it is possible to prefix the path with :###

-indicating that an alternate port should be used. Generaly paths
+indicating that an alternate port should be used. Generally paths

 start with a / and end with a /, rsync is an exception in that the
 first directory component is not a path but a label.
 
 start with a / and end with a /, rsync is an exception in that the
 first directory component is not a path but a label.
 


@@ -366,7 +370,7 @@ This is the common name we give our archives, such as <em>stable</> or
 <em>unstable</>.
 
 <tag>Component<item>
 <em>unstable</>.
 
 <tag>Component<item>

-Referes to the sub-component of the archive, <em>main</>, <em>contrib</>
+Refers to the sub-component of the archive, <em>main</>, <em>contrib</>

 etc. Component may be omitted if there are no components for this archive.
 
 <tag>Version<item>
 etc. Component may be omitted if there are no components for this archive.
 
 <tag>Version<item>


@@ -405,7 +409,7 @@ release, 1.3.1r6
 
 <example>
 Archive: stable
 
 <example>
 Archive: stable

-Compontent: main
+Component: main

 Version: 1.3.1r6
 Origin: Debian
 Label: Debian
 Version: 1.3.1r6
 Origin: Debian
 Label: Debian


@@ -425,7 +429,7 @@ NotAutomatic: Yes
 And unstable,
 <example>
 Archive: unstable
 And unstable,
 <example>
 Archive: unstable

-Compontent: main
+Component: main

 Version: 2.1
 Origin: Debian
 Label: Debian
 Version: 2.1
 Origin: Debian
 Label: Debian