Doco updates.

CVS patchset: 4641
CVS date: 2001/03/17 19:55:09

13 files changed, 324 insertions, 64 deletions

diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index 6362e7e3c..b20b807c4 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -1,6 +1,17 @@
 ## Process this file with automake to produce Makefile.in
 
 EXTRA_DIST	= \
-	builddependencies buildroot dependencies format macros \
-	multiplebuilds queryformat spec relocatable signatures triggers
-
+	builddependencies \
+	buildroot \
+	conditionalbuilds \
+	dependencies \
+	format \
+	hregions \
+	macros \
+	multiplebuilds \
+	queryformat \
+	relocatable \
+	signatures \
+	spec \
+	triggers \
+	tsort
diff --git a/doc/manual/builddependencies b/doc/manual/builddependencies
index bc09bcd1a..7c3f3795b 100644
--- a/doc/manual/builddependencies
+++ b/doc/manual/builddependencies
@@ -1,4 +1,4 @@
-/*! \page builddpendencies How to generate build depedencies
+/*! \page builddpendencies Generating buiild dependencies automatically
 
 As we start updating packages for the next Red Hat distro, I'd like to see
 packages start to make use of build dependencies. Basically build
diff --git a/doc/manual/buildroot b/doc/manual/buildroot
index f31db4764..77b159646 100644
--- a/doc/manual/buildroot
+++ b/doc/manual/buildroot
@@ -6,7 +6,7 @@ that your package can be built (installed into and packaged from)
 a user-definable directory.  This helps package building by normal
 users.
 
-<h2>The Spec File</h2>
+\subsection buildroot_specfile The Spec File
 
 Simply use
 \verbatim
@@ -59,7 +59,7 @@ would be changed to:
   /usr/bin/fooprog
 \endverbatim
 
-<h2>Building With a Build Root</h2>
+\subsection buildroot_building Building With a Build Root
 
 RPM will use the buildroot listed in the spec file as the default
 buildroot.  There are two ways to override this.  First, you can
@@ -67,7 +67,7 @@ have "buildroot: <dir>" in your rpmrc.  Second, you can override
 the default, and any entry in an rpmrc by using "--buildroot <dir>"
 on the RPM command line.
 
-<h2>Caveats using Build Roots</h2>
+\subsection buildroot_caveats Caveats using Build Roots
 
 Care should be taken when using buildroots that the install directory
 is owned by the correct package.  For example the file
diff --git a/doc/manual/dependencies b/doc/manual/dependencies
index 083b6bc0d..2623d96d9 100644
--- a/doc/manual/dependencies
+++ b/doc/manual/dependencies
@@ -6,7 +6,7 @@ with one another. These can be used to require a python interpretor
 for a python based application for example. RPM ensures dependencies
 are satisfied whenever packages are installed, erased, or upgraded.
 
-<h2>Requiring Packages</h2>
+\subsection dependencies_package Requiring Packages
 
 To require the packages python and perl, use:
 
@@ -114,14 +114,14 @@ You can't continue a "Requires: " line. If you have multiple
 "Requires: " lines then the package requires all packages mentioned on
 all of the lines to be installed.
 
-<h2>Prereqs</h2>
+\subsection dependencies_prereqs Prereqs
 
 Prereqs are different from requires only in that a PreReq is guaranteed
 to be installed before the package that contains the PreReq.  PreReq's
 are used only to order packages, otherwise PreReq's are exactly the same
 as a Requires: dependency.
 
-<h2>Virtual Packages</h2>
+\subsection dependencies_virtual Virtual Packages
 
 Sometimes you need to make sure the system your package is being installed 
 on has a package which provides a certain capability, even though you don't
@@ -150,7 +150,7 @@ on machines that are only partly managed by rpm. A virtual package with
 differs from a package that has /bin/sh in the %files list in that the
 package can be safely removed without removing /bin/sh.
 
-<h2>Automatic Dependencies</h2>
+\subsection dependencies_automatic Automatic Dependencies
 
 To reduce the amount of work required by the package builder, RPM scans
 the file list of a package when it is being built. Any files in the file
@@ -169,7 +169,7 @@ example, the libc-5.3.12 package has provides information added for
 libm.so.5 and libc.so.5. We expect this automatic dependency generation
 to eliminate the need for most packages to use explicit Requires: lines.
 
-<h2>Custom Automatic Dependency</h2>
+\subsection dependencies_custom Custom Automatic Dependency
 
 The automatic dependency programs are found via macro expansion.  Thus
 sites can very the amount of dependnecy processing that are performed
@@ -206,7 +206,7 @@ The default rpm configuration has only
 	%__find_requires	/usr/lib/rpm/find-requires
 which can be overridden (or even undefined) within a spec file.
 
-<h2>Interpreters and Shells</h2>
+\subsection dependencies_interpreters Interpreters and Shells
 
 Modules for interpreted languages like perl and tcl impose additional
 dependency requirements on packages. A script written for an interpreter
@@ -254,7 +254,7 @@ be processed by the find-requires. Since a shell script depends on all the
 programs which it runs.
 
 
-<h2>Installing and Erasing Packages with Dependencies</h2>
+\subsection dependencies_installing Installing and Erasing Packages with Dependencies
 
 For the most part, dependencies should be transparent to the user. However,
 a few things will change.
@@ -274,7 +274,7 @@ no installed packages will have their dependency conditions break due to
 the packages being removed. If you wish to turn off dependency checking for 
 a particular command, use the --nodeps flag.
 
-<h2>Conflicts</h2>
+\subsection dependencies_conflicts Conflicts
 
 While conflicts were implemented in earlier versions of RPM they never 
 worked properly until RPM 2.3.4 (well, we hope they work properly now
@@ -292,7 +292,7 @@ may codify this with a line like:
 The syntax of the "Conflicts" tag is identical to the syntax of the Requires
 tag and conflict checking may be overridden by using the --nodeps flag.
 
-<h2>Querying for Dependencies</h2>
+\subsection dependencies_querying Querying for Dependencies
 
 Two new query information selection options are now available. The first, 
 --provides, prints a list of all of the capabilities a package provides. 
@@ -306,7 +306,7 @@ provide the <item> virtual package. Note that querying for package that
 provides "python" will not return anything, as python is a package, not
 a virtual package.
 
-<h2>Verifying Dependencies</h2>
+\subsection dependencies_verifying Verifying Dependencies
 
 As of RPM 2.2.2, -V (aka --verify) verifies package dependencies
 by default. You can tell rpm to ignore dependencies during system
@@ -315,7 +315,7 @@ and not file attributes (including file existence), use the --nofiles
 flag. Note that "rpm -Va --nofiles --nodeps" will not verify anything at
 all, nor generate an error message.
 
-<h2>Branching Version</h2>
+\subsection dependencies_branching Branching Version
 
 It is quite common to need to branch a set of sources in version
 control. It is not so obvious how those branches should be repesented
@@ -354,7 +354,7 @@ Another alternative scheme might be:
 	Release: <release instance>
 \endverbatim
 
-<h2>Build dependencies</h2>
+\subsection dependencies_build Build dependencies
 
 The following dependencies are availible at build time.  These are
 similar to the install time version but these apply only during
diff --git a/doc/manual/format b/doc/manual/format
index 9281add70..5eb494bce 100644
--- a/doc/manual/format
+++ b/doc/manual/format
@@ -4,9 +4,10 @@ This document describes the RPM file format version 3.0, which is used
 by RPM versions 2.1 and greater.  The format is subject to change, and
 you should not assume that this document is kept up to date with the
 latest RPM code.  That said, the 3.0 format should not change for
-quite a while, and when it does, it will not be 3.0 anymore :-).  In
-any case, THE PROPER WAY TO ACCESS THESE STRUCTURES IS THROUGH THE RPM
-LIBRARY!!
+quite a while, and when it does, it will not be 3.0 anymore :-).
+
+\warning In any case, THE PROPER WAY TO ACCESS THESE STRUCTURES IS THROUGH
+THE RPM LIBRARY!!
 
 The RPM file format covers both source and binary packages.  An RPM
 package file is divided in 4 logical sections:
@@ -14,8 +15,8 @@ package file is divided in 4 logical sections:
 \verbatim
 . Lead      -- 96 bytes of "magic" and other info
 . Signature -- collection of "digital signatures"
-. Header    -- holding area for all the package information
-. Payload   -- compressed archive of all the files in the package
+. Header    -- holding area for all the package information (aka "metadata")
+. Payload   -- compressed archive of the file(s) in the package (aka "payload")
 \endverbatim
 
 All 2 and 4 byte "integer" quantities (int16 and int32) are stored in
@@ -23,7 +24,7 @@ network byte order.  When data is presented, the first number is the
 byte number, or address, in hex, followed by the byte values in hex,
 followed by character "translations" (where appropriate).
 
-<h2>Lead</h2>
+\subsection pkgformat_lead Lead
 
 The Lead is basically for file(1).  All the information contained in
 the Lead is duplicated or superceded by information in the Header.
@@ -94,7 +95,7 @@ is 5, which indicates the new "Header-style" signatures.
 The remaining 16 bytes (80-95) are currently unused and are reserved
 for future expansion.
 
-<h2>Signature</h2>
+\subsection pkgformat_signature Signature
 
 A 3.0 format signature (denoted by signature type 5 in the Lead), uses
 the same structure as the Header.  For historical reasons, this
@@ -122,7 +123,7 @@ the size of the PGP key used to sign the package.
 As of RPM 2.1, all packages carry at least SIZE and MD5 signatures,
 and the Signature section is padded to a multiple of 8 bytes.
 
-<h2>Header</h2>
+\subsection pkgformat_header Header
 
 The Header contains all the information about a package: name,
 version, file list, etc.  It uses the same "header structure" as the
@@ -131,12 +132,12 @@ tags for the Header would take too much space to list here, and the
 list grows fairly frequently.  For the complete list see lib/rpmlib.h
 in the RPM sources.
 
-<h2>Payload</h2>
+\subsection pkgformat_payload Payload
 
 The Payload is currently a gzipped cpio archive.  The cpio
 archive type used is SVR4 with a CRC checksum.
 
-<h2>The Header Structure</h2>
+\subsection pkgformat_header_structure The Header Structure
 
 The header structure is a little complicated, but actually performs a
 very simple function.  It acts almost like a small database in that it
@@ -245,7 +246,7 @@ could start at byte 589, byte that is an improper boundary for an INT32.
 As a result, 3 null bytes are inserted and the date for the SIZE actually
 starts at byte 592: "00 09 9b 31", which is 629553).
 
-<h2>Tools</h2>
+\subsection pkgformat_tools Tools
 
 The tools directory in the RPM sources contains a number of small
 programs that use the RPM library to pick apart packages.  These
diff --git a/doc/manual/hregions b/doc/manual/hregions
new file mode 100644
index 000000000..91408b349
--- /dev/null
+++ b/doc/manual/hregions
@@ -0,0 +1,89 @@
+/*! \page hregions Immutable header regions in rpm-4.0.1 and later
+
+The header data structure has changed in rpm-4.0.[12] to preserve the
+original header from a package. The goal is to keep the original
+header intact so that metadata can be verified separately from the
+payload by the RHN up2date client and by the rpm commmand line verify
+mode using signatures saved in the rpm database. I believe the change
+is entirely forward and backward compatible, and will not require
+any artifacts like changing the version number of packaging or 
+adding an "rpmlib(...)" tracking dependendency. We'll see ...
+
+Here's a short description of the change. An rpm header has three sections:
+\verbatim
+	1) intro		(# entries in index, # bytes of data)
+	2) index		16 byte entries, one per tag, big endian
+	3) data			tag values, properly aligned, big endian
+\endverbatim
+
+Representing sections in the header (ignoring the intro) with
+\verbatim
+	A,B,C			index entries sorted by tag number
+	a,b,c			variable length entry data
+	| 			boundary between index/data
+\endverbatim
+a header with 3 tag/value pairs (A,a) can be represented something like
+\verbatim
+	ABC|abc
+\endverbatim
+
+The change is to introduce a new tag that keeps track of a contiguous
+region (i.e. the original header). Representing the boundaries with
+square/angle brackets, an "immutable region" in the header thus becomes
+\verbatim
+	[ABC|abc]
+\endverbatim
+or more generally (spaces added for clarity)
+\verbatim
+	[ABC> QRS | <abc] qrs
+\endverbatim
+or with concatenated regions (not implemented yet)
+\verbatim
+	[ABC> [DEF> QRS | <abc] <def] qrs
+\endverbatim
+or with nested regions (not implemented yet)
+\verbatim
+	[ABC [DEF>> QRS | <<abc] def] qrs
+\endverbatim
+
+\todo Either concatenated/nested regions may be used to implement
+a metarpm, aka a package of packages, dunno how, when, or even if, yet.
+
+What complicates the above is legacy issues, as various versions of rpm
+have added/deleted/modified entries in the header freely. Thus, representing
+altered tag entries/data with a '.', there is a need to preserve deleted
+information something like
+
+\verbatim
+	[A.C> QRS XYZ | <a.c] qrs xyz
+\endverbatim
+
+\note This is basically the change that replaces the filename with
+	a {dirname,basename,dirindex} triple between rpm-3.x and rpm-4.x.
+
+or
+
+\verbatim
+	[AB.> QRS D | <ab.] qrs d
+\endverbatim
+
+\note The header is no longer sorted because of replacing Cc with Dd.
+
+and yet permit retrieval of the original
+
+\verbatim
+	[ABC|abc]
+\endverbatim
+
+region. PITA, really.
+
+What made header regions trickier yet is the desire to have an implementation
+that is both backward and forward compatible. I won't bore you with the
+tedious details.
+
+However, even after doing regressions against supported Red Hat releases,
+there's a Great Big Universe of rpm packages out there, and I'm *very*
+interested in hearing (as bug reports against rpm at http://bugzilla.redhat.com)
+about any and all problems with header regions in rpm-4.0.1.
+
+*/
diff --git a/doc/manual/macros b/doc/manual/macros
index 781ceda70..d296ca1b2 100644
--- a/doc/manual/macros
+++ b/doc/manual/macros
@@ -10,7 +10,7 @@ lists" (i.e. those read in using %files -f <file>).  In addition, macros
 can be nested, hiding the previous definition for the duration of the
 expansion of the macro which contains nested macros.
 
