dpkg (1.2.12); priority=LOW

  * dpkg --search and --list understand and comment on diversions.
  * dpkg-divert displays diversions more intelligibly.

  * Guidelines are somewhat clearer about descriptions.
  * deb(5) describes new format; old moved to deb-old(5).  (Bug#3435.)
  * deb-control(5) carries a warning about being out of date.

  * Added 1996 to dselect version/copyright.

 -- Ian Jackson <ian@chiark.chu.cam.ac.uk>  Thu, 4 Jul 1996 15:04:49 +0100

debian.Changelog

@@ -1,3 +1,16 @@
+dpkg (1.2.12); priority=LOW
+
+  * dpkg --search and --list understand and comment on diversions.
+  * dpkg-divert displays diversions more intelligibly.
+
+  * Guidelines are somewhat clearer about descriptions.
+  * deb(5) describes new format; old moved to deb-old(5).  (Bug#3435.)
+  * deb-control(5) carries a warning about being out of date.
+
+  * Added 1996 to dselect version/copyright.
+
+ -- Ian Jackson <ian@chiark.chu.cam.ac.uk>  Thu, 4 Jul 1996 15:04:49 +0100
+
 dpkg (1.2.11); priority=MEDIUM
 
   * dselect had dependency bug if installed package newer than avail.

debian.rules

@@ -1,7 +1,7 @@
 #!/usr/bin/make -f
 
 package=dpkg
-version=1.2.11
+version=1.2.12
 
 archi=$(shell dpkg --print-architecture)
 DIR:=$(shell pwd)

doc/Makefile.in

@@ -73,6 +73,7 @@ distclean:
 
 install:	all
 		$(INSTALL_DATA) deb.5 $(man5dir)/deb.$(man5)
+		$(INSTALL_DATA) deb-old.5 $(man5dir)/deb-old.$(man5)
 		$(INSTALL_DATA) deb-control.5 $(man5dir)/deb-control.$(man5)
 		$(INSTALL_DATA) guidelines.info guidelines.info-*[0-9] \
 			$(infodir)/.

doc/deb-control.5

@@ -6,6 +6,8 @@
 deb\-control \- Debian GNU/Linux packages' master control file format
 .SH SYNOPSIS
 control
+.SH WARNING
+.I This manual page is very out of date.
 .SH DESCRIPTION
 Master control file format:
 .LP

doc/deb-old.5

@@ -0,0 +1,55 @@
+.\" Hey, Emacs!  This is an -*- nroff -*- source file.
+.\" Author: Raul Miller, Ian Jackson
+.TH DEB-OLD 5  "1st July 1996" "Debian Project" "Debian GNU/Linux"
+.SH NAME 
+deb-old - Debian GNU/Linux binary package old style format
+.SH SYNOPSIS
+.IB filename .deb
+.SH DESCRIPTION
+Old style Debian binary package format.
+
+The
+.B .deb
+format is the Debian binary package file format.  The format has
+changed since Debian 0.93 and the new format is being phased in.
+
+The old format is described here.  Please see
+.BR deb (5)
+for details of the old format.
+.SH FORMAT
+The file is two lines of format information as ASCII text, followed by
+two concatenated gzipped ustar files.
+
+The first line is the format version number padded to 8 digits, and is
+.B 0.939000
+for all old-format archives.
+
+The second line is a decimal string (without leading zeroes) giving
+the length of the first gzipped tarfile.
+
+Each of these lines is terminated with a single newline character.
+
+The first tarfile contains the control information (see the
+.IR "dpkg Programmer's manual" )
+as a series of ordinary files.  The file
+.B control
+must be present, and contains the core control information.  The files
+in the control tarfile may optionally be in a
+.B DEBIAN
+subdirectory in some very old archives - in this case the
+.B DEBIAN
+subdirectory will be in the control tarfile too, and the control
+tarfile will have only files in that directory.  Optionally the
+control tarfile may contain an entry for
+.RB ` . ',
+that is, the current directory.
+
+The second gzipped tarfile is the filesystem archive, containing
+pathnames relative to the root directory of the system to be installed
+on.  The pathnames do not have leading slashes.
+
+.SH SEE ALSO
+.BR deb (5),
+.BR deb\-control (5),
+.IR "dpkg Programmers' manual" ,
+.BR dpkg\-deb (8)

doc/deb.5

@@ -1,69 +1,85 @@
 .\" Hey, Emacs!  This is an -*- nroff -*- source file.
-.\" Author: Raul Miller
-.TH DEB 8 "29th November 1995" "Debian Project" "Debian GNU/Linux"
+.\" Authors: Raul Miller, Ian Jackson
+.TH DEB 8 "1st July 1996" "Debian Project" "Debian GNU/Linux"
 .SH NAME 
-deb - Debian GNU/Linux package format
+deb - Debian GNU/Linux binary package format
 .SH SYNOPSIS
-.IB <packagename>.deb
+.IB filename .deb
 .SH DESCRIPTION
-Debian archive file format.
-Version 0.93 is implemented as follows:
-.TP
-line 1:
-version number 
-.RB ( 0.93 ...),
-followed by
-.BR newline .
-.TP
-line 2:
-number of characters occupied by control area expressed in decimal,
-followed by 
-.BR newline .
-.TP 
-control area:
-compressed gzipped ustar formatted archive.  Must contain file named
-.BR control .
-May optionally contain files named:
-.BR conffiles ,
-.BR preinst ,
-.BR prerm ,
-.BR postint ,
-.BR postrm .
-.TP 
-files archive area:
-compressed gzipped ustar formatted archive.  [with file structures
-designed to be unpacked in the root directory].
-.SH FILES
-The files represented in the control area have special significance:
-.TP
+The
+.B .deb
+format is the Debian binary package file format.  The format has
+changed since Debian 0.93 and the new format is being phased in.  It
+is understood by dpkg 0.93.76 and later, and is generated by default
+by all versions of dpkg since 1.2.0 and all i386/ELF versions since
+1.1.1elf.
+
+The new format is described here.  Please see
+.BR deb-old (5)
+for details of the old format.
+.SH FORMAT
+The file is an
+.B ar
+archive with a magic number of
+.BR !<arch> .
+Note that many modern versions of
+.B ar
+create archives with different magic numbers.  Archives created in
+this way will not be recognised by
+.BR dpkg\-deb ,
+though these
+.B ar
+programs do understand the magic number used by
+.BR dpkg\-deb .
+
+The first member is named
+.B debian-binary
+and contains a series of lines, separated by newlines.  Currently only
+one line is present, the format version number, which is currently
+.BR 2.0 .
+Programs which read new-format archives should be prepared for the
+minor number to be increased and new lines to be present, and should
+ignore these if this is the case.
+
+If the major number has changed an incompatible change has been made
+and the program should stop; if it has not then the program can safely
+continue, unless it encounters an unexpected member in the archive
+(except at the end), as described below.
+
+The second required member is named
+.B control.tar.gz
+and is a gzipped ustar containing the package control information, as
+a series of plain files, of which the file
 .B control
-see 
-.BR deb-control (5).
-.TP
-.B conffiles
-a line delimited list of "configuration files" which have special
-significance to 
-.BR dpkg (8).
-.TP
-.B preinst
-an executable to be run before unpacking the archived files.
-.TP
-.B prerm
-an executable to be run before removing files from a prior installation.
-.TP
-.B postinst
-an executable to be run after unpacking the archived files.
-.TP
-.B postrm
-an executable to be run after removing files from a prior
-installation.
+is mandatory and contains the core control information.  See the
+.I dpkg Programmers' manual
+for details of these files.  The control tarfile may optionally
+contain an entry for
+.RB ` . ',
+the current directory.
+
+The third and final required member is named
+.B data.tar.gz
+and contains the filesystem archive as a gzipped ustar.
 
-.BUGS
-There is a new package format, which is not documented here.
+These members must occur in this order.  Further members may be
+defined in the future, and will if possible be placed after these
+three.  Current implementations should ignore any additional members
+after
+.BR data.tar.gz .
+Additional members defined in the future which need to be inserted
+before
+.B data.tar.gz
+and which can safely be ignored by older programs will have names
+starting with an underscore
+.RB ` _ '.
 
+New members which cannot safely be ignored will be inserted before
+.B data.tar.gz
+with names starting with something other than underscores, or will
+cause the major version number to be increased.
 .SH SEE ALSO
-.BR deb-control (5),
-.BR dpkg (5),
-.BR dpkg (8),
-.BR dpkg-dep (8),
-.BR dselect (8).
+.BR deb (5),
+.BR deb\-control (5),
+.IR "dpkg Programmers' manual" ,
+.BR dpkg\-deb (8)

doc/guidelines.texi

@@ -1239,6 +1239,8 @@ Description: <single line synopsis>
  <extended description over several lines>
 @end smallexample
 
+Every package should have an extended description.
+
 The extended description has several kinds of line:
 
 @itemize @bullet
@@ -1300,6 +1302,13 @@ The extended description should describe what the package does and how
 it relates to the rest of the system (in terms of, for example, which
 subsystem it is which part of).
 
+The blurb that comes with a program in its announcements and/or
+@file{README} files is rarely suitable for use in a description field.
+It is usually aimed at people who are already in the community where the
+package is used.  The @code{Description} field needs to make sense to
+anyone, even people who have no idea about any of the things the package
+deals with.
+
 @item
 Put important information first, both in the synopis and extended
 description.  Sometimes only the first part of the synopsis or of the

dselect/main.cc

@@ -78,7 +78,7 @@ static const char programdesc[]=
       "Debian Linux `" DSELECT "' package handling frontend.";
 
 static const char copyrightstring[]=
-      "Version " DPKG_VERSION_ARCH ".  Copyright (C) 1994,1995 Ian Jackson.   This is\n"
+      "Version " DPKG_VERSION_ARCH ".  Copyright (C) 1994-1996 Ian Jackson.   This is\n"
       "free software; see the GNU General Public Licence version 2 or later for\n"
       "copying conditions.  There is NO warranty.  See dselect --licence for details.\n";
 

main/enquiry.c

@@ -305,6 +305,21 @@ static int searchoutput(struct filenamenode *namenode) {
   int found, i;
   struct filepackages *packageslump;
 
+  if (namenode->divert) {
+    for (i=0; i<2; i++) {
+      if (namenode->divert->pkg) printf("diversion by %s",namenode->divert->pkg->name);
+      else printf("local diversion");
+      printf(" %s: %s\n", i ? "to" : "from",
+             i ?
+             (namenode->divert->useinstead
+              ? namenode->divert->useinstead->name
+              : namenode->name)
+             :
+             (namenode->divert->camefrom
+              ? namenode->divert->camefrom->name
+              : namenode->name));
+    }
+  }
   found= 0;
   for (packageslump= namenode->packages;
        packageslump;
@@ -316,7 +331,7 @@ static int searchoutput(struct filenamenode *namenode) {
     }
   }
   if (found) printf(": %s\n",namenode->name);
-  return found;
+  return found + (namenode->divert ? 1 : 0);
 }
 
 void searchfiles(const char *const *argv) {
@@ -331,6 +346,7 @@ void searchfiles(const char *const *argv) {
 
   modstatdb_init(admindir,msdbrw_readonly);
   ensure_allinstfiles_available_quiet();
+  ensure_diversions();
 
   while ((thisarg= *argv++) != 0) {
     found= 0;
@@ -367,6 +383,7 @@ void enqperpackage(const char *const *argv) {
   const char *thisarg;
   struct fileinlist *file;
   struct pkginfo *pkg;
+  struct filenamenode *namenode;
   
   if (!*argv)
     badusage("--%s needs at least one package name argument", cipaction->olong);
@@ -411,12 +428,20 @@ void enqperpackage(const char *const *argv) {
         
       default:
         ensure_packagefiles_available(pkg);
+        ensure_diversions();
         file= pkg->clientdata->files;
         if (!file) {
           printf("Package `%s' does not contain any files (!)\n",pkg->name);
         } else {
           while (file) {
-            puts(file->namenode->name);
+            namenode= file->namenode;
+            puts(namenode->name);
+            if (namenode->divert && !namenode->divert->camefrom) {
+              if (!namenode->divert->pkg) printf("locally diverted");
+              else if (pkg == namenode->divert->pkg) printf("package diverts others");
+              else printf("diverted by %s",pkg->name);
+              printf(" to: %s\n",namenode->divert->useinstead->name);
+            }
             file= file->next;
           }
         }

scripts/dpkg-divert.pl

@@ -166,9 +166,10 @@ if ($mode eq 'add') {
 }
 
 sub infol {
-    return (($_[2] eq ':' ? "<local>" : length($_[2]) ? "$_[2]" : "<any>").
-            ": $_[0]".
-            (length($_[1]) ? " -> $_[1]" : ""));
+    return (($_[2] eq ':' ? "local " : length($_[2]) ? "" : "any ").
+            "diversion of $_[0]".
+            (length($_[1]) ? " to $_[1]" : "").
+            (length($_[2]) && $_[2] ne ':' ? " by $_[2]" : ""));
 }
 
 sub checkrename {