Another round of manpage updates.

6 files changed, 234 insertions, 45 deletions

diff --git a/doc/PKGBUILD.5 b/doc/PKGBUILD.5
index 4a296e6e..c727c1a4 100644
--- a/doc/PKGBUILD.5
+++ b/doc/PKGBUILD.5
@@ -14,7 +14,7 @@ installed with \fBpacman\fR.
 \fBNOTE:\fR If you have a local copy of the Arch Build System (ABS) tree
 on your computer, you can copy the \*(PB.proto file to your new package
 build directory and edit it from there.  To acquire/sync the ABS tree, use
-the \fBabs\fR script included with pacman/makepkg.
+the \fBabs\fR script included with \fBpacman\fP.
 
 .SS Quick \*(PB Explanation
 For an example of a \*(PB, see the \fBEXAMPLE\fR section.
@@ -41,9 +41,9 @@ The \fIbackup\fR array specifies files that should be treated specially
 when removing or upgrading packages.  See \fBHANDLING CONFIG FILES\fR in
 the \fIpacman\fR manpage for more information on this.
 
-The \fIsource()\fR array tells makepkg which files to download or extract before
-compiling begins. The \fImd5sums()\fR array provides md5sums for each of these
-files. These are used to validate the integrity of the source files.
+The \fIsource()\fR array tells \fBmakepkg\fP which files to download or extract
+before compiling begins. The \fImd5sums()\fR array provides md5sums for each of
+these files. These are used to validate the integrity of the source files.
 
 The \fIbuild\fR function is what actually does the work of putting the package
 together. Sometimes this is as simple as a configure, make, make install (to
@@ -74,8 +74,8 @@ maintainers to make updates to the package's configure flags, for example.
 .B pkgdesc
 This should be a brief description of the package and its functionality.
 
-." Not entirely applicable, and we can do this better anyway.  pacman does
-." actuall support localized descriptions, though, but i don't think makepkg does.
+." Not entirely applicable, and we can do this better anyway. pacman does
+." actuall support localized descriptions, though, but I don't think makepkg does.
 ." .TP
 ." .B pkgdesc_localized \fI(array)\fR
 ." Array of the localized package descriptions. The format is the following:
@@ -100,9 +100,9 @@ licenses are applied, use the array form: \fBlicenses=('GPL' 'FDL')\fR
 
 .TP
 .B install
-Specifies a special install script that is to be included in the package.
-This file should reside in the same directory as the \*(PB, and will be
-copied into the package by makepkg. It does not need to be included in the
+Specifies a special install script that is to be included in the package. This
+file should reside in the same directory as the \fB\*(PB\fP, and will be copied
+into the package by \fBmakepkg\fP. It does not need to be included in the
 \fIsource\fR array. (eg, install=pkgname.install)
 
 .TP
@@ -121,16 +121,20 @@ which use compressed data which id downloaded via the \fIsource\fR array.
 .TP
 .B md5sums \fI(array)\fR
 If this field is present, it should contain an MD5 hash for every source file
-specified in the \fIsource\fR array (in the same order). \fImakepkg\fR will use
+specified in the \fIsource\fR array (in the same order). \fBmakepkg\fR will use
 this to verify source file integrity during subsequent builds. To easily
-generate md5sums, first build using the \*(PB then run
-\fBmakepkg -g >>\*(PB\fR. Then you can edit the \*(PB and move the
-\fImd5sums\fR line from the bottom to an appropriate location.
-\fBNOTE:\fR makepkg supports multiple integrity algorithms and their
-corresponding arrays (i.e. sha1sums for the SHA1 algorithm), however official
+generate md5sums, first build using the \*(PB then run "makepkg -g >> \*(PB".
+Then edit the \*(PB and move the \fImd5sums\fR line to an appropriate location.
+NOTE: \fBmakepkg\fP supports multiple integrity algorithms and their
+corresponding arrays (i.e. sha1sums for the SHA1 algorithm); however, official
 packages use only md5sums for the time being.
 
 .TP
+.B sha1sums, etc.
+These are alternative integrity checks that \fBmakepkg\fP supports, as noted in
+\fBmd5sums\fP above.
+
+.TP
 .B groups \fI(array)\fR
 This is an array of symbolic names that represent groups of packages, allowing
 you to install multiple packages by requesting a single target. For example,
@@ -144,9 +148,9 @@ This array defines on which architectures the given package is available.
 .B backup \fI(array)\fR 
 A space-delimited array of filenames (without a preceding slash). The
 \fIbackup\fR line will be propagated to the package meta-info file for
-pacman. This will designate all files listed there to be backed up if this
-package is ever removed from a system. See \fBHANDLING CONFIG FILES\fR in
-the \fIpacman\fR manpage for more information.
+\fBpacman\fP. This will designate all files listed there to be backed up if
+this package is ever removed from a system. See \fBHANDLING CONFIG FILES\fR in
+the \fBpacman\fR manpage for more information.
 
 .TP
 .B depends \fI(array)\fR 
@@ -184,15 +188,18 @@ upgrade, due to the differing package names. \fIreplaces\fR handles this.
 
 .TP
 .B options \fI(array)\fR
-This array allows you to override some of makepkg's default behaviour
+This array allows you to override some of \fBmakepkg\fP's default behavior
 when building packages. To set an option, just include the option name
 in the \fBoptions\fR array.
-See \fBmakepkg (8)\fR for details on the options array.
+See
+.BR makepkg (8)
+for details on the options array.
 
 .SS Install/Upgrade/Remove Scripting
-Pacman has the ability to store and execute a package-specific script when it
-installs, removes, or upgrades a package.  This allows a package to "configure
-itself" after installation and do the opposite right before it is removed.
+\fBPacman\fP has the ability to store and execute a package-specific script
+when it installs, removes, or upgrades a package.  This allows a package to
+"configure itself" after installation and do the opposite right before it is
+removed.
 
 The exact time the script is run varies with each operation:
 
diff --git a/doc/libalpm.3 b/doc/libalpm.3
index 230de61a..af1ef4fe 100644
--- a/doc/libalpm.3
+++ b/doc/libalpm.3
@@ -1,9 +1,18 @@
-.TH libalpm 3 "07 Jan 2007" "libalpm @PM_VERSION@" ""
+." the string declarations are a start to try and make distro independent
+.ds DS Arch Linux
+.ds PB PKGBUILD
+.ds VR 3.0.0
+.ds LV 1.0.0
+.TH libalpm 3 "Feb 08, 2007" "libalpm version \*(LV" "\*(DS Utilities"
 .SH NAME
-	libalpm \- Arch Linux Package Management library
+	libalpm \- Arch Linux Package Management (ALPM) library
+
 .SH SYNOPSIS
 For ease of access, the libalpm manual has been split up into several sections.
 
+(TODO) Yes, this man page needs a lot of work. Once we get around to doing good
+Doxygen documentation, it will improve. We promise.
+
 .nf
 alpm_databases      Database Functions
 alpm_interface      Interface Functions
@@ -15,7 +24,29 @@ alpm_sync           Sync Functions
 alpm_trans          Transaction Functions
 .fi
 
-.SH AUTHOR
+.SH CONFIGURATION
+See
+.BR pacman.conf (5)
+for more details on configuring \fBlibalpm\fP using the \fBpacman.conf\fP file.
+
+.SH BUGS
+Bugs? You must be kidding, there are no bugs in this software. But if we happen
+to be wrong, send us an email with as much detail as possible to
+<pacman-dev@archlinux.org>.
+
+.SH SEE ALSO
+.BR pacman (8),
+.BR makepkg (8),
+.BR pacman.conf (5)
+
+See the Arch Linux website at <http://www.archlinux.org> for more current
+information on the distribution and the \fBpacman\fP family of tools.
+
+.SH AUTHORS
 .nf
 Judd Vinet <jvinet@zeroflux.org>
+Aurelien Foret <aurelien@archlinux.org>
+Aaron Griffin <aaron@archlinux.org>
+Dan McGee <dan@archlinux.org>
+See the 'AUTHORS' file for additional contributors.
 .fi
diff --git a/doc/makepkg.8 b/doc/makepkg.8
index 90944d93..78913ccc 100644
--- a/doc/makepkg.8
+++ b/doc/makepkg.8
@@ -115,15 +115,14 @@ before proceeding with operations.
 useful if you are redirecting makepkg output to file.
 
 .SH CONFIGURATION
-Configuration options are stored in \fBmakepkg.conf\fP.  This file is sourced,
-so you can include any special compiler flags you wish to use. This is helpful
-for building for different architectures, or with different optimizations.
+See
+.BR makepkg.conf (5)
+for more details on configuring \fBmakepkg\fP using the \fBmakepkg.conf\fP file.
 
-\fBNOTE:\fP This does not guarantee that all package Makefiles will use your
-exported variables.  Some of them are non-standard...
-
-The file is fairly well commented, so follow directions given there for
-customization.
+.SH BUGS
+Bugs? You must be kidding, there are no bugs in this software. But if we happen
+to be wrong, send us an email with as much detail as possible to
+<pacman-dev@archlinux.org>.
 
 .SH SEE ALSO
 .BR makepkg.conf (5),
diff --git a/doc/makepkg.conf.5 b/doc/makepkg.conf.5
new file mode 100644
index 00000000..f5714c21
--- /dev/null
+++ b/doc/makepkg.conf.5
@@ -0,0 +1,146 @@
+." the string declarations are a start to try and make distro independent
+.ds DS Arch Linux
+.ds PB PKGBUILD
+.ds VR 3.0.0
+.TH \*(PB 5 "Feb 08, 2007" "makepkg.conf version \*(VR" "\*(DS Files"
+.SH NAME
+makepkg.conf \- makepkg configuration file
+
+.SH DESCRIPTION
+Configuration options for \fBmakekpg\fP are stored in \fBmakepkg.conf\fP. This
+file is sourced, so you can include any special compiler flags you wish to use.
+This is helpful for building for different architectures, or with different
+optimizations.
+
+\fBNOTE:\fP This does not guarantee that all package Makefiles will use your
+exported variables.  Some of them are non-standard...
+
+The default file is fairly well commented, so it may be easiest to simply
+follow directions given there for customization.
+
+.SH OPTIONS
+.TP
+.B FTPAGENT="\fI/path/to/command\fP [\fIoptions\fP]"
+Sets the download agent used to fetch source files specified with a URL in the
+\fB\*(PB\fP file. Flags can be specified as well; the download URL is then
+placed on the end of the command.
+.TP
+.B CARCH="\fIcarch\fP"
+Specifies your computer architecture; possible values include such things as
+"i686", "x86_64", "ppc", etc. This should be automatically set on installation.
+.TP
+.B CHOST="\fIchost\fP"
+A string such as "i686-pc-linux-gnu", do not touch unless you know what you are
+doing.
+.TP
+.B CFLAGS="\fIcflags\fP"
+Flags used for the C compiler. This is a key part to the use of makepkg.
+Usually several options are specified, and the most common string resembles
+something like this: "-march=i686 -O2 -pipe". Another useful option may be
+-mcpu in place of -march. Read
+.BR gcc (1)
+for more details on the wide variety of compiler flags available.
+.TP
+.B CXXFLAGS="\fIcxxflags\fP"
+Flags used for the C++ compiler; see \fBCFLAGS\fP for more info.
+.TP
+.B MAKEFLAGS="\fImakeflags\fP"
+This is often used to set the number of jobs used, for example, "-j2". Other
+flags that make accepts can also be passed.
+.TP
+.B BUILDENV=(fakeroot !distcc color !ccache)
+This array contains four options that affect the build environment, the
+defaults are shown here. All options should always be left in the array; to
+enable or disable an option simply remove or place an "!" at the front of the
+option. Each works as follows:
+.RS
+.TP
+fakeroot
+Allow building packages as a non-root user. This is \fIhighly\fP recommended.
+.TP
+distcc
+Use the distributed C/C++/ObjC compiler to spread compilation among multiple
+machines. If this is enabled, \fBDISTCC_HOSTS\fP must be specified as well.
+.TP
+color
+Colorize output messages, making output easier to read.
+.TP
+ccache
+Use ccache to cache compilation by default. This allows for faster compiles if
+you are continuously recompiling the same packages. It can be disabled for
+individual packages by passing the \fB-B\fP or \fB--noccache\fP flag to
+\fBmakepkg\fP.
+.RE
+.TP
+.B DISTCC_HOSTS="\fIhost1 ...\fP"
+If using DistCC, this is used to specify a space-delimited list of hosts
+running in the DistCC cluster. In addition, you will want to modify your
+\fBMAKEFLAGS\fP.
+.TP
+.B OPTIONS=(strip !docs libtool emptydirs)
+This array contains four options that affect the default packaging. All four
+are equivalent to options that can be placed in the PKGBUILD; the defaults are
+shown here. All options should always be left in the array; to enable or
+disable an option simply remove or place an "!" at the front of the option.
+Each works as follows:
+.RS
+.TP
+strip
+Strip symbols from binaries and libraries. If you frequently use a debugger on
+programs or libraries, it may be helpful to disable this option.
+.TP
+docs
+Save doc and info directories. If you wish to delete doc and info directories,
+specify "!docs" in the array.
+.TP
+libtool
+Leave libtool (.la) files in packages. Specify "!libtool" to remove them.
+.TP
+emptydirs
+Leave empty directories in packages.
+.RE
+.TP
+.B INTEGRITY_CHECK=(\fIcheck1 ...\fP)
+File integrity checks to use. Multiple checks may be specified; this affects
+both generation and checking. The current valid options are: md5, sha1, sha256,
+sha384, and sha512.
+.TP
+.B DOC_DIRS=(usr/{,share/}{info,doc} ...)
+If "!docs" is specified in the \fBOPTIONS\fP array, this variable will instruct
+makepkg where to look to remove docs. If you build packages that are located in
+opt/, you may need to add the directory to this array. NOTE: do not add the
+leading slash to the directory name.
+.TP
+.B PKGDEST=\fI/path/to/folder\fP
+If this value is not set, packages will by default be placed in the current
+directory (location of the \fB\*(PB\fP). Many people like to keep all their
+packages in one place so this option allows this behavior. A common location is
+"/home/packages".
+.TP
+.B SRCDEST=\fI/path/to/folder\fP
+If this value is not set, downloaded source files will only be stored in the
+current directory. Many people like to keep all source files in a central
+location for easy cleanup, so this path can be set here.
+.TP
+.B PACKAGER="\fIJohn Doe <john@doe.com>\fP"
+This value is used when querying a package to see who was the builder. It is
+recommended you change this to your name and email address.
+
+.SH SEE ALSO
+.BR makepkg (8),
+.BR pacman (8),
+.BR \*(PB (5)
+
+See the Arch Linux website at <http://www.archlinux.org> for more current
+information on the distribution and the \fBpacman\fP family of tools, and
+<http://wiki.archlinux.org/index.php/Arch_Packaging_Standards> for
+recommendations on packaging standards.
+
+.SH AUTHORS
+.nf
+Judd Vinet <jvinet@zeroflux.org>
+Aurelien Foret <aurelien@archlinux.org>
+Aaron Griffin <aaron@archlinux.org>
+Dan McGee <dan@archlinux.org>
+See the 'AUTHORS' file for additional contributors.
+.fi
diff --git a/doc/pacman.8 b/doc/pacman.8
index b9ded2e9..5ed182c4 100644
--- a/doc/pacman.8
+++ b/doc/pacman.8
@@ -2,6 +2,7 @@
 .ds DS Arch Linux
 .ds PB PKGBUILD
 .ds VR 3.0.0
+.ds LV 1.0.0
 .TH pacman 8 "Feb 07, 2007" "pacman version \*(VR" "\*(DS Utilities"
 .SH NAME
 pacman \- package manager utility
@@ -131,7 +132,8 @@ This will search each locally-installed package for names or descriptions that
 matche \fIregexp\fP.
 .TP
 .B \-u, --upgrades
-Lists all packages that are out of date on the local system. This option works best if the sync database is refreshed using \fB-Sy\fP.
+Lists all packages that are out of date on the local system. This option works
+best if the sync database is refreshed using \fB-Sy\fP.
 
 .SH REMOVE OPTIONS
 .TP
@@ -233,7 +235,7 @@ the original file.
 .SH CONFIGURATION
 See
 .BR pacman.conf (5)
-for more details on configuring pacman using the \fBpacman.conf\fP file.
+for more details on configuring \fBpacman\fP using the \fBpacman.conf\fP file.
 
 .SH BUGS
 Bugs? You must be kidding, there are no bugs in this software. But if we happen
diff --git a/doc/pacman.conf.5 b/doc/pacman.conf.5
index 3a94f801..181f8755 100644
--- a/doc/pacman.conf.5
+++ b/doc/pacman.conf.5
@@ -2,17 +2,17 @@
 .ds DS Arch Linux
 .ds PB PKGBUILD
 .ds VR 3.0.0
+.ds LV 1.0.0
 .TH \*(PB 5 "Feb 07, 2007" "pacman.conf version \*(VR" "\*(DS Files"
 .SH NAME
 pacman.conf \- pacman package manager configuration file
 
 .SH DESCRIPTION
-
-\fBpacman\fP will attempt to read \fBpacman.conf\fP each time it is invoked.
-This configuration file is divided into sections or \fIrepositories\fP. Each
-section defines a package repository that \fBpacman\fP can use when searching
-for packages in \fB--sync\fP mode. The exception to this is the \fIoptions\fP
-section, which defines global options.
+\fBpacman\fP, using \fBlibalpm\fP, will attempt to read \fBpacman.conf\fP each
+time it is invoked.  This configuration file is divided into sections or
+\fIrepositories\fP. Each section defines a package repository that \fBpacman\fP
+can use when searching for packages in \fB--sync\fP mode. The exception to this
+is the \fIoptions\fP section, which defines global options.
 
 .SH EXAMPLE
 .RS
@@ -34,11 +34,11 @@ Server = file:///home/pkgs
 
 .SH OPTIONS
 .TP
-.B DBPath = path/to/db/dir
+.B DBPath = \fIpath/to/db/dir\fP
 Overrides the default location of the toplevel database directory.  The default
 is \fIvar/lib/pacman\fP.
 .TP
-.B CacheDir = path/to/cache/dir
+.B CacheDir = \fIpath/to/cache/dir\fP
 Overrides the default location of the package cache directory. The default is
 \fIvar/cache/pacman\fP.
 .TP
@@ -102,7 +102,11 @@ take precedence over those listed later in the file when packages in two
 repositories have identical names, regardless of version number.
 
 .SH USING YOUR OWN REPOSITORY
-If you have numerous custom packages of your own, it is often easier to generate your own custom local repository than install them all with the \fB--upgrade\fP option. All you need to do is generate a compressed package database in the directory with these packages so \fBpacman\fP can find it when run with \fB--refresh\fP.
+If you have numerous custom packages of your own, it is often easier to
+generate your own custom local repository than install them all with the
+\fB--upgrade\fP option. All you need to do is generate a compressed package
+database in the directory with these packages so \fBpacman\fP can find it when
+run with \fB--refresh\fP.
 
 .RS
 .nf