-<h2>Defining a Macro</h2>
+\subsection macros_defining Defining a Macro
 
 To define a macro use:
 
@@ -39,7 +39,7 @@ following shell-like macros are available:
 At the end of invocation of a parameterized macro, the above macros are
 (at the moment, silently) discarded.
 
-<h2>Writing a Macro</h2>
+\subsection macros_writing Writing a Macro
 
 Within the body of a macro, there are several constructs that permit
 testing for the presence of optional parameters. The simplest construct
@@ -57,7 +57,7 @@ deleted). Note the 2nd % needed to escape the arguments to /bin/date.
 There is currently an 8K limit on the size that this macro can expand
 to.
 
-<h2>Builtin Macros</h2>
+\subsection macros_builtin Builtin Macros
 
 There are several builtin macros (with reserved names) that are needed
 to perform useful operations. The current list is
@@ -92,7 +92,7 @@ In addition, rpm itself defines numerous macros. To display the current
 set, add "%dump" to the beginning of any spec file, process with rpm, and
 examine the output from stderr.
 
-<h2>Example of a Macro</h2>
+\subsection macros_example Example of a Macro
 
 Here is an example %patch definition from /usr/lib/rpm/macros:
 
@@ -130,7 +130,7 @@ There are two "private" helper macros:
 	%patch_suffix	the gory details of overriding the (default) ".orig"
 \endverbatim
 
