Initial revision

2 files changed, 719 insertions, 0 deletions

diff --git a/doc/makepkg.8.in b/doc/makepkg.8.in
new file mode 100644
index 00000000..569f3596
--- /dev/null
+++ b/doc/makepkg.8.in
@@ -0,0 +1,407 @@
+.TH makepkg 8 "August 3, 2004" "makepkg #VERSION#" ""
+.SH NAME
+makepkg \- package build utility
+.SH SYNOPSIS
+\fBmakepkg [options]\fP
+.SH DESCRIPTION
+\fBmakepkg\fP will build packages for you.  All it needs is
+a build-capable linux platform, wget, and some build scripts.  The advantage
+to a script-based build is that you only really do the work once.  Once you
+have the build script for a package, you just need to run makepkg and it
+will do the rest: download and validate source files, check dependencies,
+configure the buildtime settings, build the package, install the package
+into a temporary root, make customizations, generate meta-info, and package
+the whole thing up for \fBpacman\fP to use.
+
+\fBmakeworld\fP can be used to rebuild an entire package group or the
+entire build tree.  See \fBmakeworld --help\fP for syntax.
+.SH BUILD PROCESS (or How To Build Your Own Packages)
+Start in an isolated directory (ie, it's not used for anything other
+than building this package).  The build script should be called PKGBUILD
+and it should bear resemblance to the example below.
+
+\fBNOTE:\fP If you have a local copy of the Arch Build System (ABS) tree
+on your computer, you can copy the PKGBUILD.proto file to your new package
+build directory and edit it from there.  To acquire/sync the ABS tree, use
+the \fBabs\fP script included with pacman/makepkg.
+
+.TP
+.TP
+.SH PKGBUILD Example:
+.RS
+.nf
+pkgname=modutils
+pkgver=2.4.25
+pkgrel=1
+pkgdesc="Utilities for inserting and removing modules from the linux kernel"
+url="http://www.kernel.org"
+backup=(etc/modules.conf)
+makedepends=('bash' 'mawk')
+depends=('glibc' 'zlib')
+source=(ftp://ftp.kernel.org/pub/linux/utils/kernel/$pkgname/v2.4/$pkgname-$pkgver.tar.bz2 \\
+        modules.conf)
+md5sums=('2c0cca3ef6330a187c6ef4fe41ecaa4d' \\
+        '35175bee593a7cc7d6205584a94d8625')
+
+build() {
+  cd $startdir/src/$pkgname-$pkgver
+  ./configure --prefix=/usr --enable-insmod-static
+  make || return 1
+  make prefix=$startdir/pkg/usr install
+  mv $startdir/pkg/usr/sbin $startdir/pkg
+  mkdir -p $startdir/pkg/etc
+  cp ../modules.conf $startdir/pkg/etc
+}
+.fi
+.RE
+
+As you can see, the setup is fairly simple.  The first three lines define
+the package name and version info.  They also define the final package name
+which will be of the form \fI$pkgname-$pkgver-$pkgrel.pkg.tar.gz\fP.  The fourth
+line provides a brief description of the package.  These four lines should
+be present in every PKGBUILD script.
+
+The line with \fIbackup=\fP specifies files that should be treated specially
+when removing or upgrading packages.  See \fBHANDLING CONFIG FILES\fP in
+the \fIpacman\fP manpage for more information on this.
+
+Lines 7 and 8 list the dependencies for this package.  The \fIdepends\fP array
+specifies the run-time dependencies and \fImakedepends\fP specifies the build-time
+dependencies.  In order to run the package, \fIdepends\fP must be satisfied.  To
+build the package, \fBall\fP dependencies must be satisifed first.  makepkg
+will check this before attempting to build the package.
+
+The \fIsource\fP array tells makepkg which files to download/extract before compiling
+begins.  The \fImd5sums\fP array provides md5sums for each of these files.  These
+are used to validate the integrity of the source files.
+
+Once your PKGBUILD is created, you can run \fImakepkg\fP from the build directory.
+makepkg will then check dependencies and look for the source files required to
+build.  If some are missing it will attempt to download them, provided there is
+a fully-qualified URL in the \fIsource\fP array.
+
+The sources are then extracted into a directory called ./src and
+the \fIbuild\fP function is called.  This is where all package configuration,
+building, and installing should be done.  Any customization will likely take
+place here.
+
+After a package is built, the \fIbuild\fP function must install the package
+files into a special package root, which can be referenced by \fB$startdir/pkg\fP
+in the \fIbuild\fP function.  The typical way to do this is one of the following:
+.RS
+.nf
+
+make DESTDIR=$startdir/pkg install
+
+or
+
+make prefix=$startdir/pkg/usr install
+
+.fi
+.RE
+Notice that the "/usr" portion should be present with "prefix", but not "DESTDIR".
+"DESTDIR" is the favorable option to use, but not all Makefiles support it.  Use
+"prefix" only when "DESTDIR" is unavailable.
+
+Once the package is successfully installed into the package root, \fImakepkg\fP
+will remove some directories (as per Arch Linux package guidelines; if you use
+this elsewhere, feel free to change it) like /usr/doc and /usr/info.  It will
+then strip debugging info from libraries and binaries and generate a meta-info
+file.  Finally, it will compress everything into a .pkg.tar.gz file and leave it
+in the directory you ran \fBmakepkg\fP from.
+
+At this point you should have a package file in the current directory, named
+something like name-version-release.pkg.tar.gz.  Done!
+
+.SH 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.
+
+The exact time the script is run varies with each operation:
+.TP
+.B pre_install
+script is run right before files are extracted.
+
+.TP
+.B post_install
+script is run right after files are extracted.
+
+.TP
+.B pre_upgrade
+script is run right before files are extracted.
+
+.TP
+.B post_upgrade
+script is run after files are extracted.
+
+.TP
+.B pre_remove
+script is run right before files are removed.
+
+.TP
+.B post_remove
+script is run right after files are removed.
+
+.RE
+To use this feature, just create a file (eg, pkgname.install) and put it in
+the same directory as the PKGBUILD script.  Then use the \fIinstall\fP directive:
+.RS
+.nf
+install=pkgname.install
+.fi
+.RE
+
+The install script does not need to be specified in the \fIsource\fP array.
+
+.TP
+.TP
+.SH Install scripts must follow this format:
+.RS
+.nf
+# arg 1:  the new package version
+pre_install() {
+  #
+  #  do pre-install stuff here
+  #
+  /bin/true
+}
+
+# arg 1:  the new package version
+post_install() {
+  #
+  #  do post-install stuff here
+  #
+  /bin/true
+}
+
+# arg 1:  the new package version
+# arg 2:  the old package version
+pre_upgrade() {
+  #
+  #  do pre-upgrade stuff here
+  #
+  /bin/true
+}
+
+# arg 1:  the new package version
+# arg 2:  the old package version
+post_upgrade() {
+  #
+  #  do post-upgrade stuff here
+  #
+  /bin/true
+}
+
+# arg 1:  the old package version
+pre_remove() {
+  #
+  #  do pre-remove stuff here
+  #
+  /bin/true
+}
+
+# arg 1:  the old package version
+post_remove() {
+  #
+  #  do post-remove stuff here
+  #
+  /bin/true
+}
+
+op=$1
+shift
+$op $*
+.fi
+.RE
+
+This template is also available in your ABS tree (/var/abs/install.proto).
+
+.SH PKGBUILD Directives
+.TP
+.B pkgname
+The name of the package.  This has be a unix-friendly name as it will be
+used in the package filename.
+
+.TP
+.B pkgver
+This is the version of the software as released from the author (eg, 2.7.1).
+
+.TP
+.B pkgrel
+This is the release number specific to Arch Linux packages.
+
+.TP
+.B pkgdesc
+This should be a brief description of the package and its functionality.
+
+.TP
+.B force
+This is used to force the package to be upgraded by \fB--sysupgrade\fP, even
+if its an older version.
+
+.TP
+.B url
+This field contains an optional URL that is associated with the piece of software
+being packaged.  This is typically the project's website.
+
+.TP
+.B license
+Sets the license type (eg, "GPL", "BSD", "NON-FREE").  (\fBNote\fP: This
+option is still in development and may change in the future)
+
+.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 PKGBUILD, and will be
+copied into the package by makepkg.  It does not need to be included in the
+\fIsource\fP array.  (eg, install=modutils.install)
+
+.TP
+.B source \fI(array)\fP 
+The \fIsource\fP line is an array of source files required to build the
+package.  Source files must reside in the same directory as the PKGBUILD
+file, unless they have a fully-qualified URL.  Then if the source file
+does not already exist in /var/cache/pacman/src, the file is downloaded
+by wget.
+
+.TP
+.B md5sums \fI(array)\fP
+If this field is present, it should contain an MD5 hash for every source file
+specified in the \fIsource\fP array (in the same order).  makepkg will use
+this to verify source file integrity during subsequent builds.  To easily
+generate md5sums, first build using the PKGBUILD then run
+\fBmakepkg -g >>PKGBILD\fP.  Then you can edit the PKGBUILD and move the
+\fImd5sums\fP line from the bottom to an appropriate location.
+
+.TP
+.B groups \fI(array)\fP
+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,
+one could install all KDE packages by installing the 'kde' group.
+
+.TP
+.B backup \fI(array)\fP 
+A space-delimited array of filenames (without a preceding slash). The
+\fIbackup\fP 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\fP in
+the \fIpacman\fP manpage for more information.
+
+.TP
+.B depends \fI(array)\fP 
+An array of packages that this package depends on to build and run.  Packages
+in this list should be surrounded with single quotes and contain at least the
+package name.  They can also include a version requirement of the form
+\fBname<>version\fP, where <> is one of these three comparisons: \fB>=\fP
+(greater than equal to), \fB<=\fP (less than or equal to), or \fB=\fP (equal to).
+See the PKGBUILD example above for an example of the \fIdepends\fP directive.
+
+.TP
+.B makedepends \fI(array)\fP
+An array of packages that this package depends on to build (ie, not required
+to run).  Packages in this list should follow the same format as \fIdepends\fP.
+
+.TP
+.B conflicts \fI(array)\fP 
+An array of packages that will conflict with this package (ie, they cannot both
+be installed at the same time).  This directive follows the same format as
+\fIdepends\fP except you cannot specify versions here, only package names.
+
+.TP
+.B provides \fI(array)\fP 
+An array of "virtual provisions" that this package provides.  This allows a package
+to provide dependency names other than it's own package name.  For example, the
+kernel-scsi and kernel-ide packages can each provide 'kernel' which allows packages
+to simply depend on 'kernel' rather than "kernel-scsi OR kernel-ide OR ..."
+
+.TP
+.B replaces \fI(array)\fP 
+This is an array of packages that this package should replace, and can be used to handle
+renamed/combined packages.  For example, if the kernel package gets renamed
+to kernel-ide, then subsequent 'pacman -Syu' calls will not pick up the upgrade, due
+to the differing package names.  \fIreplaces\fP handles this.
+
+.SH MAKEPKG OPTIONS
+.TP
+.B "\-b, \-\-builddeps"
+Build missing dependencies from source.  When makepkg finds missing build-time or
+run-time dependencies, it will look for the dependencies' PKGBUILD files under
+$ABSROOT (set in your /etc/makepkg.conf).  If it finds them it will
+run another copy of makepkg to build and install the missing dependencies.
+The child makepkg calls will be made with the \fB-b\fP and \fB-i\fP options.
+.TP
+.B "\-c, \-\-clean"
+Clean up leftover work files/directories after a successful build.
+.TP
+.B "\-C, \-\-cleancache"
+Removes all source files from the cache directory to free up diskspace.
+.TP
+.B "\-d, \-\-nodeps"
+Do not perform any dependency checks.  This will let you override/ignore any
+dependencies required.  There's a good chance this option will break the build
+process if all of the dependencies aren't installed.
+.TP
+.B "\-f, \-\-force"
+\fBmakepkg\fP will not build a package if a \fIpkgname-pkgver-pkgrel.pkg.tar.gz\fP
+file already exists in the build directory.  You can override this behaviour with
+the \fB--force\fP switch.
+.TP
+.B "\-g, \-\-genmd5"
+Download all source files (if required) and use \fImd5sum\fP to generate md5 hashes
+for each of them.  You can then redirect the output into your PKGBUILD for source
+validation (makepkg -g >>PKGBUILD).
+.TP
+.B "\-h, \-\-help"
+Output syntax and commandline options.
+.TP
+.B "\-i, \-\-install"
+Install/Upgrade the package after a successful build.
+.TP
+.B "\-j <jobs>"
+Sets MAKEFLAGS="-j<jobs>" before building the package.  This is useful for overriding
+the MAKEFLAGS setting in /etc/makepkg.conf.
+.TP
+.B "\-m, \-\-nocolor"
+Disable color in output messages
+.TP
+.B "\-n, \-\-nostrip"
+Do not strip binaries and libraries.
+.TP
+.B "\-o, \-\-nobuild"
+Download and extract files only, do not build.
+.TP
+.B "\-p <buildscript>"
+Read the package script \fI<buildscript>\fP instead of the default (\fIPKGBUILD\fP).
+.TP
+.B "\-r, \-\-rmdeps"
+Upon successful build, remove any dependencies installed by makepkg/pacman during
+dependency auto-resolution (using \fB-b\fP or \fB-s\fP).
+.TP
+.B "\-s, \-\-syncdeps"
+Install missing dependencies using pacman.  When makepkg finds missing build-time
+or run-time dependencies, it will run pacman to try and resolve them.  If successful,
+pacman will download the missing packages from a package repository and
+install them for you.
+.TP
+.B "\-w <destdir>"
+Write the resulting package file to the directory \fI<destdir>\fP instead of the
+current working directory.
+
+.SH CONFIGURATION
+Configuration options are stored in \fI/etc/makepkg.conf\fP.  This file is parsed
+as a bash script, so you can export 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 flaky...
+.SH SEE ALSO
+\fBpacman\fP is the package manager that uses packages built by makepkg.
+
+See the Arch Linux Documentation for package-building guidelines if you wish
+to contribute packages to the Arch Linux project.
+.SH AUTHOR
+.nf
+Judd Vinet <jvinet@zeroflux.org>
+.fi
diff --git a/doc/pacman.8.in b/doc/pacman.8.in
new file mode 100644
index 00000000..27787c15
--- /dev/null
+++ b/doc/pacman.8.in
@@ -0,0 +1,312 @@
+.TH pacman 8 "September 17, 2004" "pacman #VERSION#" ""
+.SH NAME
+pacman \- package manager utility
+.SH SYNOPSIS
+\fBpacman  <operation> [options] <package> [package] ...\fP
+.SH DESCRIPTION
+\fBpacman\fP is a \fIpackage management\fP utility that tracks installed
+packages on a linux system.  It has simple dependency support and the ability
+to connect to a remote ftp server and automatically upgrade packages on
+the local system.  pacman package are \fIgzipped tar\fP format.
+.SH OPERATIONS
+.TP
+.B "\-A, \-\-add"
+Add a package to the system.  Package will be uncompressed
+into the installation root and the database will be updated.
+.TP
+.B "\-F, \-\-freshen"
+This is like --upgrade except that, unlike --upgrade, this will only
+upgrade packages that are already installed on your system.
+.TP
+.B "\-Q, \-\-query"
+Query the package database.  This operation allows you to
+view installed packages and their files, as well as meta-info
+about individual packages (dependencies, conflicts, install date,
+build date, size).  This can be run against the local package
+database or can be used on individual .tar.gz packages.  See
+\fBQUERY OPTIONS\fP below.
+.TP
+.B "\-R, \-\-remove"
+Remove a package from the system.  Files belonging to the
+specified package will be deleted, and the database will
+be updated.  Most configuration files will be saved with a
+\fI.pacsave\fP extension unless the \fB--nosave\fP option was
+used.
+.TP
+.B "\-S, \-\-sync"
+Synchronize packages.  With this function you can install packages
+directly from the ftp servers, complete with all dependencies required
+to run the packages.  For example, \fBpacman -S qt\fP will download
+qt and all the packages it depends on and install them. You could also use
+\fBpacman -Su\fP to upgrade all packages that are out of date (see below).
+.TP
+.B "\-U, \-\-upgrade"
+Upgrade a package.  This is essentially a "remove-then-add"
+process.  See \fBHANDLING CONFIG FILES\fP for an explanation
+on how pacman takes care of config files.
+.TP
+.B "\-V, \-\-version"
+Display version and exit.
+.TP
+.B "\-h, \-\-help"
+Display syntax for the given operation.  If no operation was
+supplied then the general syntax is shown.
+.SH OPTIONS
+.TP
+.B "\-d, \-\-nodeps"
+Skips all dependency checks.  Normally, pacman will always check
+a package's dependency fields to ensure that all dependencies are
+installed and there are no package conflicts in the system.  This
+switch disables these checks.
+.TP
+.B "\-f, \-\-force"
+Bypass file conflict checks, overwriting conflicting files.  If the
+package that is about to be installed contains files that are already
+installed, this option will cause all those files to be overwritten.
+This option should be used with care, ideally not at all.
+.TP
+.B "\-r, \-\-root <path>"
+Specify alternative installation root (default is "/"). This
+should \fInot\fP be used as a way to install software into
+e.g. /usr/local instead of /usr. Instead this should be used
+if you want to install a package on a temporary mounted partition,
+which is "owned" by another system. By using this option you not only
+specify where the software should be installed, but you also
+specify which package database to use.
+.TP
+.B "\-v, \-\-verbose"
+Output more status and error messages.
+.TP
+.B "\-\-config <path>"
+Specify an alternate configuration file.
+.TP
+.B "\-\-noconfirm"
+Bypass any and all "Are you sure?" messages.  It's not a good to do this
+unless you want to run pacman from a script.
+.SH SYNC OPTIONS
+.TP
+.B "\-c, \-\-clean"
+Remove old packages from the cache.  When pacman downloads packages,
+it saves them in \fI/var/cache/pacman/pkg\fP.  If you need to free up
+diskspace, you can remove these packages by using the --clean option.
+Using one --clean (or -c) switch will only remove \fIold\fP packages.
+Use it twice to remove \fIall\fP packages from the cache.
+.TP
+.B "\-g, \-\-groups"
+Display all the members for each package group specified.  If no group
+names are provided, all groups will be listed.
+.TP
+.B "\-i, \-\-info"
+Display dependency information for a given package.  This will search
+through all repositories for a matching package and display the
+dependencies, conflicts, etc.
+.TP
+.B "\-l, \-\-list"
+List all files in the specified repositories.  Multiple repositories can
+be specified on the command line.
+.TP
+.B "\-p, \-\-print-uris"
+Print out URIs for each specified package and its dependencies.  These
+can be piped to a file and downloaded at a later time, using a program
+like wget.
+.TP
+.B "\-s, \-\-search <string>"
+This will search each package in the package list for names or descriptions
+that contains <string>.
+.TP
+.B "\-u, \-\-sysupgrade"
+Upgrades all packages that are out of date.  pacman will examine every
+package installed on the system, and if a newer package exists on the
+server it will upgrade.  pacman will present a report of all packages
+it wants to upgrade and will not proceed without user confirmation.
+Dependencies are automatically resolved at this level and will be
+installed/upgraded if necessary.
+.TP
+.B "\-w, \-\-downloadonly"
+Retrieve all packages from the server, but do not install/upgrade anything.
+.TP
+.B "\-y, \-\-refresh"
+Download a fresh copy of the master package list from the ftp server
+defined in \fI/etc/pacman.conf\fP.  This should typically be used each
+time you use \fB--sysupgrade\fP.
+.TP
+.B "\-\-ignore <pkg>"
+This option functions exactly the same as the \fBIgnorePkg\fP configuration
+directive.  Sometimes it can be handy to skip some package updates without
+having to edit \fIpacman.conf\fP each time.
+.SH REMOVE OPTIONS
+.TP
+.B "\-c, \-\-cascade"
+Remove all target packages, as well as all packages that depend on one
+or more target packages.  This operation is recursive.
+.TP
+.B "\-k, \-\-keep"
+Removes the database entry only.  Leaves all files in place.
+.TP
+.B "\-n, \-\-nosave"
+Instructs pacman to ignore file backup designations.  Normally, when
+a file is about to be \fIremoved\fP from the system the database is first
+checked to see if the file should be renamed to a .pacsave extension.  If
+\fB--nosave\fP is used, these designations are ignored and the files are
+removed.
+.TP
+.B "\-s, \-\-recursive"
+For each target specified, remove it and all its dependencies, provided
+that (A) they are not required by other packages; and (B) they were not
+explicitly installed by the user.
+This option is analagous to a backwards --sync operation.
+.SH QUERY OPTIONS
+.TP
+.B "\-e, \-\-orphans"
+List all packages that were explicitly installed (ie, not pulled in
+as a dependency by other packages) and are not required by any other
+packages.
+.TP
+.B "\-g, \-\-groups"
+Display all groups that a specified package is part of.  If no package
+names are provided, all groups and members will be listed.
+.TP
+.B "\-i, \-\-info"
+Display information on a given package.  If it is used with the \fB-p\fP
+option then the .PKGINFO file will be printed.
+.TP
+.B "\-l, \-\-list"
+List all files owned by <package>.  Multiple packages can be specified on
+the command line.
+.TP
+.B "\-o, \-\-owns <file>"
+Search for the package that owns <file>.
+.TP
+.B "\-p, \-\-file"
+Tells pacman that the package supplied on the command line is a
+file, not an entry in the database.  Pacman will decompress the
+file and query it.  This is useful with \fB--info\fP and \fB--list\fP.
+.TP
+.B "\-s, \-\-search <string>"
+This will search each locally-installed package for names or descriptions
+that contains <string>.
+.SH HANDLING CONFIG FILES
+pacman uses the same logic as rpm to determine action against files
+that are designated to be backed up.  During an upgrade, it uses 3
+md5 hashes for each backup file to determine the required action:
+one for the original file installed, one for the new file that's about
+to be installed, and one for the actual file existing on the filesystem.
+After comparing these 3 hashes, the follow scenarios can result:
+.TP
+original=\fBX\fP, current=\fBX\fP, new=\fBX\fP
+All three files are the same, so we win either way.  Install the new file.
+.TP
+original=\fBX\fP, current=\fBX\fP, new=\fBY\fP
+The current file is un-altered from the original but the new one is
+different.  Since the user did not ever modify the file, and the new
+one may contain improvements/bugfixes, we install the new file.
+.TP
+original=\fBX\fP, current=\fBY\fP, new=\fBX\fP
+Both package versions contain the exact same file, but the one
+on the filesystem has been modified since.  In this case, we leave
+the current file in place.
+.TP
+original=\fBX\fP, current=\fBY\fP, new=\fBY\fP
+The new one is identical to the current one.  Win win.  Install the new file.
+.TP
+original=\fBX\fP, current=\fBY\fP, new=\fBZ\fP
+All three files are different.  So we install the new file, but back up the
+old one to a .pacsave extension.  This way the user can move the old configuration
+file back into place if he wishes.
+.SH CONFIGURATION
+pacman will attempt to read \fI/etc/pacman.conf\fP each time it is invoked.  This
+configuration file is divided into sections or \fIrepositories\fP.  Each section
+defines a package repository that pacman can use when searching for packages in
+--sync mode.  The exception to this is the \fIoptions\fP section, which defines
+global options.
+.TP
+.SH Example:
+.RS
+.nf
+[options]
+NoUpgrade = etc/passwd etc/group etc/shadow
+NoUpgrade = etc/fstab
+
+Include = /etc/pacman.d/current
+
+[custom]
+Server = file:///home/pkgs
+
+.fi
+.RE
+.SH CONFIG: OPTIONS
+.TP
+.B "DBPath = path/to/db/dir"
+Overrides the default location of the toplevel database directory.  The default is
+\fIvar/lib/pacman\fP.
+.TP
+.B "HoldPkg = <package> [package] ..."
+If a user tries to \fB--remove\fP a package that's listed in HoldPkg, pacman
+will ask for confirmation before proceeding.
+.TP
+.B "IgnorePkg = <package> [package] ..."
+Instructs pacman to ignore any upgrades for this package when performing a
+\fB--sysupgrade\fP.
+.TP
+.B "Include = <path>"
+Include another config file.  This config file can include repositories or
+general configuration options.
+.TP
+.B "ProxyServer = <host|ip>[:port]"
+If set, pacman will use this proxy server for all ftp/http transfers.
+.TP
+.B "XferCommand = /path/to/command %u"
+If set, pacman will use this external program to download all remote files.
+All instances of \fB%u\fP will be replaced with the URL to be downloaded.  If
+present, instances of \fB%o\fP will be replaced with the local filename, plus a
+".part" extension, which allows programs like wget to do file resumes properly.
+
+This option is useful for users who experience problems with pacman's built-in http/ftp
+support, or need the more advanced proxy support that comes with utilities like
+wget.
+.TP
+.B "NoPassiveFtp"
+Disables passive ftp connections when downloading packages. (aka Active Mode)
+.TP
+.B "NoUpgrade = <file> [file] ..."
+All files listed with a \fBNoUpgrade\fP directive will never be touched during a package
+install/upgrade.  \fINote:\fP do not include the leading slash when specifying files.
+.TP
+.B "UseSyslog"
+Log action messages through syslog().  This will insert pacman log entries into your
+/var/log/messages or equivalent.
+.TP
+.B "LogFile = /path/to/file"
+Log actions directly to a file, usually /var/log/pacman.log.
+
+.SH CONFIG: REPOSITORIES
+Each repository section defines a section name and at least one location where the packages
+can be found.  The section name is defined by the string within square brackets (eg, the two
+above are 'current' and 'custom').  Locations are defined with the \fIServer\fP directive and
+follow a URL naming structure.  Currently only ftp is supported for remote servers.  If you
+want to use a local directory, you can specify the full path with a 'file://' prefix, as
+shown above.
+.SH USING YOUR OWN REPOSITORY
+Let's say you have a bunch of custom packages in \fI/home/pkgs\fP and their respective PKGBUILD
+files are all in \fI/var/abs/local\fP.  All you need to do is generate a compressed package database
+in the \fI/home/pkgs\fP directory so pacman can find it when run with --refresh.
+
+.RS
+.nf
+# gensync /var/abs/local /home/pkgs/custom.db.tar.gz
+.fi
+.RE
+
+The above command will read all PKGBUILD files in /var/abs/local and generate a compressed
+database called /home/pkgs/custom.db.tar.gz.  Note that the database must be of the form
+\fI{treename}.db.tar.gz\fP, where {treename} is the name of the section defined in the
+configuration file.
+That's it!  Now configure your \fIcustom\fP section in the configuration file as shown in the
+config example above.  Pacman will now use your package repository.  If you add new packages to
+the repository, remember to re-generate the database and use pacman's --refresh option.
+.SH SEE ALSO
+\fBmakepkg\fP is the package-building tool that comes with pacman.
+.SH AUTHOR
+.nf
+Judd Vinet <jvinet@zeroflux.org>
+.fi