add pl translation and man pages (Tomasz K?oczko et al).

CVS patchset: 3183
CVS date: 1999/07/19 22:13:12

9 files changed, 1087 insertions, 0 deletions

diff --git a/doc/manual/buildroot b/doc/manual/buildroot
new file mode 100644
index 000000000..ec40c52ea
--- /dev/null
+++ b/doc/manual/buildroot
@@ -0,0 +1,66 @@
+BUILD ROOT
+==========
+
+The build root is very similar to Root: (which will be deprecated
+soon).  By using Buildroot: in your spec file you are indicating
+that your package can be built (installed into and packaged from)
+a user-definable directory.  This helps package building by normal
+users.
+
+The Spec File
+-------------
+
+Simply use
+
+  Buildroot: <dir>
+
+in your spec file.  The acutal buildroot used by RPM during the
+build will be available to you (and your %prep, %build, and %install
+sections) as the environment variable RPM_BUILD_ROOT.  You must
+make sure that the files for the package are installed into the
+proper buildroot.  As with Root:, the files listed in the %files
+section should *not* contain the buildroot.  For example, the
+following hypothetical spec file:
+
+  Name: foo
+  ...
+  Root: /tmp
+  
+  %prep
+  ...
+  
+  %build
+  ...
+  
+  %install
+  install -m755 fooprog /tmp/usr/bin/fooprog
+  
+  %files
+  /usr/bin/fooprog
+
+would be changed to:
+
+  Name: foo
+  ...
+  Buildroot: /tmp
+  
+  %prep
+  ...
+  
+  %build
+  ...
+  
+  %install
+  install -m755 fooprog $RPM_BUILD_ROOT/usr/bin/fooprog
+  
+  %files
+  /usr/bin/fooprog
+
+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
+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.
diff --git a/doc/manual/dependencies b/doc/manual/dependencies
new file mode 100644
index 000000000..62c1adca5
--- /dev/null
+++ b/doc/manual/dependencies
@@ -0,0 +1,178 @@
+DEPENDENCIES
+============
+
+Dependencies provide a way for a package builder to require other
+packages or capabilities to be installed before or simultaneously
+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.
+
+Requiring Packages
+------------------
+
+To require packages, use:
+
+	Requires: python perl
+
+in the spec file. Note that "Requires python, perl" would work as well. If you
+needed to have a very recent version of python but any version of perl,
+
+	Requires: python >= 1.3, perl
+
+would do the trick. Again, the ',' in the line is optional.  Instead of
+'>=', you may also use '<', '>', '<=', or '='.
+
+RPM uses an internal algorithm to determine version number orderings which
+works correctly most of the time. For example, it will know that
+1.9a is older then 1.9b. However, it will also be later then 1.9 which
+may or may not be correct as some programmers use letters in version numbers
+to indicate beta versions. 
+
+To work around this, you may specify a serial number for a package like this:
+
+	Serial: 23
+
+If a Requires: line should be comparing the given number with a serial number
+instead of a version number, you would do this:
+
+	Requires: somepackage =S 23
+
+You can't continue a "Requires: " line. If you have multiple
+"Requires: " lines then the package requires all pacakges mentioned on
+all lines to be installed. Max line length is probably 8K.
+
+
+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
+care what specific package provides it. For example, sendmail won't work
+properly unless a local delivery agent (lda) is present. You can ensure that
+one is installed like this:
+
+	Requires: lda
+
+This will match either a package called lda (as mentioned above), or any
+package which contains:
+
+	Provides: lda
+
+in its .spec file. No version numbers may be used with virtual packages.
+
+Automatic Dependencies
+----------------------
+
+To reduct 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
+list which require shared libraries to work (as determined by ldd) cause
+that package to require the shared library.
+
+For example, if your package contains /bin/vi, RPM will add dependencies 
+for both libtermcap.so.2 and libc.so.5. These are treated as virtual
+packages, so no version numbers are used.
+
+A similar process allows RPM to add Provides information automatically. Any
+shared library in the file list is examined for its soname (the part of
+the name which must match for two shared libraries to be considered
+equivalent) and that soname is automatically provided by the package. For
+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.
+
+
+Interpreters and Shells (to be implemented)
+-----------------------
+
+Modules for interpreted languages like perl and tcl impose additional
+dependency requirements on packages. A script written for an interpreter
+often requires language specfic modules to be installed in order to execute
+correctly. In order to automatically detect langiage specific modules, each
+interpreter may have its own find-provides and find-requires. To prevent
+module name collisions between interpreters, module names are enclosed within
+parentheses and a conventional interpreter specific identifier is pre-pended:
+
+
+  Provides: perl(MIME-Base64), perl(Mail-Header)-1-09
+
+  Requires: perl(Carp), perl(IO-Wrap) = 4.5
+
+
+The output of a per-interpreter find-requires (notice in this example the
+first requirement is a package and the rest are langague specific modules)
+
+	Mail-Header >= 1.01
+	perl(Carp) >= 3.2
+	perl(IO-Wrap) == 4.5 or perl(IO-Wrap)-4.5
+
+the output from find-provides is
+	Foo-0.9
+	perl(Widget)-0-1
+
+
+The per-interpreter automatic module detectors will normally be located in
+	/usr/lib/rpm/{perl,tcl}/find-{provides,requires}
+with appropriate per-interpreter hooks into
+	/usr/lib/rpm/find-{provides,requires}
+
+
+Installing and Erasing Packages with Dependencies
+-------------------------------------------------
+
+For the most part, dependencies should be transparent to the user. However,
+a few things will change.
+
+First, when packages are added or upgraded, all of their dependencies
+must be satisfied. If they are not, an error message like this appears:
+
+    failed dependencies:
+	    libICE.so.6  is needed by somepackage-2.11-1
+	    libSM.so.6  is needed by somepackage-2.11-1
+	    libc.so.5  is needed by somepackage-2.11-1
+
+Similarly, when packages are removed, a check is made to ensure that 
+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.
+
+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
+anyway).
+
+Conflicts allow a package to say it won't work with another package (or
+virtual package) installed on the system. For example, qmail doesn't work
+(w/o custom setup) on machines with sendmail installed. The qmail spec file
+may codify this with a line like:
+
+Conflicts: sendmail
+
+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.
+
+Querying with Dependencies
+--------------------------
+
+Two new query information selection options are now available. The first, 
+--provides, prints a list of all of the capabilities a package provides. 
+The second, --requires, shows the other packages that a package requires
+to be installed, along with any version number checking.
+
+There are also two new ways to search for packages. Running a query with 
+--whatrequires <item> queries all of the packages that require <item>. 
+Similarly, running --whatprovides <item> queries all of the packages that 
+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.
+
+Verifying Dependencies
+----------------------
+
+As of RPM 2.2.2, -V (aka -y, --verify) verifies package dependencies
+by default. You can tell rpm to ignore dependencies during system
+verification with the --nodeps. If you want RPM to verify just dependencies
+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.
diff --git a/doc/manual/format b/doc/manual/format
new file mode 100644
index 000000000..987faf95a
--- /dev/null
+++ b/doc/manual/format
@@ -0,0 +1,246 @@
+RPM File Format
+===============
+
+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!!
+
+The RPM file format covers both source and binary packages.  An RPM
+package file is divided in 4 logical sections:
+
+. Lead      -- 96 bytes of "magic" and other info
+. Signature -- collection of "digital signatures"
+. Header    -- holding area for all the package information
+. Archive   -- compressed archive of all the files in the package
+
+All 2 and 4 byte "integer" quantities (int16 and int32) are stored in
+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).
+
+Lead
+----
+
+The Lead is basically for file(1).  All the information contained in
+the Lead is duplicated or superceded by information in the Header.
+Much of the info in the Lead was used in old versions of RPM but is
+now ignored.  The Lead is stored as a C structure:
+
+struct rpmlead {
+    unsigned char magic[4];
+    unsigned char major, minor;
+    short type;
+    short archnum;
+    char name[66];
+    short osnum;
+    short signature_type;
+    char reserved[16];
+};
+
+and is illustrated with one pulled from the rpm-2.1.2-1.i386.rpm
+package:
+
+00000000: ed ab ee db 03 00 00 00
+
+The first 4 bytes (0-3) are "magic" used to uniquely identify an RPM
+package.  It is used by RPM and file(1).  The next two bytes (4, 5)
+are int8 quantities denoting the "major" and "minor" RPM file format
+version.  This package is in 3.0 format.  The following 2 bytes (6-7)
+form an int16 which indicates the package type.  As of this writing
+there are only two types: 0 == binary, 1 == source.
+
+00000008: 00 01 72 70 6d 2d 32 2e    ..rpm-2.
+
+The next two bytes (8-9) form an int16 that indicates the architecture
+the package was built for.  While this is used by file(1), the true
+architecture is stored as a string in the Header.  See, lib/misc.c for
+a list of architecture->int16 translations.  In this case, 1 == i386.
+Starting with byte 10 and extending to byte 75, are 65 characters and
+a null byte which contain the familiar "name-version-release" of the
+package, padded with null (0) bytes.
+
+00000010: 31 2e 32 2d 31 00 00 00    1.2-1...
+00000018: 00 00 00 00 00 00 00 00    ........
+00000020: 00 00 00 00 00 00 00 00    ........
+00000028: 00 00 00 00 00 00 00 00    ........
+00000030: 00 00 00 00 00 00 00 00    ........
+00000038: 00 00 00 00 00 00 00 00    ........
+00000040: 00 00 00 00 00 00 00 00    ........
+00000048: 00 00 00 00 00 01 00 05    ........
+
+Bytes 76-77 ("00 01" above) form an int16 that indicates the OS the
+package was built for.  In this case, 1 == Linux.  The next 2 bytes
+(78-79) form an int16 that indicates the signature type.  This tells
+RPM what to expect in the Signature.  For version 3.0 packages, this
+is 5, which indicates the new "Header-style" signatures.
+
+00000050: 04 00 00 00 68 e6 ff bf    ........
+00000058: ab ad 00 08 3c eb ff bf    ........
+
+The remaining 16 bytes (80-95) are currently unused and are reserved
+for future expansion.
+
+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
+structure is called a "header structure", which can be confusing since
+it is used for both the Header and the Signature.  The details of the
+header structure are given below, and you'll want to read them so the
+rest of this makes sense.  The tags for the Signature are defined in
+lib/signature.h.
+
+The Signature can contain multiple signatures, of different types.
+There are currently only three types, each with its own tag in the
+header structure:
+
+	Name	Tag	Header Type
+	----	----	-----------
+	SIZE	1000	INT_32
+	MD5	1001	BIN
+	PGP	1002	BIN
+
+The MD5 signature is 16 bytes, and the PGP signature varies with
+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.
+
+Header
+------
+
+The Header contains all the information about a package: name,
+version, file list, etc.  It uses the same "header structure" as the
+Signature, which is described in detail below.  A complete list of the
+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.
+
+Archive
+-------
+
+The Archive is currently a gzipped cpio archive.  The cpio
+archive type used is SVR4 with a CRC checksum.
+
+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
+allows you to store and retrieve arbitrary data with a key called a
+"tag".  When a header structure is written to disk, the data is
+written in network byte order, and when it is read from disk, is is
+converted to host byte order.
+
+Along with the tag and the data, a data "type" is stored, which indicates,
+obviously, the type of the data associated with the tag.  There are
+currently 9 types:
+
+	Type		Number
+	----		------
+	NULL		0
+	CHAR		1
+	INT8		2
+	INT16		3
+	INT32		4
+	INT64		5
+	STRING		6
+	BIN		7
+	STRING_ARRAY	8
+
+One final piece of information is a "count" which is stored with each
+tag, and indicates the number of items of the associated type that are
+stored.  As a special case, the STRING type is not allowed to have a
+count greater than 1.  To store more than one string you must use a
+STRING_ARRAY.
+
+Altogether, the tag, type, count, and data are called an "Entry" or
+"Header Entry".
+
+00000000: 8e ad e8 01 00 00 00 00    ........
+
+A header begins with 3 bytes of magic "8e ad e8" and a single byte to
+indicate the header version.  The next four bytes (4-7) are reserved.
+
+00000008: 00 00 00 20 00 00 07 77    ........
+
+The next four bytes (8-11) form an int32 that is a count of the number
+of entries stored (in this case, 32).  Bytes 12-15 form an int32 that
+is a count of the number of bytes of data stored (that is, the number
+of bytes made up by the data portion of each entry).  In this case it
+is 1911 bytes.
+
+00000010: 00 00 03 e8 00 00 00 06 00 00 00 00 00 00 00 01    ................
+
+Following the first 16 bytes is the part of the header called the
+"index".  The index is made of up "index entries", one for each entry
+in the header.  Each index entry contains four int32 quantities.  In
+order, they are: tag, type, offset, count.  In the above example, we
+have tag=1000, type=6, offset=0, count=1.  By looking up the the tag
+in lib/rpmlib.h we can see that this entry is for the package name.
+The type of the entry is a STRING.  The offset is an offset from the
+start of the data part of the header to the data associated with this
+entry.  The count indicates that there is only one string associated
+with the entry (which we really already knew since STRING types are
+not allowed to have a count greater than 1).
+
+In our example there would be 32 such 16-byte index entries, followed
+by the data section:
+
+00000210: 72 70 6d 00 32 2e 31 2e 32 00 31 00 52 65 64 20    rpm.2.1.2.1.Red 
+00000220: 48 61 74 20 50 61 63 6b 61 67 65 20 4d 61 6e 61    Hat Package Mana
+00000230: 67 65 72 00 31 e7 cb b4 73 63 68 72 6f 65 64 65    ger.1...schroede
+00000240: 72 2e 72 65 64 68 61 74 2e 63 6f 6d 00 00 00 00    r.redhat.com....
+...
+00000970: 6c 69 62 63 2e 73 6f 2e 35 00 6c 69 62 64 62 2e    libc.so.5.libdb.
+00000980: 73 6f 2e 32 00 00                                  so.2..
+
+The data section begins at byte 528 (4 magic, 4 reserved, 4 index
+entry count, 4 data byte count, 16 * 32 index entries).  At offset 0,
+bytes 528-531 are "rpm" plus a null byte, which is the data for the
+first index entry (the package name).  Following is is the data for
+each of the other entries.  Each string is null terminated, the strings
+in a STRING_ARRAY are also null terminated and are place one after
+another.  The integer types are aligned to appropriate byte boundaries,
+so that the data of INT64 type starts on an 8 byte boundary, INT32
+type starts on a 4 byte boundary, and an INT16 type starts on a 2 byte
+boundary.  For example:
+
+00000060: 00 00 03 ef 00 00 00 06 00 00 00 28 00 00 00 01    ................
+00000070: 00 00 03 f1 00 00 00 04 00 00 00 40 00 00 00 01    ................
+...
+00000240: 72 2e 72 65 64 68 61 74 2e 63 6f 6d 00 00 00 00    r.redhat.com....
+00000250: 00 09 9b 31 52 65 64 20 48 61 74 20 4c 69 6e 75    ....Red Hat Linu
+
+Index entry number 6 is the BUILDHOST, of type STRING.  Index entry
+number 7 is the SIZE, of type INT32.  The corresponding data for entry
+6 end at byte 588 with "....redhat.com\0".  The next piece of data
+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).
+
+Tools
+-----
+
+The tools directory in the RPM sources contains a number of small
+programs that use the RPM library to pick apart packages.  These
+tools are mostly used for debugging, but can also be used to help
+you understand the internals of the RPM package format.
+
+	rpmlead		- extracts the Lead from a package
+	rpmsignature	- extracts the Signature from a package
+	rpmheader	- extracts the Header from a package
+	rpmarchive	- extracts the Archive from a package
+	dump		- displays a header structure in readable format
+
+Given a package foo.rpm you might try:
+
+	rpmlead foo.rpm | od -x
+	rpmsignature foo.rpm | dump
+	rpmheader foo.rpm | dump
+	rpmarchive foo.rpm | zcat | cpio --list
diff --git a/doc/manual/macros b/doc/manual/macros
new file mode 100644
index 000000000..4fcbfd14f
--- /dev/null
+++ b/doc/manual/macros
@@ -0,0 +1,135 @@
+SPEC FILE MACROS
+================
+
+RPM 2.4.104 introduces fully recursive spec file macros.  Simple macros
+do straight text substitution. Parameterized macros include an options
+field, and perform argc/argv processing on white space separated tokens
+to the next newline. During macro expansion, both flags and arguments are
+available as macros which are deleted at the end of macro expansion.
+Macros can be used (almost) anywhere in a spec file, and, in particular,
+in "included file 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.
+
+Defining a Macro
+----------------
+
+To define a macro use:
+
+%define <name>[(opts)] <body>
+
+All whitespace surrounding <body> is removed.  Name may be composed
+of alphanumeric characters, and the character `_' and must be at least
+3 characters in length. A macro without an (opts) field is "simple" in that
+only recursive macro expansion is performed. A parameterized macro contains
+an (opts) field. The opts (i.e. string between parantheses) is passed
+exactly as is to getopts(3) for argc/argv processing at the beginning of
+a macro invocation.  While a parameterized macro is being expanded, the
+following shell-like macros are available:
+
+	%0	the name of the macro being invoked
+	%*	all arguments (unlike shell, not including any processed flags)
+	%#	the number of arguments
+	%{-f}	if present at invocation, the flag f itself
+	%{-f*}	if present at invocation, the argument to flag f
+	%1, %2	the arguments themselves (after getopt(3) processing)
+
+At the end of invocation of a parameterized macro, the above macros are
+(at the moment, silently) discarded.
+
+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
+is "%{-f}" which expands (literally) to "-f" if -f was mentioned when the
+macro was invoked. There are also provisions for including text if flag
+was present using "%{-f:X}". This macro expands to (the expansion of) X
+if the flag was present. The negative form, "%{!-f:Y}", expanding to (the
+expansion of) Y if -f was *not* present, is also supported.
+
+In addition to the "%{...}" form, shell expansion can be performed
+using "%(shell command)". The expansion of "%(...)" is the output of
+(the expansion of) ... fed to /bin/sh. For example, "%(date
++%%y%%m%%d)" expands to the string "YYMMDD" (final newline is
+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.
+
+Builtin Macros
+--------------
+There are several builtin macros (with reserved names) that are needed
+to perform useful operations. The current list is
+
+	%trace		toggle print of debugging information before/after
+			expansion
+	%dump		print the active (i.e. non-covered) macro table
+
+	%{echo:...}	print ... to stderr
+	%{warn:...}	print ... to stderr
+	%{error:...}	print ... to stderr and return BADSPEC
+ 
+	%define ...	define a macro
+	%undefine ...	undefine a macro
+	%global ...	define a macro whose body is available in global context
+
+	%{uncompress:...} expand ... to <file> and test to see if <file> is
+			compressed.  The expansion is
+				cat <file>		# if not compressed
+				gzip -dc <file>		# if gzip'ed
+				bzip2 -dc <file>	# if bzip'ed
+	%{expand:...}	like eval, expand ... to <body> and (re-)expand <body>
+
+	%{S:...}	expand ... to <source> file name
+	%{P:...}	expand ... to <patch> file name
+	%{F:...}	expand ... to <file> file name
+
+Macros may also be automatically included from /usr/lib/rpm/macros.
+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.
+
+Example of a Macro
+------------------
+
+Here is an example %patch definition from /usr/lib/rpm/macros:
+
+%patch(b:p:P:REz:) \
+%define patch_file	%{P:%{-P:%{-P*}}%{!-P:%%PATCH0}} \
+%define patch_suffix	%{!-z:%{-b:--suffix %{-b*}}}%{!-b:%{-z:--suffix %{-z*}}}%{!-z:%{!-b: }}%{-z:%{-b:%{error:Can't specify both -z(%{-z*}) and -b(%{-b*})}}} \
+	%{uncompress:%patch_file} | patch %{-p:-p%{-p*}} %patch_suffix %{-R} %{-E} \
+	...
+
+The first line defines %patch with its options. The body of %patch is
+
+	%{uncompress:%patch_file} | patch %{-p:-p%{-p*}} %patch_suffix %{-R} %{-E}
+
+The body contains 7 macros, which expand as follows
+
+	%{uncompress:...}	copy uncompressed patch to stdout
+	  %patch_file		... the name of the patch file
+	%{-p:...}		if "-p N" was present, (re-)generate "-pN" flag
+	  -p%{-p*}		... note patch-2.1 insists on contiguous "-pN"
+	%patch_suffix		override (default) ".orig" suffix if desired
+	%{-R}			supply -R (reversed) flag if desired
+	%{-E}			supply -E (delete empty?) flag if desired
+
+There are two "private" helper macros:
+
+	%patch_file	the gory details of generating the patch file name
+	%patch_suffix	the gory details of overriding the (default) ".orig"
+
+Using a Macro
+-------------
+
+To use a macro, write:
+
+%<name> ...
+
+or
+
+%{<name>}
+
+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.
diff --git a/doc/manual/queryformat b/doc/manual/queryformat
new file mode 100644
index 000000000..3864cafd1
--- /dev/null
+++ b/doc/manual/queryformat
@@ -0,0 +1,137 @@
+QUERY FORMATS
+=============
+
+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.
+
+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
+of information in the header has a tag associated with it which allows
+RPM to to tell the difference between the name and description of a
+package.
+
+To get a list of all of the tags your version of RPM knows about, run the
+command 'rpm --querytags'. It will print out a list like (but much longer
+then) this:
+
+    RPMTAG_NAME
+    RPMTAG_VERSION
+    RPMTAG_RELEASE
+    RPMTAG_SERIAL
+    RPMTAG_SUMMARY
+    RPMTAG_DESCRIPTION
+    RPMTAG_BUILDTIME
+    RPMTAG_BUILDHOST
+    RPMTAG_INSTALLTIME
+    RPMTAG_SIZE
+
+As all of these tags begin with RPMTAG_, you may omit it from query format
+specifiers and it will be omitted from the rest of this documentation for
+the same reason.
+
+A tag can consist of one element or an array of elements. Each element can
+be a string or number only.
+
+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
+the information section of a query. This means that when both -i and 
+--queryformat are used in a command, the -i is essentially ignored. 
+Additionally, using --queryformat implies -q, so you may omit the -q as well.
+
+The query format is similar to a C style printf string, which the printf(2)
+man page provides a good introduction to. However, as RPM already knows the
+type of data that is being printed, you must omit the type specifier. In
+its place put the tag name you wish to print enclosed in curly braces
+({}). For example, the following RPM command prints the names and sizes
+of all of the packages installed on a system:
+
+    rpm -qa --queryformat "%{NAME} %{SIZE}\n"
+
+If you want to use printf formatters, they go between the % and {. To
+change the above command to print the NAME in the first 30 bytes and
+right align the size to, use:
+
+    rpm -qa --queryformat "%-30{NAME} %10{SIZE}\n"
+
+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
+respectively, with the first element in the size array corresponding
+to the first element in the name array. 
+
+To iterate over a set of parallel arrays, enclose the format to be used
+to print each item in the array within square brackets ([]). For example,
+to print all of the files and their sizes in the slang-devel package
+followed by their sizes, with one file per line, use this command:
+
+    rpm -q --queryformat "[%-50{FILENAMES} %10{FILESIZES}\n]" slang-devel
+
+Note that since the trailing newline is inside of the square brackets, one
+newline is printed for each filename.
+
+A popular query format to try to construct is one that prints the
+name of a package and the name of a file it contains on one line, 
+repeated for every file in the package. This query can be very usefull
+for passing information to any program that's line oriented (such as
+grep or awk). If you try the obvious,
+
+    rpm --queryformat "[%{NAME} %{FILENAMES}\n]" cdp
+
+If you try this, you'll see RPM complain about a "parallel array size 
+mismatch". Internally, all items in RPM are actually arrays, so the NAME
+is a string array containing one element. When you tell RPM to iterate
+over the NAME and FILENAMES elements, RPM notices the two tags have 
+different numbers of elements and complains.
+
+To make this work properly, you need to tell RPM to always print the first
+item in the NAME element. You do this by placing a '=' before the tag
+name, like this:
+
+    rpm --queryformat "[%{=NAME} %{FILENAMES}\n]" cdp
+
+which will give you the expected output.
+
+    cdp /usr/bin/cdp
+    cdp /usr/bin/cdplay
+    cdp /usr/man/man1/cdp.1
+
+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
+of as a number. To compensate, you can specify one of a few different
+formats to use when printing tags by placing a colon followed the formatting 
+name after the tag name. Here are some examples:
+
+    rpm -q --queryformat "%{NAME} %{INSTALLTIME:date}\n" fileutils
+    rpm -q --queryformat "[%{FILEMODES:perms} %{FILENAMES}\n]" rpm
+    rpm -q --queryformat \
+	"[%{REQUIRENAME} %{REQUIREFLAGS:depflags} %{REQUIREVERSION}\n]" \
+	vlock
+
+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.
+
+Query Expressions
+-----------------
+
+Simple conditionals may be evaluated through query expressions. Expressions
+are delimited by %|...|. The only type of expression currently supported
+is a C-like ternary conditional, which provides simple if/then/else
+conditions. For example, the following query format display "present" if
+the SOMETAG tag is present, and "missing" otherwise:
+
+    %|SOMETAG?{present}:{missing}|
+
+Notice that the subformats "present" and "missing" must be inside of curly
+braces.
diff --git a/doc/manual/relocatable b/doc/manual/relocatable
new file mode 100644
index 000000000..82bb36a56
--- /dev/null
+++ b/doc/manual/relocatable
@@ -0,0 +1,53 @@
+RELOCATABLE PACKAGES
+====================
+
+Relocatable packages are a way to give the user a little control
+over the installation location of a package.  For example, a vendor
+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.
+
+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
+programs access *it* (and expect it to be in a certain place), etc.
+If you determine that the location of the package doesn't matter,
+then it can probably be built as "relocatable".
+
+All you need to do to build a relocatable package is put one or more:
+
+  Prefix: <dir>
+
+in your spec file.  The "<dir>" will usually be something like "/usr",
+"/usr/local", or "/opt".  Every file in your %files list must start
+with that prefix.  For example, if you have "Prefix: /usr" and your
+%files list contains "/etc/foo.conf", the build will fail. The fix for
+this is to put
+
+  Prefix: /usr
+  Prefix: /etc
+
+into the spec file so that the /usr and /etc directories may be
+relocated separately when this package is installed.
+
+
+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
+RPM install command line with "--prefix <dir>".  For example, if
+the package in question were going to be installed in "/opt" but
+you don't have enough disk space there (and it is a relocatable
+package), you could install it "--prefix /usr/opt".
+
+If there is more then one Prefix you may relocate each prefix
+separately by using syntax like:
+
+  rpm ... --relocate /opt=/usr/opt --relocate /etc=/usr/etc ...
+
+If any of the Prefixs are not being relocated they can be skipped on
+the command line
+
diff --git a/doc/manual/signatures b/doc/manual/signatures
new file mode 100644
index 000000000..503b0f6d8
--- /dev/null
+++ b/doc/manual/signatures
@@ -0,0 +1,70 @@
+New RPM Signatures
+==================
+
+The 2.1 release of RPM had a few improvements in the area of
+digital package signatures.  The usage of PGP has been cleaned
+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.
+
+PGP
+---
+
+RPM's previous usage of PGP was cumbersome, and only supported
+1024 bit keys.  Both of these problems have been corrected.
+
+Whereas previously you needed many rpmrc entries to clue in
+RPM about keyring locations and such, RPM now behaves as PGP
+users would expect.  The PGPPATH environment variable can be
+used to specify keyring locations.  You can also use a
+"pgp_path:" line in your rpmrc to specify a different value
+for RPM to use for PGPPATH.  If neither of these are used PGP
+uses its default ($HOME/.pgp).
+
+If you just want to verify packages, you do not need any entries
+in your rpmrc (except possibly "pgp_path:").  The minimal rpmrc
+entries to use PGP for package building are:
+
+signature: pgp
+pgp_name: <name to uniquely select the key to use for signing>
+
+Signature Creation
+------------------
+
+Signature creation is the same as previous releases: just add
+a --sign to your build command line.  You can sign a package
+after the package is built with:
+
+rpm --resign <package>
+
+Using --resign removes any previous signature in the package.
+To *add* a signature to a package, leaving all existing
+signatures use:
+
+rpm --addsign <package>
+
+RPM always creates MD5 and SIZE signatures when it build
+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.
+
+Signature Verification
+----------------------
+
+Package signature verification is the same as previous releases:
+
+rpm -K <package>
+
+RPM will verify evey signature in the package, which may include
+more than one PGP signature.  The output indicates what types of
+signatures are being checked.  If any checks fail you'll see a
+"NOT OK" message, and you should be worried.
+
+If you have a package with PGP signatures, but don't have PGP
+installed, but still want to verify it as much as possible, you
+can do:
+
+rpm -K --nopgp <package>
+
+That will cause RPM to skip any PGP signatures, but still check
+any others (currently only MD5 and SIZE).
diff --git a/doc/manual/spec b/doc/manual/spec
new file mode 100644
index 000000000..0b3d465ef
--- /dev/null
+++ b/doc/manual/spec
@@ -0,0 +1,78 @@
+SPEC FILE ADDITIONS
+===================
+
+A few additions have been made to the spec file format.
+
+Summary and Description
+-----------------------
+
+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
+a Summary: line.  The Description: tag is still supported but should
+be changed to a "%description" entry similar to %package and %files.
+At some point in the future support will be removed for "Description:".
+As an example, this spec file fragment:
+
+  Description: Screen drawing library
+  Name: screenlib
+  Version: 1.0
+
+  %package devel
+  Description: Screen drawing library headers and static libs
+
+might be changed to:
+
+  Summary: Screen drawing library
+  Name: screenlib
+  Version: 1.0
+
+  %description
+  The screen drawing library
+  is a handy development tool
+
+  %package devel
+  Summary: Screen drawing library headers and static libs
+
+  %description devel
+  This package contains all of the
+  headers and the static libraries for
+  screenlib.
+
+  You'll only need this package if you
+  are doing development.
+
+The description is free form text, but there are two things to note.
+The first regards reformating.  Lines that begin with white space
+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.
+
+Other 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
+contained in the package.  Some future RPM package tool may make use
+of this.  The Packager: tag is meant to contain the name and email
+address of the person who "maintains" the RPM package (which may be
+different from the person who actually maintains the program the
+package contains).
+
+Files attributes
+---------------
+
+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
+are important while the contents is not (e.g. a log file).
+
+The %config(missingok) indicates that the file need not exist on the
+installed machine. The %config(missingok) is frequently used for files
+like /etc/rc.d/rc2.d/S55named where the (non-)existence of the symlink
+is part of the configuration in %post, and the file may need to be
+removed when this package is removed.  This file is not required to
+exist at either install or uninstall time.
+
+The %config(noreplace) indicates that the file in the package should
+be installed with extension .rpmnew if there is already a file by
+the same name on the installed machine.
+
diff --git a/doc/manual/triggers b/doc/manual/triggers
new file mode 100644
index 000000000..c148f1bca
--- /dev/null
+++ b/doc/manual/triggers
@@ -0,0 +1,124 @@
+TRIGGERS
+========
+
+Triggers provide a well-defined method for packages to interact with one
+another at package install and uninstall time. They are an extension
+of the normal installation scripts (i.e. %pre) which allows one package
+(the "source" of the trigger package [which I often think of as the 
+"triggered package"]) to execute an action when the installation status
+of another package (the "target" of the trigger) changes.
+
+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
+point to /usr/bin/sendmail, but it vmail is installed, the link should 
+instead point to /usr/bin/vmail. If both packages are present, we don't care
+where the link points (realisticaly, sendmail and vmail should conflict
+with one another), while if neither package is installed the link should
+not exist at all.
+
+This can be accomplished by mymailer providing trigger scripts which 
+move the symlink when any of the following occurs:
+
+	1) sendmail is installed
+	2) vmail is installed
+	3) sendmail is removed
+	4) vmail is removed
+
+The first two of these scripts would look like this:
+
+	%triggerin -- sendmail
+	ln -sf /usr/bin/sendmail /etc/mymailer/mailer
+
+	%triggerin -- vmail
+	ln -sf /usr/bin/vmail /etc/mymailer/mailer
+
+These are two installation triggers, triggered by one of sendmail or vmail.
+They are run when:
+
+	1) mymailer is already installed, and sendmail is installed or
+	   upgraded
+	2) mymailer is already installed, and vmail is installed or
+	   upgraded
+	3) sendmail is already installed, and mymailer is installed or
+	   upgraded
+	4) vmail is already installed, and mymailer is installed or
+	   upgraded
+
+For the upgrading, the strategy is a little different. Rather then
+setting the link to point to the trigger, the link is set to point to
+the *other* mailer (if it exists), as follows:
+
+	%triggerun -- sendmail
+	[ $2 = 0 ] || exit 0
+	if [ -f /usr/bin/vmail ]; then
+		ln -sf /usr/bin/vmail /etc/mymailer/mailer
+	else
+		rm -f /etc/mymailer/mailer
+
+	fi
+
+	%triggerun -- vmail
+	[ $2 = 0 ] || exit 0
+	if [ -f /usr/bin/sendmail ]; then
+		ln -sf /usr/bin/sendmail /etc/mymailer/mailer
+	else
+		rm -f /etc/mymailer/mailer
+
+	fi
+
+	%postun
+	[ $1 = 0 ] && rm -f /etc/mymailer/mailer
+
+These trigger scripts get run when:
+
+	1) sendmail is installed, and mymailer is removed
+	2) vmail is installed, and mymailer is removed
+	3) mymailer is installed, and sendmail gets removed
+	4) mymailer is installed, and vmail gets removed
+
+The %postun insures that /etc/mymailer/mailer is removed when mymailer
+is removed (triggers get run at the same time as %preun scripts, so 
+doing this in the %postun is safe). Note that the triggers are testing
+$2 to see if any action should occur. Recall that the $1 passed to regular
+scripts contains the number of instances of the package which will be 
+installed when the operation has completed. $1 for triggers is exactly
+the same -- it is the number of instances of the source (or triggered)
+package which will remain when the trigger has completed. Similarly, $2
+is the number of instances of the target package which will remain. In
+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).
+
+Trigger Syntax
+--------------
+
+Trigger specifications are of the form:
+
+	%trigger{un|in|postun} [[-n] <subpackage>] [-p <program>] -- <trigger>
+
+The -n and -p arguments are the same as for %post scripts.  The
+<trigger> portion is syntactically equivalent to a "Requires"
+specification (version numbers may be used). If multiple items are
+given (comma separated), the trigger is run when *any* of those
+conditions becomes true (the , can be read as "or"). For example:
+
+	%triggerin -n package -p /usr/bin/perl -- fileutils > 3.0, perl < 1.2
+	print "I'm in my trigger!\n";
+
+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).
+
+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
+never be run when the package containing the trigger is removed. 
+
+While this type of trigger is almost never usefull, they allow a package to
+fix errors introduced by the %postun of another package (or by an earlier 
+version of that package).