-<h2>Using a Macro</h2>
+\subsection macros_using Using a Macro
 
 To use a macro, write:
 
@@ -148,7 +148,7 @@ The %{...} form allows you to place the expansion adjacent to other text.
 The %<name> form, if a parameterized macro, will do argc/argv processing
 of the rest of the line as described above.
 
-<h2>Command Line Options</h2>
+\subsection macros_commandline Command Line Options
 
 When the command line option "--define 'macroname value'" allows the
 user to specify the value that a macro should have during the build.
@@ -167,7 +167,7 @@ Note: This works only macros defined in rpm configuration files, not for
 macros defined in specfiles. You can use %{echo: %{your_macro_here}} if
 you wish to see the expansion of a macro defined in a spec file.
  
-<h2>Configuration using Macros</h2>
+\subsection macros_configuration Configuration using Macros
 
 Starting in rpm 3.0, macros rather than rpmrc lines are used to configure rpm.
 In general, all the rpmrc configuration lines documented in "Maximum RPM"
@@ -209,7 +209,7 @@ Here are 2 common FAQ for experienced users of rpm:
 		%_topdir        whatever
 \endverbatim
 
-<h2>Macro Analogues of Autoconf Variables</h2>
+\subsection macros_autoconf Macro Analogues of Autoconf Variables
 
 Several macro definitions provided by the default rpm macro set have uses in
 packaging similar to the autoconf variables that are used in building packages:
