Update to doxygen-1.2.6 configuration.

Add manual files to Doxfile.in.
lclint annotations.

CVS patchset: 4624
CVS date: 2001/03/14 23:09:09

11 files changed, 299 insertions, 158 deletions

diff --git a/doc/manual/builddependencies b/doc/manual/builddependencies
index 0d6dca6fe..bc09bcd1a 100644
--- a/doc/manual/builddependencies
+++ b/doc/manual/builddependencies
@@ -1,12 +1,17 @@
-As we start updating packages for Red Hat 6.2, I'd like to see packages
-start to make use of build dependencies. Basically build dependencies are
-just like install dependencies, but they are resolved against the build system
-just after parsing the spec file. Syntactically, build dependencies look just
-like install dependencies in a spec file with "Build" prefixed:
+/*! \page builddpendencies How to generate build depedencies
 
+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
+dependencies are just like install dependencies, but they are resolved
+against the build system just after parsing the spec file. Syntactically,
+build dependencies look just like install dependencies in a spec file with
+"Build" prefixed:
+
+\verbatim
 	BuildPrereqs:
 	BuildRequires:
 	BuildConflicts:
+\endverbatim
 
 All the above dependencies include versions, files, existence/range tests, etc.
 The build dependency checking can also be turned off with --nodeps if necessary
@@ -21,6 +26,7 @@ spec files as part of rebuilding packages for Red Hat 6.2.
 Here's a short example of how to generate the package/file names that were used
 while building gnorpm using InDependence:
 
+\verbatim
 	rpm -U /mnt/redhat/comps/powertools/6.2/i386/InDependence-1.0-3.i386.rpm
 	rpm -i /mnt/redhat/comps/dist/6.2/SRPMS/gnorpm-0.9-11.src.rpm
 	cd /usr/src/redhat/SPECS
@@ -29,8 +35,9 @@ while building gnorpm using InDependence:
 	(the build will take longer since both dep and strace are pigs)
 	...
 	grep -- '::' xxx > yyy
+\endverbatim
 
-=========================================================================
+\verbatim
 Aside:	The dep perl wrapper is a "pig" only because it's exec'ing
 		rpm -qf <filename>
         in order to turn filenames into package names. There are easier/faster
@@ -42,10 +49,11 @@ Aside:	The dep perl wrapper is a "pig" only because it's exec'ing
 	same open/execve syscalls using LD_PRELOAD.
 
 	Patches cheerfully accepted :-)
-=========================================================================
+\endverbatim
 
 Here's what's in yyy (<packagename>::<filename> format):
 
+\verbatim
 	ORBit-devel-0.4.95-2::/usr/bin/orbit-config 
 	XFree86-libs-3.3.5-6::/usr/X11R6/lib/libICE.so.6 
 	XFree86-libs-3.3.5-6::/usr/X11R6/lib/libSM.so.6 
@@ -151,15 +159,20 @@ Here's what's in yyy (<packagename>::<filename> format):
 	textutils-2.0-2::/usr/bin/cut 
 	textutils-2.0-2::/usr/bin/tr 
 	zlib-1.1.3-5::/usr/lib/libz.so.1 
+\endverbatim
 
 The information can be used to generate build prerequisites. What is still
 needed is a sensible approach on
 
+\verbatim
 	1) eliminating obvious common dependencies (e.g. libtool, egcs).
 	2) identifying (and removing for now) per-platform build dependencies.
 	3) deciding on whether to add the build dependency on a file or on the
 	package that contains the file.
 	4) if adding a dependency on a package, choosing version ranges as
 	appropriate.
+\endverbatim
 
 but that's up to individual packagers.
+
+*/
diff --git a/doc/manual/buildroot b/doc/manual/buildroot
index 7c9facd65..f31db4764 100644
--- a/doc/manual/buildroot
+++ b/doc/manual/buildroot
@@ -1,18 +1,17 @@
-BUILD ROOT
-==========
+/*! \page buildroot Using a 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
+The build root is very similar to Root: (which is now legacy).
+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
--------------
+<h2>The Spec File</h2>
 
 Simply use
-
+\verbatim
   Buildroot: <dir>
+\endverbatim
 
 in your spec file.  The acutal buildroot used by RPM during the
 build will be available to you (and your %prep, %build, and %install
@@ -22,6 +21,7 @@ proper buildroot.  As with Root:, the files listed in the %files
 section should *not* contain the buildroot.  For example, the
 following hypothetical spec file:
 
+\verbatim
   Name: foo
   ...
   Root: /tmp
@@ -37,12 +37,14 @@ following hypothetical spec file:
   
   %files
   /usr/bin/fooprog
+\endverbatim
 
 would be changed to:
 
+\verbatim
   Name: foo
   ...
-  Buildroot: /tmp
+  BuildRoot: /tmp
   
   %prep
   ...
@@ -55,9 +57,9 @@ would be changed to:
   
   %files
   /usr/bin/fooprog
+\endverbatim
 
-Building With a Build Root
---------------------------
+<h2>Building With a Build Root</h2>
 
 RPM will use the buildroot listed in the spec file as the default
 buildroot.  There are two ways to override this.  First, you can
@@ -65,19 +67,22 @@ 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.
 
-Caveats using Build Roots
--------------------------
+<h2>Caveats using Build Roots</h2>
 
 Care should be taken when using buildroots that the install directory
 is owned by the correct package.  For example the file
 
+\verbatim
 	/usr/lib/perl5/site_perl/MD5.pm
+\endverbatim
 
 is installed by the package perl-MD5.  If we were to use a buildroot
 and specified 
 
+\verbatim
 	%files  
 	/usr/lib/perl5/site_perl
+\endverbatim
 
 we would end up with the directory /usr/lib/perl5/site_perl being
 owned by the library package. This directory is in fact used by ALL
@@ -85,7 +90,9 @@ perl libriares and should be owned by the package for perl not any of
 its libraries. It is important that the %files command specifies all
 the known directories explicitly. So this would be preferable:
 
+\verbatim
 	/usr/lib/perl5/site_perl/*
+\endverbatim
 
 Since we only want the files and directories that the package perl-MD5
 installed into /usr/lib/perl5/site_perl/ to be owned by the package.
@@ -111,3 +118,5 @@ contains file names already used by other packages on the system then
 RPM will warn you of the problem and give a fatal error. This error can
 be overriden with --force and the installed file will be replaced by the
 new file and when the new package is removed the file will be removed as well.
+
+*/
diff --git a/doc/manual/dependencies b/doc/manual/dependencies
index 4f5b3f33a..7e268e03d 100644
--- a/doc/manual/dependencies
+++ b/doc/manual/dependencies
@@ -1,5 +1,4 @@
-DEPENDENCIES
-============
+/*! \page dependencies Dependencies
 
 Dependencies provide a way for a package builder to require other
 packages or capabilities to be installed before or simultaneously
@@ -7,17 +6,20 @@ 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
-------------------
+<h2>Requiring Packages</h2>
 
 To require packages, use:
 
+\verbatim
 	Requires: python perl
+\endverbatim
 
 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,
 
+\verbatim
 	Requires: python >= 1.3, perl
+\endverbatim
 
 would do the trick. Again, the ',' in the line is optional.  Instead of
 '>=', you may also use '<', '>', '<=', or '='.
@@ -30,12 +32,16 @@ to indicate beta versions.
 
 To work around this, you may specify an epoch number for a package like this:
 
+\verbatim
 	Epoch: 23
+\endverbatim
 
 If a Requires: line needs to include an epoch in the comparison, then
 the line should be written like
 
+\verbatim
 	Requires: somepackage = 23:version
+\endverbatim
 
 You can't continue a "Requires: " line. If you have multiple
 "Requires: " lines then the package requires all packages mentioned on
@@ -43,14 +49,17 @@ all of the lines to be installed. Max line length is probably 8K.
 
 The full syntax for specifying a dependency on an epoch, version and release
 is
+\verbatim
 	[epoch:]version[-release]
+\endverbatim
 where
+\verbatim
 	epoch	(optional) number, with assumed default of 0 if not supplied
 	version	(required) can contain any character except '-'
 	release	(optional) can contain any character except '-'
+\endverbatim
 
-Prereqs
--------
+<h2>Prereqs</h2>
 
 Prereqs are slightly different than requires. If multiple packages are
 given on a single command line, then RPM will rearrange the package
@@ -60,8 +69,7 @@ the package itself is installed. Otherwise prereqs are identical to
 requires.
 
 
-Virtual Packages
-----------------
+<h2>Virtual Packages</h2>
 
 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
@@ -69,23 +77,28 @@ 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:
 
+\verbatim
 	Requires: lda
+\endverbatim
 
 This will match either a package called lda (as mentioned above), or any
 package which contains:
 
+\verbatim
 	Provides: lda
+\endverbatim
 
 in its .spec file. No version numbers may be used with virtual packages.
 
 Virtual packages are often used to supply file dependencies such as /bin/sh
 on machines that are only partly managed by rpm. A virtual package with
+\verbatim
 	Provides: /bin/sh
+\endverbatim
 differs from a package that has /bin/sh in the %files list in that the
 package can be safely removed without removing /bin/sh.
 
-Automatic Dependencies
-----------------------
+<h2>Automatic Dependencies</h2>
 
 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
@@ -105,8 +118,7 @@ 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)
------------------------
+<h2>Interpreters and Shells (to be implemented)</h2>
 
 Modules for interpreted languages like perl and tcl impose additional
 dependency requirements on packages. A script written for an interpreter
@@ -117,26 +129,35 @@ module name collisions between interpreters, module names are enclosed within
 parentheses and a conventional interpreter specific identifier is pre-pended:
 
 
+\verbatim
   Provides: perl(MIME-Base64), perl(Mail-Header)-1-09
 
   Requires: perl(Carp), perl(IO-Wrap) = 4.5
+\endverbatim
 
 
 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)
 
+\verbatim
 	Mail-Header >= 1.01
 	perl(Carp) >= 3.2
 	perl(IO-Wrap) == 4.5 or perl(IO-Wrap)-4.5
+\endverbatim
 
 the output from find-provides is
+\verbatim
 	Foo-0.9
 	perl(Widget)-0-1
+\endverbatim
 
 The per-interpreter automatic module detectors will normally be located in
+\verbatim
 	/usr/lib/rpm/{perl,tcl}/find-{provides,requires}
 with appropriate per-interpreter hooks into
+\verbatim
 	/usr/lib/rpm/find-{provides,requires}
+\endverbatim
 
 Notice that shell dependencies will require that all executable programs be
 tracked by the dependency processing system. Since a shell script depends on
@@ -144,8 +165,7 @@ all the programs which it runs. In this way executables are much like shared
 libraries for shell scripts.
 
 
-Installing and Erasing Packages with Dependencies
--------------------------------------------------
+<h2>Installing and Erasing Packages with Dependencies</h2>
 
 For the most part, dependencies should be transparent to the user. However,
 a few things will change.
@@ -153,18 +173,19 @@ 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:
 
+\verbatim
     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
+\endverbatim
 
 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
----------
+<h2>Conflicts</h2>
 
 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
@@ -175,13 +196,14 @@ 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
+\verbatim
+	Conflicts: sendmail
+\endverbatim
 
 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
---------------------------
+<h2>Querying with Dependencies</h2>
 
 Two new query information selection options are now available. The first, 
 --provides, prints a list of all of the capabilities a package provides. 
@@ -195,12 +217,13 @@ 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
-----------------------
+<h2>Verifying Dependencies</h2>
 
-As of RPM 2.2.2, -V (aka -y, --verify) verifies package dependencies
+As of RPM 2.2.2, -V (aka --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
index 987faf95a..9281add70 100644
--- a/doc/manual/format
+++ b/doc/manual/format
@@ -1,5 +1,4 @@
-RPM File Format
-===============
+/*! \page pkgformat Package 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
@@ -12,24 +11,26 @@ LIBRARY!!
 The RPM file format covers both source and binary packages.  An RPM
 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
-. Archive   -- compressed archive of all the files in the package
+. Payload   -- compressed archive of all the files in the package
+\endverbatim
 
 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
-----
+<h2>Lead</h2>
 
 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:
 
+\code
 struct rpmlead {
     unsigned char magic[4];
     unsigned char major, minor;
@@ -40,11 +41,14 @@ struct rpmlead {
     short signature_type;
     char reserved[16];
 };
+\endcode
 
 and is illustrated with one pulled from the rpm-2.1.2-1.i386.rpm
 package:
 
+\verbatim
 00000000: ed ab ee db 03 00 00 00
+\endverbatim
 
 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)
@@ -53,7 +57,9 @@ 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.
 
+\verbatim
 00000008: 00 01 72 70 6d 2d 32 2e    ..rpm-2.
+\endverbatim
 
 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
@@ -63,6 +69,7 @@ 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.
 
+\verbatim
 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    ........
@@ -71,6 +78,7 @@ package, padded with null (0) bytes.
 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    ........
+\endverbatim
 
 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,14 +86,15 @@ package was built for.  In this case, 1 == Linux.  The next 2 bytes
 RPM what to expect in the Signature.  For version 3.0 packages, this
 is 5, which indicates the new "Header-style" signatures.
 
+\verbatim
 00000050: 04 00 00 00 68 e6 ff bf    ........
 00000058: ab ad 00 08 3c eb ff bf    ........
+\endverbatim
 
 The remaining 16 bytes (80-95) are currently unused and are reserved
 for future expansion.
 
-Signature
----------
+<h2>Signature</h2>
 
 A 3.0 format signature (denoted by signature type 5 in the Lead), uses
 the same structure as the Header.  For historical reasons, this
@@ -99,11 +108,13 @@ The Signature can contain multiple signatures, of different types.
 There are currently only three types, each with its own tag in the
 header structure:
 
+\verbatim
 	Name	Tag	Header Type
 	----	----	-----------
 	SIZE	1000	INT_32
 	MD5	1001	BIN
 	PGP	1002	BIN
+\endverbatim
 
 The MD5 signature is 16 bytes, and the PGP signature varies with
 the size of the PGP key used to sign the package.
@@ -111,8 +122,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.
 
-Header
-------
+<h2>Header</h2>
 
 The Header contains all the information about a package: name,
 version, file list, etc.  It uses the same "header structure" as the
@@ -121,14 +131,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.
 
-Archive
--------
+<h2>Payload</h2>
 
-The Archive is currently a gzipped cpio archive.  The cpio
+The Payload is currently a gzipped cpio archive.  The cpio
 archive type used is SVR4 with a CRC checksum.
 
-The Header Structure
---------------------
+<h2>The Header Structure</h2>
 
 The header structure is a little complicated, but actually performs a
 very simple function.  It acts almost like a small database in that it
@@ -141,6 +149,7 @@ 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:
 
+\verbatim
 	Type		Number
 	----		------
 	NULL		0
@@ -152,6 +161,8 @@ currently 9 types:
 	STRING		6
 	BIN		7
 	STRING_ARRAY	8
+	I18NSTRING_TYPE	9
+\endverbatim
 
 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
@@ -162,12 +173,16 @@ STRING_ARRAY.
 Altogether, the tag, type, count, and data are called an "Entry" or
 "Header Entry".
 
+\verbatim
 00000000: 8e ad e8 01 00 00 00 00    ........
+\endverbatim
 
 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.
 
+\verbatim
 00000008: 00 00 00 20 00 00 07 77    ........
+\endverbatim
 
 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
@@ -175,7 +190,9 @@ 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.
 
+\verbatim
 00000010: 00 00 03 e8 00 00 00 06 00 00 00 00 00 00 00 01    ................
+\endverbatim
 
 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
@@ -192,6 +209,7 @@ 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:
 
+\verbatim
 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
@@ -199,6 +217,7 @@ by the data section:
 ...
 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..
+\endverbatim
 
 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,
@@ -211,11 +230,13 @@ 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:
 
+\verbatim
 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
+\endverbatim
 
 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
@@ -224,23 +245,28 @@ 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
------
+<h2>Tools</h2>
 
 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.
 
+\verbatim
 	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
+\endverbatim
 
 Given a package foo.rpm you might try:
 
+\verbatim
 	rpmlead foo.rpm | od -x
 	rpmsignature foo.rpm | dump
 	rpmheader foo.rpm | dump
 	rpmarchive foo.rpm | zcat | cpio --list
+\endverbatim
+
+*/
diff --git a/doc/manual/macros b/doc/manual/macros
index cd8ea3eb1..781ceda70 100644
--- a/doc/manual/macros
+++ b/doc/manual/macros
@@ -1,22 +1,22 @@
-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
-----------------
+/*! \page macros Macro syntax
+
+RPM has 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.
+
+<h2>Defining a Macro</h2>
 
 To define a macro use:
 
-%define <name>[(opts)] <body>
+\verbatim
+	%define <name>[(opts)] <body>
+\endverbatim
 
 All whitespace surrounding <body> is removed.  Name may be composed
 of alphanumeric characters, and the character `_' and must be at least
@@ -27,18 +27,19 @@ 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:
 
+\verbatim
 	%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)
+\endverbatim
 
 At the end of invocation of a parameterized macro, the above macros are
 (at the moment, silently) discarded.
 
-Writing a Macro
----------------
+<h2>Writing a Macro</h2>
 
 Within the body of a macro, there are several constructs that permit
 testing for the presence of optional parameters. The simplest construct
@@ -56,11 +57,12 @@ 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
---------------
+<h2>Builtin Macros</h2>
+
 There are several builtin macros (with reserved names) that are needed
 to perform useful operations. The current list is
 
+\verbatim
 	%trace		toggle print of debugging information before/after
 			expansion
 	%dump		print the active (i.e. non-covered) macro table
@@ -83,29 +85,35 @@ to perform useful operations. The current list is
 	%{S:...}	expand ... to <source> file name
 	%{P:...}	expand ... to <patch> file name
 	%{F:...}	expand ... to <file> file name
+\endverbatim
 
 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
-------------------
+<h2>Example of a Macro</h2>
 
 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} \
+\verbatim
+	%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} \
 	...
+\endverbatim
+
 
 The first line defines %patch with its options. The body of %patch is
 
+\verbatim
 	%{uncompress:%patch_file} | patch %{-p:-p%{-p*}} %patch_suffix %{-R} %{-E}
+\endverbatim
 
 The body contains 7 macros, which expand as follows
 
+\verbatim
 	%{uncompress:...}	copy uncompressed patch to stdout
 	  %patch_file		... the name of the patch file
 	%{-p:...}		if "-p N" was present, (re-)generate "-pN" flag
@@ -113,29 +121,34 @@ The body contains 7 macros, which expand as follows
 	%patch_suffix		override (default) ".orig" suffix if desired
 	%{-R}			supply -R (reversed) flag if desired
 	%{-E}			supply -E (delete empty?) flag if desired
+\endverbatim
 
 There are two "private" helper macros:
 
+\verbatim
 	%patch_file	the gory details of generating the patch file name
 	%patch_suffix	the gory details of overriding the (default) ".orig"
+\endverbatim
 
-Using a Macro
--------------
+<h2>Using a Macro</h2>
 
 To use a macro, write:
 
-%<name> ...
+\verbatim
+	%<name> ...
+\endverbatim
 
 or
 
-%{<name>}
+\verbatim
+	%{<name>}
+\endverbatim
 
 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.
 
-Command Line Options
---------------------
+<h2>Command Line Options</h2>
 
 When the command line option "--define 'macroname value'" allows the
 user to specify the value that a macro should have during the build.
@@ -144,16 +157,17 @@ users who accidentally type the leading % but this should not be
 relied upon.
 
 Evaluating a macro can be difficult outside of an rpm execution context. If
-you wish to see the expanded value of a macro, you may use
-	"--eval '<macro expression>'"
+you wish to see the expanded value of a macro, you may use the option
+\verbatim
+	--eval '<macro expression>'
+\endverbatim
 that will read rpm config files and print the macro expansion on stdout.
 
 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.
  
-RPM Configuration using Macros
---------------------------------
+<h2>Configuration using Macros</h2>
 
 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"
@@ -165,6 +179,7 @@ spec file parsing.
 
 Here's an example to illustrate configuration using macros:
 
+\verbatim
    Old way:
 	In /etc/rpmrc and/or ~/.rpmrc you put
 		something:      some_value
@@ -172,9 +187,11 @@ Here's an example to illustrate configuration using macros:
    New way:
 	In /etc/rpm/macros and/or ~/.rpmmacros
 		%_something     some_value
+\endverbatim
 
 Here are 2 common FAQ for experienced users of rpm:
 
+\verbatim
   1) --rcfile works differently.
     Old way:	rpm --rcfile whatever
     New way:	rpm --rcfile /usr/lib/rpm/rpmrc:whatever
@@ -190,13 +207,14 @@ Here are 2 common FAQ for experienced users of rpm:
 		macrofiles:     /usr/lib/rpm/macros: ... :~/.rpmmacros
 	~/.rpmmacros contains
 		%_topdir        whatever
+\endverbatim
 
-Macro Analogues of Autoconf Variables
--------------------------------------
+<h2>Macro Analogues of Autoconf Variables</h2>
 
 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:
 
+\verbatim
     %_prefix		/usr
     %_exec_prefix	%{_prefix}
     %_bindir		%{_exec_prefix}/bin
@@ -211,4 +229,6 @@ packaging similar to the autoconf variables that are used in building packages:
     %_oldincludedir	/usr/include
     %_infodir		%{_prefix}/include
     %_mandir		%{_prefix}/man
+\endverbatim
 
+*/
diff --git a/doc/manual/multiplebuilds b/doc/manual/multiplebuilds
index 3557b2459..3db75fb52 100644
--- a/doc/manual/multiplebuilds
+++ b/doc/manual/multiplebuilds
@@ -1,4 +1,4 @@
-(From Ken Estes <kestes@staff.mail.com>)
+/*! \page multiplebuilds Multiple build areas
 
 It is possible to run several RPM builds on the same machine using
 separate RPM databases.  On my build machine I have several build
@@ -7,35 +7,41 @@ interfere with each other.  Each build behaves as if it was running on
 its own machine and no build area knows about the RPM database which
 actually configures the machine.
 
-1) First setup a "topdir" in a prefix other then where RPM is
+First, setup a "topdir" in a prefix other then where RPM is
 installed.  You will need to make the directories.  They need to be
 writable by the account which will do the building, typically they
 are owned by the buildmaster account and set to permissions
 755.
 
+\verbatim
         BUILD RPMS SOURCES SPECS SRPMS
+\endverbatim
 
-2) Next you will need to decide where the database files live. I suggest
+Next, you will need to decide where the database files live. I suggest
 putting them in a separate directory under "topdir".  I call my
 directory DB and it has the same owner and permissions as the other
 directories.
 
-3) Each separate build area needs a rpmrc.  This will need to specify
-the new topdir and dbpath.  If you will be building the same packages
-in different work areas you will also need to specify a tmppath into
-the topdir.  I suggest either making tmppath be the same as the BUILD
-directory or adding another directory called BUILDROOT for it in the
-topdir.
+Each separate build area needs a rpmrc and macro configuration file. This
+will need to specify the new topdir and dbpath.  If you will be building
+the same packages in different work areas you will also need to specify a
+tmppath into the topdir.  I suggest either making tmppath be the same as
+the BUILD directory or adding another directory called BUILDROOT for it
+in the topdir.
 
-4) keeping track of the correct rpmrc for each build area can be
+Keeping track of the correct rpmrc for each build area can be
 difficult.  To make my life easier I make a small shell script with the
 topdir hard coded inside:
 
+\verbatim
         #!/bin/sh
         /bin/rpm --rcfile /topdir/rpmrc "$@"
         exit $?
+\endverbatim
 
 I call the shell script rpm and it lives in the topdir.  Each time I
 wish to use a particular build area I just ensure that the build area
 is first in my path so that when I run "rpm" I get the regular rpm
 binary but I am using the local build areas rpmrc.
+
+*/
diff --git a/doc/manual/queryformat b/doc/manual/queryformat
index 3864cafd1..d088b573f 100644
--- a/doc/manual/queryformat
+++ b/doc/manual/queryformat
@@ -1,12 +1,10 @@
-QUERY FORMATS
-=============
+/*! \page queryformat 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
-----
+<h2>Tags</h2>
 
 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
@@ -18,6 +16,7 @@ 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:
 
+\verbatim
     RPMTAG_NAME
     RPMTAG_VERSION
     RPMTAG_RELEASE
@@ -28,6 +27,7 @@ then) this:
     RPMTAG_BUILDHOST
     RPMTAG_INSTALLTIME
     RPMTAG_SIZE
+\endverbatim
 
 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
@@ -36,8 +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.
 
-Query Formats
--------------
+<h2>Query Formats</h2>
 
 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
@@ -52,16 +51,19 @@ 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:
 
+\verbatim
     rpm -qa --queryformat "%{NAME} %{SIZE}\n"
+\endverbatim
 
 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:
 
+\verbatim
     rpm -qa --queryformat "%-30{NAME} %10{SIZE}\n"
+\endverbatim
 
-Arrays
-------
+<h2>Arrays</h2>
 
 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
@@ -73,18 +75,22 @@ 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:
 
+\verbatim
     rpm -q --queryformat "[%-50{FILENAMES} %10{FILESIZES}\n]" slang-devel
+\endverbatim
 
 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
+repeated for every file in the package. This query can be very useful
 for passing information to any program that's line oriented (such as
 grep or awk). If you try the obvious,
 
+\verbatim
     rpm --queryformat "[%{NAME} %{FILENAMES}\n]" cdp
+\endverbatim
 
 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
@@ -96,16 +102,19 @@ 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:
 
+\verbatim
     rpm --queryformat "[%{=NAME} %{FILENAMES}\n]" cdp
+\endverbatim
 
 which will give you the expected output.
 
+\verbatim
     cdp /usr/bin/cdp
     cdp /usr/bin/cdplay
     cdp /usr/man/man1/cdp.1
+\endverbatim
 
-Formatting Tags
----------------
+<h2>Formatting Tags</h2>
 
 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
@@ -113,17 +122,18 @@ 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:
 
+\verbatim
     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
+\endverbatim
 
 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
------------------
+<h2>Query Expressions</h2>
 
 Simple conditionals may be evaluated through query expressions. Expressions
 are delimited by %|...|. The only type of expression currently supported
@@ -131,7 +141,11 @@ 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:
 
+\verbatim
     %|SOMETAG?{present}:{missing}|
+\endverbatim
 
 Notice that the subformats "present" and "missing" must be inside of curly
 braces.
+
+*/
diff --git a/doc/manual/relocatable b/doc/manual/relocatable
index 82bb36a56..ecc503936 100644
--- a/doc/manual/relocatable
+++ b/doc/manual/relocatable
@@ -1,5 +1,4 @@
-RELOCATABLE PACKAGES
-====================
+/*! \page relocateable Relocateable packages
 
 Relocatable packages are a way to give the user a little control
 over the installation location of a package.  For example, a vendor
@@ -7,8 +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.
 
-Building a Relocatable Package
-------------------------------
+<h2>Building a Relocatable Package</h2>
 
 Not all software can be "relocatable".  Before continuing you should
 think about how the program works, what files it accesses, what other
@@ -18,7 +16,9 @@ then it can probably be built as "relocatable".
 
 All you need to do to build a relocatable package is put one or more:
 
+\verbatim
   Prefix: <dir>
+\endverbatim
 
 in your spec file.  The "<dir>" will usually be something like "/usr",
 "/usr/local", or "/opt".  Every file in your %files list must start
@@ -26,15 +26,16 @@ 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
 
+\verbatim
   Prefix: /usr
   Prefix: /etc
+\endverbatim
 
 into the spec file so that the /usr and /etc directories may be
 relocated separately when this package is installed.
 
 
-Installing Relocatable Packages
--------------------------------
+<h2>Installing Relocatable Packages</h2>
 
 By default, RPM will install a relocatable package in the prefix
 directory listed in the spec file.  You can override this on the
@@ -46,8 +47,11 @@ 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:
 
+\verbatim
   rpm ... --relocate /opt=/usr/opt --relocate /etc=/usr/etc ...
+\endverbatim
 
 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
index 39c08f5e7..22f5a78cd 100644
--- a/doc/manual/signatures
+++ b/doc/manual/signatures
@@ -1,5 +1,4 @@
-New RPM Signatures
-==================
+/*! \page signatures Signature header
 
 The 2.1 release of RPM had a few improvements in the area of
 digital package signatures.  The usage of PGP has been cleaned
@@ -7,8 +6,7 @@ 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
----
+<h2>PGP</h2>
 
 RPM's previous usage of PGP was cumbersome, and only supported
 1024 bit keys.  Both of these problems have been corrected.
@@ -23,40 +21,48 @@ uses its default ($HOME/.pgp).
 
 If you just want to verify packages, you need to supply values
 for the macros
+\verbatim
 	%_pgpbin	the path to the pgp executable
 	%_signature	the type of signature to use
+\endverbatim
 
 In order to be able to sign packages, you may also have to
 supply values for
+\verbatim
 	%_pgp_name	the pgp signature to use for signing
 	%_pgp_path	the path to the key ring
+\endverbatim
 
-Signature Creation
-------------------
+<h2>Signature Creation</h2>
 
 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>
+\verbatim
+	rpm --resign <package>
+\endverbatim
 
 Using --resign removes any previous signature in the package.
 To *add* a signature to a package, leaving all existing
 signatures use:
 
-rpm --addsign <package>
+\verbatim
+	rpm --addsign <package>
+\endverbatim
 
 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
-----------------------
+<h2>Signature Verification</h2>
 
 Package signature verification is the same as previous releases:
 
-rpm -K <package>
+\verbatim
+	rpm -K <package>
+\endverbatim
 
 RPM will verify evey signature in the package, which may include
 more than one PGP signature.  The output indicates what types of
@@ -67,7 +73,11 @@ 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>
+\verbatim
+	rpm -K --nopgp <package>
+\endverbatim
 
 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
index 1ee780ed6..71c905e74 100644
--- a/doc/manual/spec
+++ b/doc/manual/spec
@@ -1,10 +1,8 @@
-SPEC FILE ADDITIONS
-===================
+/*! \page specfile Spec file tags
 
 A few additions have been made to the spec file format.
 
-Summary and Description
------------------------
+<h2>Summary and Description</h2>
 
 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
@@ -13,15 +11,18 @@ 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:
 
+\verbatim
   Description: Screen drawing library
   Name: screenlib
   Version: 1.0
 
   %package devel
   Description: Screen drawing library headers and static libs
+\endverbatim
 
 might be changed to:
 
+\verbatim
   Summary: Screen drawing library
   Name: screenlib
   Version: 1.0
@@ -40,6 +41,7 @@ might be changed to:
 
   You'll only need this package if you
   are doing development.
+\endverbatim
 
 The description is free form text, but there are two things to note.
 The first regards reformating.  Lines that begin with white space
@@ -47,8 +49,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.
 
-Other Tags
-----------
+<h2>Other Tags</h2>
 
 Two new tags are "URL:" and "Packager:".  "URL:" is a place to put a
 URL for more information and/or documentation on the software
@@ -58,8 +59,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).
 
-Files Attributes
-----------------
+<h2>Files Attributes</h2>
 
 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
@@ -76,8 +76,7 @@ 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.
 
-Fine Adjustment of Automatic Dependencies
------------------------------------------
+<h2>Fine Adjustment of Automatic Dependencies</h2>
 
 Rpm currently supports separate "Autoreq:" and "Autoprov:" tags in a
 spec file to independently control the running of find-requires and
@@ -88,10 +87,16 @@ installed on the target machine even though their intended use was
 optional. To rectify the situation you may turn off requirements when
 building the package by putting
 
+\verbatim
 	Autoreq: 0 
+\endverbatim
 
 in your spec file. Any and all requirements should be added manually using the
 
+\verbatim
 	Requires: depend1, ..., dependN
+\endverbatim
 
 in this case.
+
+*/
diff --git a/doc/manual/triggers b/doc/manual/triggers
index 40f90316d..733332733 100644
--- a/doc/manual/triggers
+++ b/doc/manual/triggers
@@ -1,5 +1,4 @@
-TRIGGERS
-========
+/*! \page triggers Trigger scriptlets
 
 Triggers provide a well-defined method for packages to interact with one
 another at package install and uninstall time. They are an extension
@@ -8,8 +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.
 
-A Simple Example
-----------------
+<h2>A Simple Example</h2>
 
 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
@@ -22,22 +20,27 @@ not exist at all.
 This can be accomplished by mymailer providing trigger scripts which 
 move the symlink when any of the following occurs:
 
+\verbatim
 	1) sendmail is installed
 	2) vmail is installed
 	3) sendmail is removed
 	4) vmail is removed
+\endverbatim
 
 The first two of these scripts would look like this:
 
+\verbatim
 	%triggerin -- sendmail
 	ln -sf /usr/bin/sendmail /etc/mymailer/mailer
 
 	%triggerin -- vmail
 	ln -sf /usr/bin/vmail /etc/mymailer/mailer
+\endverbatim
 
 These are two installation triggers, triggered by one of sendmail or vmail.
 They are run when:
 
+\verbatim
 	1) mymailer is already installed, and sendmail is installed or
 	   upgraded
 	2) mymailer is already installed, and vmail is installed or
@@ -46,11 +49,13 @@ They are run when:
 	   upgraded
 	4) vmail is already installed, and mymailer is installed or
 	   upgraded
+\endverbatim
 
 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:
 
+\verbatim
 	%triggerun -- sendmail
 	[ $2 = 0 ] || exit 0
 	if [ -f /usr/bin/vmail ]; then
@@ -71,13 +76,16 @@ the *other* mailer (if it exists), as follows:
 
 	%postun
 	[ $1 = 0 ] && rm -f /etc/mymailer/mailer
+\endverbatim
 
 These trigger scripts get run when:
 
+\verbatim
 	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
+\endverbatim
 
 The %postun insures that /etc/mymailer/mailer is removed when mymailer
 is removed (triggers get run at the same time as %preun scripts, so 
@@ -92,12 +100,13 @@ 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
---------------
+<h2>Trigger Syntax</h2>
 
 Trigger specifications are of the form:
 
+\verbatim
 	%trigger{un|in|postun} [[-n] <subpackage>] [-p <program>] -- <trigger>
+\endverbatim
 
 The -n and -p arguments are the same as for %post scripts.  The
 <trigger> portion is syntactically equivalent to a "Requires"
@@ -105,30 +114,31 @@ 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:
 
+\verbatim
 	%triggerin -n package -p /usr/bin/perl -- fileutils > 3.0, perl < 1.2
 	print "I'm in my trigger!\n";
+\endverbatim
 
 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
----------------
+<h2>An Unusual Case</h2>
 
 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
+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).
 
-Order of Script Execution
--------------------------
+<h2>Order of Script Execution</h2>
 
 For reference, here's the order in which scripts are executed on a single
 package upgrade:
 
+\verbatim
   new-%pre	for new version of package being installed
   ...		(all new files are installed)
   new-%post	for new version of package being installed
@@ -145,4 +155,5 @@ package upgrade:
   old-%triggerpostun
   any-%triggerpostun (%triggerpostun from other packages set off by old un
 		install)
-
+\endverbatim
+*/