diff --git a/doc/manual/queryformat b/doc/manual/queryformat
index 181c1134c..19ef60151 100644
--- a/doc/manual/queryformat
+++ b/doc/manual/queryformat
@@ -4,7 +4,7 @@ As it is impossible to please everyone with one style of query output, RPM
 allows you to specify what information should be printed during a query
 operation and how it should be formatted.
 
-<h2>Tags</h2>
+\subsection queryformat_tags Tags
 
 All of the information a package contains, apart from signatures and the
 actual files, is in a part of the package called the header. Each piece
@@ -36,7 +36,7 @@ the same reason.
 A tag can consist of one element or an array of elements. Each element can
 be a string or number only.
 
-<h2>Query Formats</h2>
+\subsection queryformat_format Query Formats
 
 A query format is passed to RPM after the --queryformat argument, and normally
 should be enclosed in single quotes. This query format is then used to print
@@ -63,7 +63,7 @@ right align the size to, use:
     rpm -qa --queryformat "%-30{NAME} %10{SIZE}\n"
 \endverbatim
 
-<h2>Arrays</h2>
+\subsection queryformat_arrays Arrays
 
 RPM uses many parallel arrays internally. For example, file sizes and 
 file names are kept as an array of numbers and an array of strings
@@ -114,7 +114,7 @@ which will give you the expected output.
     cdp /usr/man/man1/cdp.1
 \endverbatim
 
-<h2>Formatting Tags</h2>
+\subsection queryformat_formatting Formatting Tags
 
 One of the weaknesses with query formats is that it doesn't recognize
 that the INSTALLTIME tag (for example) should be printed as a date instead
@@ -133,7 +133,7 @@ name after the tag name. Here are some examples:
 The :shescape may be used on plain strings to get a string which can pass
 through a single level of shell and give the original string.
 
-<h2>Query Expressions</h2>
+\subsection queryformat_expressions Query Expressions
 
 Simple conditionals may be evaluated through query expressions. Expressions
 are delimited by %|...|. The only type of expression currently supported
@@ -148,7 +148,7 @@ the SOMETAG tag is present, and "missing" otherwise:
 Notice that the subformats "present" and "missing" must be inside of curly
 braces.
 
-<h2>Viewing the Verify Flags</h2>
+\subsection queryformat_example Example: Viewing the Verify Flags
 
 The follwing example query is run against dev becuase I know %verify
 is used there.
diff --git a/doc/manual/relocatable b/doc/manual/relocatable
index ecc503936..c4bdd41ab 100644
--- a/doc/manual/relocatable
+++ b/doc/manual/relocatable
@@ -6,7 +6,7 @@ may distribute their software to install in "/opt" but you'd like
 it to install in "/usr/opt".  If the vendor were distributing a
 relocatable RPM package, it would be easy.
 
-<h2>Building a Relocatable Package</h2>
+\subsection relcateable_building Building a Relocatable Package
 
 Not all software can be "relocatable".  Before continuing you should
 think about how the program works, what files it accesses, what other
@@ -35,7 +35,7 @@ into the spec file so that the /usr and /etc directories may be
 relocated separately when this package is installed.
 
 
-<h2>Installing Relocatable Packages</h2>
+\subsection relcateable_installing Installing Relocatable Packages
 
 By default, RPM will install a relocatable package in the prefix
 directory listed in the spec file.  You can override this on the
diff --git a/doc/manual/signatures b/doc/manual/signatures
index 22f5a78cd..7b4f6dc71 100644
--- a/doc/manual/signatures
+++ b/doc/manual/signatures
@@ -6,10 +6,10 @@ up and extended, the signature section in the RPM file format
 has been made easily extensible with new signature types, and
 packages can have multiple signatures.
 
-<h2>PGP</h2>
+\subsection signatures_pgp PGP
 
-RPM's previous usage of PGP was cumbersome, and only supported
-1024 bit keys.  Both of these problems have been corrected.
+Legacy usage of PGP in rpm-2.0 was cumbersome, and only supported
+1024 bit keys.  Both of these problems have been corrected in rpm-2.1.
 
 Whereas previously you needed many rpmrc entries to clue in
 RPM about keyring locations and such, RPM now behaves as PGP
@@ -33,7 +33,7 @@ supply values for
 	%_pgp_path	the path to the key ring
 \endverbatim
 
-<h2>Signature Creation</h2>
+\subsection signatures_signing Signing Packages
 
 Signature creation is the same as previous releases: just add
 a --sign to your build command line.  You can sign a package
@@ -56,7 +56,7 @@ packages, which means that packages built without --sign can
 be "verified" to some extent.  The MD5 signature should catch
 problems like corrupt packages, faulty downloads, etc.
 
-<h2>Signature Verification</h2>
+\subsection signatures_verifying Verifying Package Signatures
 
 Package signature verification is the same as previous releases:
 
diff --git a/doc/manual/spec b/doc/manual/spec
index fc48ae05a..2a27e48ec 100644
--- a/doc/manual/spec
+++ b/doc/manual/spec
@@ -19,7 +19,7 @@ definition:
 	%package -n newname
 \endverbatim
 
-<h2>Summary and Description</h2>
+\subsection specfile_summary Summary: and Description: Tags
 
 The Summary: tag should be use to give a short (50 char or so) summary
 of the package.  Most package's Description: line should be changed to
@@ -66,7 +66,7 @@ are considered "pre-formatted" and will be left alone.  Adjacent
 lines without leading whitespace are considered a single paragraph
 and may be subject to formatting by glint or another RPM tool.
 
-<h2>Other Tags</h2>
+\subsection specfile_url URL: and Packager: Tags
 
 Two new tags are "URL:" and "Packager:".  "URL:" is a place to put a
 URL for more information and/or documentation on the software
@@ -76,7 +76,7 @@ address of the person who "maintains" the RPM package (which may be
 different from the person who actually maintains the program the
 package contains).
 
-<h2>BuildArchitectures</h2>
+\subsection specfile_buildarchitectures BuildArchitectures: Tag
 
 This tag specifies the arctecture which the resulting binary package
 will run on.  Typically this is a CPU architecture like sparc,
@@ -84,7 +84,7 @@ i386. The string 'noarch' is reserved for specifying that the
 resulting binary package is platform independent.  Typical platform
 independent packages are html, perl, python, java, and ps packages.
 
-<h2>Files Attributes</h2>
+\subsection specfile_virtual Virtual File Attribute(s) in %files Section
 
 A %ghost tag on a file indicates that this file is not to be included
 in the package.  It is typically used when the attributes of the file
@@ -101,14 +101,14 @@ The %config(noreplace) indicates that the file in the package should
 be installed with extension .rpmnew if there is already a modified file
 with the same name on the installed machine.
 
--The virtual file attribute token %verify tells `-V/--verify' to ignore
+The virtual file attribute token %verify tells `-V/--verify' to ignore
 certain features on files which may be modified by (say) a postinstall
 script so that false problems are not displayed during package verification.
 \verbatim
 	%verify(not size md5 mtime) %{prefix}/bin/javaswarm
 \endverbatim
 
-<h2>Shell Gobbing of %files</h2>
+\subsection specfile_globbing Shell Gobbing of %files Section
 
 The usual rules for shell globbing apply.  Most special characters can
 be escaped by prefixing them with a '\'.  Spaces are used to separate
@@ -136,7 +136,7 @@ easiest to do with a shell script like this:
 	%files -f filelist.rpm
 \endverbatim
 
-<h2>Fine Adjustment of Automatic Dependencies</h2>
+\subsection specfile_automatic Fine Adjustment of Automatic Dependencies
 
 Rpm currently supports separate "Autoreq:" and "Autoprov:" tags in a
 spec file to independently control the running of find-requires and
@@ -163,7 +163,7 @@ Similarly there is an Autoprov tag to turn off the automatic provision
 generation and a Autoreqprov to turn off both the automatic provides and
 the automatic requires generation.
 
-<h2>nosrc rpms</h2>
+\subsection specfile_nosrc NoSource: Tag
 
 Files ending in .nosrc.rpm are generally source RPM packages whose spec
 files have one or more NoSource: or NoPatch: directives in them.  Both
@@ -186,7 +186,7 @@ The end result of all this, though, is that you can't rebuild
 ``no-source'' RPM packages using `rpm --rebuild' unless you also have
 the sources or patches which are not included in the .nosrc.rpm.
 
-<h2>BuildRequires</h2>
+\subsection specfile_buildrequires BuildRequires: Tag
 
 Build dependencies are identical to install dependencies except:
 
diff --git a/doc/manual/triggers b/doc/manual/triggers
index 733332733..6e3ed8945 100644
--- a/doc/manual/triggers
+++ b/doc/manual/triggers
@@ -7,7 +7,7 @@ of the normal installation scripts (i.e. %pre) which allows one package
 "triggered package"]) to execute an action when the installation status
 of another package (the "target" of the trigger) changes.
 
-<h2>A Simple Example</h2>
+\subsection triggers_example A Simple Example
 
 Say the package "mymailer" needs an /etc/mymailer/mailer symlink which points
 to the mail transport agent to use. If sendmail is installed, the link should
@@ -100,7 +100,7 @@ this case, if any of the targets will remain after the uninstall, the
 trigger doesn't do anything (as it's probably being triggered by an
 upgrade).
 
-<h2>Trigger Syntax</h2>
+\subsection triggers_syntax Trigger Syntax
 
 Trigger specifications are of the form:
 
@@ -123,7 +123,7 @@ Will put a trigger in package 'package' which runs when the installation
 status of either fileutils > 3.0 or perl < 1.2 is changed. The script will
 be run through /usr/bin/perl rather then /bin/sh (which is the default).
 
-<h2>An Unusual Case</h2>
+\subsection triggers_unusual An Unusual Case
 
 There is one other type of trigger available -- %triggerpostun. These are
 triggers that are run after their target package has been removed; they will
@@ -133,7 +133,7 @@ While this type of trigger is almost never useful, they allow a package to
 fix errors introduced by the %postun of another package (or by an earlier 
 version of that package).
 
-<h2>Order of Script Execution</h2>
+\subsection triggers_order Order of Script Execution
 
 For reference, here's the order in which scripts are executed on a single
 package upgrade:
diff --git a/doc/manual/tsort b/doc/manual/tsort
new file mode 100644
index 000000000..8b2177359
--- /dev/null
+++ b/doc/manual/tsort
@@ -0,0 +1,159 @@
+/*! \page tsort Package ordering in rpm-4.0.1 and later
+
+The package ordering algorithm in rpm-4.0.1 has changed.
+
+\subsection tsort_problem The Problem
+
+Here's a simple test to illustrate the need for the change (from
+bugzilla #12327):
+
+Assume the minimal 7.0 package manifest in /tmp/list
+\verbatim
+	/mnt/redhat/comps/dist/7.0/sparc/bash-2.04-11.sparc.rpm
+	/mnt/redhat/comps/dist/7.0.2/sparc/glibc-2.1.94-1.sparc.rpm
+	/mnt/redhat/comps/dist/7.0/sparc/mktemp-1.5-5.sparc.rpm
+	/mnt/redhat/comps/dist/7.0/noarch/basesystem-7.0-2.noarch.rpm
+	/mnt/redhat/comps/dist/7.0/noarch/setup-2.3.4-1.noarch.rpm
+	/mnt/redhat/comps/dist/7.0/noarch/filesystem-2.0.7-1.noarch.rpm
+	/mnt/redhat/comps/dist/7.0/sparc/libtermcap-2.0.8-25.sparc.rpm
+	/mnt/redhat/comps/dist/7.0/noarch/termcap-11.0.1-3.noarch.rpm
+\endverbatim
+
+with database initialization as
+\verbatim
+	mkdir -p /tmp/ROOT/var/lib/rpm
+	rpm --initdb /tmp/ROOT/var/lib/rpm
+\endverbatim
+
+This command "works"
+\verbatim
+	rpm -Uvh -r /tmp/ROOT `cat /tmp/list`
+\endverbatim
+while this command
+\verbatim
+	rpm -Uvh -r /tmp/ROOT `tac /tmp/list`
+\endverbatim
+fails with 
+\verbatim
+	loop in prerequisite chain: libtermcap bash libtermcap
+\endverbatim
+
+\note The 2nd upgrade reverse orders the packages in the manifest.
+
+The problem is that the previous ordering algorithm, basically a very clever
+implementation of tsort, was sensitive to initial conditions, and the first
+command "happens" to snip a loop, while the second does not.
+
+\subsection tsort_solution The Solution
+
+The current ordering algorithm is exactly tsort from Knuth V1, with one further
+twist. Since the only way out of a dependency loop is to snip the loop
+somewhere, rpm uses hints from Requires: dependencies to distinguish
+co-requisite (these are not needed to install, only to use, a package) from
+pre-requisite (these are guaranteed to be installed before the package that
+includes the dependency) relations.
+
+There is now syntax in spec files to explicitly specify the source of a
+Requires: dependency.  If, for example, you use grep in %post, then you
+as a packager would normally add
+\verbatim
+	PreReq: grep
+\endverbatim
+in order to insure that grep was installed before attempted use by the 
+%postun scriptlet.
+
+Now the same dependency can be expressed more precisely as
+\verbatim
+	Requires(post): grep
+\endverbatim
+
+For completeness, here's the complete set of tokens that may be
+added to Requires: as in the example above:
+\verbatim
+    "interp",         RPMSENSE_INTERP
+    "prereq",         RPMSENSE_PREREQ
+    "preun",          RPMSENSE_SCRIPT_PREUN
+    "pre",            RPMSENSE_SCRIPT_PRE
+    "postun",         RPMSENSE_SCRIPT_POSTUN
+    "post",           RPMSENSE_SCRIPT_POST
+    "rpmlib",         RPMSENSE_RPMLIB
+    "verify",         RPMSENSE_SCRIPT_VERIFY
+\endverbatim
+
+Ditto BuildRequires:
+\verbatim
+    "prep",           RPMSENSE_SCRIPT_PREP
+    "build",          RPMSENSE_SCRIPT_BUILD
+    "install",        RPMSENSE_SCRIPT_INSTALL
+    "clean",          RPMSENSE_SCRIPT_CLEAN
+\endverbatim
+but let's not go there (yet).
+
+For giggles, you can also do stuff like
+\verbatim
+	Requires(pre,post): /bin/sh
+\endverbatim
+
+By marking dependencies more precisely, rpm can distinguish between
+an upgrade context (like the use of grep in %post above) and an installed
+context (like the autogenerated Requires: in a package that includes a
+script with #!/bin/sh), and that permits rpm to differentiate pre-requisites
+from co-requisites while doing package ordering.
+
+Here's what cures the libtermcap <-> bash loop:
+\verbatim
+	Requires(postun): /bin/sh
+\endverbatim
+which, since the dependency is clearly not useful or necessary in determining
+install ordering, is safely ignored.
+
+\subsection tsort_sideeffects Side Effects
+
+One of the side effects of changing the package install ordering, is that
+there are a handful of new loops that are detected. Here's what I found
+looking at supported Red Hat releases:
+
+\verbatim
+    ghostscript-fonts	ghostscript
+    /* 7.0 only */
+    pango-gtkbeta-devel	pango-gtkbeta
+    XFree86		Mesa
+    compat-glibc	db2
+    compat-glibc	db1
+    pam			initscripts
+    kernel		initscripts
+    initscripts		sysklogd
+    /* 6.2 */
+    egcs-c++		libstdc++
+    /* 6.1 */
+    pilot-link-devel	pilot-link
+    /* 5.2 */
+    pam			pamconfig
+\endverbatim
+
+Why are there new loops? Because tsort is trying to use all of the
+dependency relations for ordering, while the previous tsort ignored all
+Requires: from added packages.
+
+Except for the "well known" libtermcap <-> bash loop (which is just wrong),
+all of the other dependencies are simply not needed in an upgrade context
+to perform package ordering. Please note that all of the known to cause
+loop dependencies listed above are, for now, explicitly ignored when
+determining package install ordering.
+
+\subsection tsort_summary Summary
+
+So what does this all mean? Basically not much, unless you find yourself
+trying to specify dependencies amongst a set of packages correctly and
+happen to create a dependency loop.
+
+And, before you start adding the new-fangled syntax to packages, please
+remember that rpm will almost certainly be auto-generating fine-grained
+dependencies for %post et al scriptlets pretty soon. Truly, rpm needs to
+make packaging easier, not provide Yet More Complicated Syntax in spec files.
+
+With thanks to Ken Estes for doing the implementation in bash2 that makes
+it possible to auto-generate scriptlet dependencies, blame me for the long,
+slow deployment.
+
+*/