summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorDan McGee <dan@archlinux.org>2007-09-16 21:10:44 -0500
committerDan McGee <dan@archlinux.org>2007-09-16 21:10:44 -0500
commit708488f6fe8bf5e06ae724243381b40586301633 (patch)
tree83042c703173107def709f65d65697e233225441 /doc
parentb0aa51059233849b0a7ef8d6a851750776ce6645 (diff)
parentf131ee9c56b99429374dfcce583872ad9259ed96 (diff)
downloadpacman-708488f6fe8bf5e06ae724243381b40586301633.tar.xz
Merge branch 'asciidoc' into working
We're getting close to release, so might as well do this now so people can actually update some of our documentation.
Diffstat (limited to 'doc')
-rw-r--r--doc/.gitignore9
-rw-r--r--doc/Makefile.am49
-rw-r--r--doc/PKGBUILD-example.txt32
-rw-r--r--doc/PKGBUILD.5288
-rw-r--r--doc/PKGBUILD.5.txt239
-rw-r--r--doc/asciidoc.conf64
-rw-r--r--doc/footer.txt24
-rw-r--r--doc/libalpm.353
-rw-r--r--doc/libalpm.3.txt39
-rw-r--r--doc/makepkg.8146
-rw-r--r--doc/makepkg.8.txt143
-rw-r--r--doc/makepkg.conf.5152
-rw-r--r--doc/makepkg.conf.5.txt154
-rw-r--r--doc/pacman.8293
-rw-r--r--doc/pacman.8.txt313
-rw-r--r--doc/pacman.conf.5143
-rw-r--r--doc/pacman.conf.5.txt147
-rw-r--r--doc/repo-add.8.txt51
18 files changed, 1256 insertions, 1083 deletions
diff --git a/doc/.gitignore b/doc/.gitignore
index fcbfb09d..e10f61a4 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -1,2 +1,9 @@
-*.html
+PKGBUILD.5
+libalpm.3
+makepkg.8
+makepkg.conf.5
+pacman.8
+pacman.conf.5
+repo-add.8
+*.xml
man3
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 14caa0da..ad251287 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,25 +1,60 @@
-man_MANS = \
+ASCIIDOC_MANS = \
pacman.8 \
makepkg.8 \
+ repo-add.8 \
PKGBUILD.5 \
makepkg.conf.5 \
pacman.conf.5 \
libalpm.3
-if HAS_DOXYGEN
-man_MANS += $(wildcard man3/*.3)
+if USE_DOXYGEN
+DOXYGEN_MANS = $(wildcard man3/*.3)
endif
-EXTRA_DIST = $(man_MANS) Doxyfile
+man_MANS = $(ASCIIDOC_MANS) $(DOXYGEN_MANS)
-if HAS_DOXYGEN
+EXTRA_DIST = \
+ pacman.8.txt \
+ makepkg.8.txt \
+ repo-add.8.txt \
+ PKGBUILD.5.txt \
+ PKGBUILD-example.txt \
+ makepkg.conf.5.txt \
+ pacman.conf.5.txt \
+ libalpm.3.txt \
+ footer.txt \
+ Doxyfile \
+ $(ASCIIDOC_MANS)
+
+# Files that should be removed, but which Automake does not know.
+MOSTLYCLEANFILES = $(DOXYGEN_MANS) *.xml
+
+if USE_DOXYGEN
all: doxygen.in
doxygen.in:
doxygen $(srcdir)/Doxyfile
endif
-clean-local:
- $(RM) man3/*.3
+if USE_ASCIIDOC
+ASCIIDOC_OPTS = \
+ -f asciidoc.conf \
+ -a pacman_version="$(PACKAGE_VERSION)" \
+ -a pacman_date="`date +%Y-%m-%d`" \
+ -a sysconfdir=$(sysconfdir)
+
+$(ASCIIDOC_MANS):
+ a2x -d manpage -f manpage --asciidoc-opts="$(ASCIIDOC_OPTS)" $@.txt
+
+# These rules are due to the includes and files of the asciidoc text
+$(ASCIIDOC_MANS): footer.txt
+pacman.8: pacman.8.txt
+makepkg.8: makepkg.8.txt
+repo-add.8: repo-add.8.txt
+PKGBUILD.5: PKGBUILD.5.txt PKGBUILD-example.txt
+makepkg.conf.5: makepkg.conf.5.txt
+pacman.conf.5: pacman.conf.5.txt
+libalpm.3: libalpm.3.txt
+endif
# vim:set ts=2 sw=2 noet:
diff --git a/doc/PKGBUILD-example.txt b/doc/PKGBUILD-example.txt
new file mode 100644
index 00000000..50b652bd
--- /dev/null
+++ b/doc/PKGBUILD-example.txt
@@ -0,0 +1,32 @@
+# $Id: PKGBUILD,v 1.16 2006/06/20 07:03:04 tpowa Exp $
+# Maintainer: judd <jvinet@zeroflux.org>
+pkgname=module-init-tools
+pkgver=3.2.2
+pkgrel=3
+pkgdesc="Utilities for inserting and removing modules from the Linux kernel"
+arch=(i686 x86_64)
+url="http://www.kernel.org"
+license=('GPL')
+depends=('glibc')
+conflicts=('modutils')
+replaces=('modutils')
+backup=('etc/modprobe.conf' 'etc/modules.conf' 'etc/modprobe.devfs')
+source=(http://www.kernel.org/pub/linux/utils/kernel/module-init-tools/module-init-tools-$pkgver.tar.bz2 \
+ makefile.patch modprobe.conf)
+md5sums=('a1ad0a09d3231673f70d631f3f5040e9' '47e14fda7a46668290d11d0444d81826'\
+ '6db59d41e04941a790f80c1a4432faef')
+
+build() {
+ cd "$srcdir"/$pkgname-$pkgver
+
+ patch -Np1 -i ../makefile.patch || return 1
+ sed -i 's|/usr/bin/install|/bin/install|g' install-with-care
+
+ ./configure --prefix=/usr --exec-prefix=/
+ make || return 1
+
+ INSTALL=/bin/install make DESTDIR="$pkgdir" install
+ install -D -m644 ../modprobe.conf "$pkgdir"/etc/modprobe.conf
+}
+
+# vim:set ts=2 sw=2 et:
diff --git a/doc/PKGBUILD.5 b/doc/PKGBUILD.5
deleted file mode 100644
index 747b9f15..00000000
--- a/doc/PKGBUILD.5
+++ /dev/null
@@ -1,288 +0,0 @@
-." 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 07, 2007" "\*(PB version \*(VR" "\*(DS Files"
-.SH NAME
-\*(PB \- \*(DS package build description file
-
-.SH DESCRIPTION
-This manual page is meant to describe general rules about \fB\*(PB\fPs. Once
-a \fB\*(PB\fP is written, the actual package is built using \fBmakepkg\fP and
-installed with \fBpacman\fP.
-
-\fBNOTE:\fP 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\fP script included with \fBpacman\fP.
-
-.SH OPTIONS AND 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
-The version of the software as released from the author (e.g. 2.7.1).
-
-.TP
-.B pkgrel
-This is the release number specific to the \*(DSs release. This allows package
-maintainers to make updates to the package's configure flags, for example.
-
-.TP
-.B pkgdesc
-This should be a brief description of the package and its functionality. Try to
-keep the description to one line of text.
-
-.TP
-.B url
-This field contains a URL that is associated with the software being packaged.
-This is typically the project's website.
-
-.TP
-.B license (array)
-This field specifies the license(s) that apply to the package. Commonly-used
-licenses are found in \fI/usr/share/licenses/common\fP. If you see the
-package's license there, simply reference it in the license field (e.g.
-\fBlicense=("GPL")\fP). If the package provides a license not found in
-\fI/usr/share/licenses/common\fP, then you should include the license in the
-package itself and set \fBlicense=("custom")\fP or
-\fBlicense=("custom:LicenseName")\fP. The license should be placed in
-\fI$startdir/pkg/usr/share/licenses/$pkgname\fP when building the package. If
-multiple licenses are applicable for a package, list all of them:
-\fBlicenses=('GPL' 'FDL')\fP.
-
-.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 \fB\*(PB\fP, and will be copied
-into the package by \fBmakepkg\fP. It does not need to be included in the
-\fIsource\fP array (e.g. \fBinstall=pkgname.install\fP).
-
-.TP
-.B source \fI(array)\fP
-An array of source files required to build the package. Source files must
-either reside in the same directory as the \fB\*(PB file\fP, or be a
-fully-qualified URL that makepkg will use to download the file. In order to
-make the PKGBUILD as useful as possible, use the \fB$pkgname\fP and
-\fB$pkgver\fP variables if possible when specifying the download location.
-
-.TP
-.B noextract \fI(array)\fP
-An array of filenames corresponding to those from the \fBsource\fP array. Files
-listed here will not be extracted with the rest of the source files. This is
-useful for packages which use compressed data which is downloaded but not
-necessary to uncompress.
-
-.TP
-.B md5sums \fI(array)\fP
-This array contains an MD5 hash for every source file specified in the
-\fBsource\fP array (in the same order). \fBmakepkg\fP will use this to verify
-source file integrity during subsequent builds. To easily generate md5sums, run
-"makepkg -g >> \*(PB". If desired, move the \fBmd5sums\fP 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.
-Alternative integrity checks that \fBmakepkg\fP supports, as noted in
-\fBmd5sums\fP above.
-
-.TP
-.B groups \fI(array)\fP
-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 arch \fI(array)\fP
-Defines on which architectures the given package is available (e.g.
-\fBarch=('i686' 'x86_64')\fP).
-
-.TP
-.B backup \fI(array)\fP
-A space-delimited array of filenames, \fIwithout\fP preceding slashes, that
-should be backed up if the package is removed or upgraded. This is commonly
-used for packages placing configuration files in /etc. See \fBHANDLING CONFIG
-FILES\fP in the \fBpacman\fP manpage for more information.
-
-.TP
-.B depends \fI(array)\fP
-An array of packages that this package depends on to run. Packages in this list
-should be surrounded with single quotes and contain at least the package name.
-Entries can also include a version requirement of the form
-\fB'name<>version'\fP, where <> is one of three comparisons: \fI>=\fP (greater
-than or equal to), \fI<=\fP (less than or equal to), or \fI=\fP (equal to).
-
-.TP
-.B makedepends \fI(array)\fP
-An array of packages that this package depends on to build, but are not needed
-at runtime. Packages in this list follow the same format as \fBdepends\fP.
-
-.TP
-.B conflicts \fI(array)\fP
-An array of packages that will conflict with this package (i.e. they cannot
-both be installed at the same time). This directive follows the same format as
-\fIdepends\fP, except you cannot specify versions.
-
-.TP
-.B provides \fI(array)\fP
-An array of "virtual provisions" that this package provides. This allows a
-package to provide dependencies other than its own package name. For example,
-the dcron package can provide 'cron', which allows packages to depend on 'cron'
-rather than 'dcron OR fcron'.
-
-.TP
-.B replaces \fI(array)\fP
-An array of packages that this package should replace, and can be used to
-handle renamed/combined packages. For example, if the 'j2re' package is renamed
-to 'jre', this directive allows future upgrades to continue as expected even
-though the package has moved.
-
-.TP
-.B options \fI(array)\fP
-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\fP array. To reverse the default behavior, place an "!" at the front
-of the option. Only specify the options you specifically want to override, the
-rest will be taken from \fBmakepkg.conf\fP. NOTE: 'force' is a special option
-only used in \fB\*(PB\fPs, do not use it unless you know what you are doing.
-.RS
-.TP
-.B 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
-.B docs
-Save doc and info directories. If you wish to delete doc and info directories,
-specify "!docs" in the array.
-.TP
-.B libtool
-Leave libtool (.la) files in packages. Specify "!libtool" to remove them.
-.TP
-.B emptydirs
-Leave empty directories in packages.
-.TP
-.B ccache
-Allow the use of \fBccache\fP during build. More useful in its negative form
-"!ccache" with select packages that have problems building with \fBccache\fP.
-.TP
-.B distcc
-Allow the use of \fBdistcc\fP during build. More useful in its negative form
-"!distcc" with select packages that have problems building with \fBdistcc\fP.
-.TP
-.B makeflags
-Allow the use of user-specific makeflags during build as specified in
-\fBmakepkg.conf\fP. More useful in its negative form "!makeflags" with select
-packages that have problems building with custom makeflags such as "-j2" (or
-higher).
-.TP
-.B force
-Force the package to be upgraded by a \fBpacman\fP system upgrade operation,
-even if the version number would normally not trigger such an upgrade. This is
-useful when the version numbering scheme of a package changes (or is
-alphanumeric).
-.RE
-
-.SH INSTALL/UPGRADE/REMOVE SCRIPTING
-\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:
-
-.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.
-
-.P
-To use this feature, create a file such as 'pkgname.install' and put it in
-the same directory as the \fB\*(PB\fP script. Then use the \fBinstall\fP
-directive:
-
-.RS
-.nf
-install=pkgname.install
-.fi
-.RE
-
-The install script does not need to be specified in the \fBsource\fP array.
-A template install file is available in the ABS tree (/var/abs/install.proto).
-
-.SH EXAMPLE
-The following is an example \fB\*(PB\fP for the 'modutils' package. For more
-examples, look through the ABS tree.
-
-.nf
-# Maintainer: John Doe <johndoe@archlinux.org>
-# Contributor: Bill Smith <billsmith@archlinux.org>
-pkgname=modutils
-pkgver=2.4.25
-pkgrel=1
-pkgdesc="Utilities for inserting modules in the linux kernel"
-url="http://www.kernel.org"
-makedepends=('bash' 'mawk')
-depends=('glibc' 'zlib')
-backup=(etc/modules.conf)
-source=(ftp://ftp.kernel.org/pub/linux/utils/kernel/$pkgname/v2.4/$pkgname-$pkgver.tar.bz2
- modules.conf)
-arch=('i686')
-license=('GPL' 'custom') # dual licensed
-md5sums=('2c0cca3ef6330a187c6ef4fe41ecaa4d'
- '35175bee593a7cc7d6205584a94d8625')
-options=(!libtool)
-
-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
-
-.SH SEE ALSO
-.BR makepkg (8),
-.BR pacman (8),
-.BR makepkg.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, 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>
-.fi
-
-See the 'AUTHORS' file for additional contributors.
diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt
new file mode 100644
index 00000000..be3f1169
--- /dev/null
+++ b/doc/PKGBUILD.5.txt
@@ -0,0 +1,239 @@
+/////
+vim:set ts=4 sw=4 syntax=asciidoc noet:
+/////
+PKGBUILD(5)
+===========
+
+Name
+----
+PKGBUILD - Arch Linux package build description file
+
+
+Synopsis
+--------
+PKGBUILD
+
+
+Description
+-----------
+This manual page is meant to describe general rules about PKGBUILDs. Once a
+PKGBUILD is written, the actual package is built using makepkg and installed
+with pacman.
+
+NOTE: 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 abs
+script included with pacman.
+
+
+Options and Directives
+----------------------
+*pkgname*::
+ The name of the package. This has be a unix-friendly name as it will be
+ used in the package filename.
+
+*pkgver*::
+ The version of the software as released from the author (e.g. \'2.7.1').
+
+*pkgrel*::
+ This is the release number specific to the Arch Linuxs release. This
+ allows package maintainers to make updates to the package's configure
+ flags, for example.
+
+*pkgdesc*::
+ This should be a brief description of the package and its functionality.
+ Try to keep the description to one line of text.
+
+*url*::
+ This field contains a URL that is associated with the software being
+ packaged. This is typically the project's website.
+
+*license (array)*::
+ This field specifies the license(s) that apply to the package.
+ Commonly-used licenses are found in '/usr/share/licenses/common'. If you
+ see the package's license there, simply reference it in the license
+ field (e.g. `$$license=('GPL')$$`). If the package provides a license not
+ found in '/usr/share/licenses/common', then you should include the license
+ in the package itself and set `$$license=('custom')$$` or
+ `$$license=('custom:LicenseName')$$`. The license should be placed in
+ '$pkgdir/usr/share/licenses/$pkgname' when building the package. If
+ multiple licenses are applicable for a package, list all of them:
+ `$$license=('GPL' 'FDL')$$`.
+
+*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 source array (e.g. `$$install=pkgname.install$$`).
+
+*source (array)*::
+ An array of source files required to build the package. Source files
+ must either reside in the same directory as the PKGBUILD file, or be a
+ fully-qualified URL that makepkg will use to download the file. In order
+ to make the PKGBUILD as useful as possible, use the $pkgname and $pkgver
+ variables if possible when specifying the download location.
+
+*noextract (array)*::
+ An array of filenames corresponding to those from the source array. Files
+ listed here will not be extracted with the rest of the source files. This
+ is useful for packages which use compressed data which is downloaded but
+ not necessary to uncompress.
+
+*md5sums (array)*::
+ This array contains an MD5 hash for every source file specified in the
+ source array (in the same order). makepkg will use this to verify source
+ file integrity during subsequent builds. To easily generate md5sums, run
+ ``makepkg -g >> PKGBUILD''. If desired, move the md5sums line to an
+ appropriate location. *NOTE:* makepkg 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.
+
+*sha1sums, etc.*::
+ Alternative integrity checks that makepkg supports, as noted in md5sums
+ above.
+
+*groups (array)*::
+ 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.
+
+*arch (array)*::
+ Defines on which architectures the given package is available (e.g.
+ `$$arch=('i686' 'x86_64')$$`).
+
+*backup (array)*::
+ A space-delimited array of filenames, without preceding slashes, that
+ should be backed up if the package is removed or upgraded. This is
+ commonly used for packages placing configuration files in /etc. See
+ Handling Config Files in manlink:pacman[8] for more information.
+
+*depends (array)*::
+ An array of packages that this package depends on to run. Packages in
+ this list should be surrounded with single quotes and contain at least
+ the package name. Entries can also include a version requirement of the
+ form 'name<>version', where <> is one of three comparisons: >= (greater
+ than or equal to), <= (less than or equal to), or = (equal to).
+
+*makedepends (array)*::
+ An array of packages that this package depends on to build, but are not
+ needed at runtime. Packages in this list follow the same format as
+ depends.
+
+*conflicts (array)*::
+ An array of packages that will conflict with this package (i.e. they
+ cannot both be installed at the same time). This directive follows the
+ same format as depends, except you cannot specify versions.
+
+*provides (array)*::
+ An array of ``virtual provisions'' that this package provides. This allows
+ a package to provide dependencies other than its own package name. For
+ example, the dcron package can provide 'cron', which allows packages to
+ depend on 'cron' rather than 'dcron OR fcron'.
+
+*replaces (array)*::
+ An array of packages that this package should replace, and can be used
+ to handle renamed/combined packages. For example, if the 'j2re' package
+ is renamed to 'jre', this directive allows future upgrades to continue
+ as expected even though the package has moved. Sysupgrade is currently
+ the only pacman operation that utilizes this field, a normal sync will
+ not use its value.
+
+*options (array)*::
+ This array allows you to override some of makepkg's default behavior
+ when building packages. To set an option, just include the option name
+ in the options array. To reverse the default behavior, place an ``!'' at
+ the front of the option. Only specify the options you specifically want
+ to override, the rest will be taken from manlink:makepkg.conf[5].
+ *NOTE:* 'force' is a special option only used in a manlink:PKGBUILD[5],
+ do not use it unless you know what you are doing.
+
+ *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.
+
+ *docs*;;
+ Save doc and info directories. If you wish to delete doc and
+ info directories, specify `!docs` in the array.
+
+ *libtool*;;
+ Leave libtool (.la) files in packages. Specify `!libtool` to
+ remove them.
+
+ *emptydirs*;;
+ Leave empty directories in packages.
+
+ *ccache*;;
+ Allow the use of ccache during build. More useful in its negative
+ form `!ccache` with select packages that have problems building
+ with ccache.
+
+ *distcc*;;
+ Allow the use of distcc during build. More useful in its negative
+ form `!distcc` with select packages that have problems building
+ with distcc.
+
+ *makeflags*;;
+ Allow the use of user-specific makeflags during build as specified
+ in manlink:makepkg.conf[5]. More useful in its negative form
+ `!makeflags` with select packages that have problems building with
+ custom makeflags such as `-j2` (or higher).
+
+ *force*;;
+ Force the package to be upgraded by a pacman system upgrade
+ operation, even if the version number would normally not trigger
+ such an upgrade. This is useful when the version numbering scheme
+ of a package changes (or is alphanumeric).
+
+
+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:
+
+*pre_install*::
+ script is run right before files are extracted.
+
+*post_install*::
+ script is run right after files are extracted.
+
+*pre_upgrade*::
+ script is run right before files are extracted.
+
+*post_upgrade*::
+ script is run after files are extracted.
+
+*pre_remove*::
+ script is run right before files are removed.
+
+*post_remove*::
+ script is run right after files are removed.
+
+To use this feature, create a file such as 'pkgname.install' and put it in the
+same directory as the PKGBUILD script. Then use the install directive:
+
+ install=pkgname.install
+
+The install script does not need to be specified in the source array. A template
+install file is available in the ABS tree (/var/abs/install.proto).
+
+
+Example
+-------
+The following is an example PKGBUILD for the 'module-init-tools' package. For more
+examples, look through the ABS tree.
+
+-----
+include::PKGBUILD-example.txt[]
+-----
+
+
+See Also
+--------
+manlink:makepkg[8], manlink:pacman[8], manlink:makepkg.conf[5]
+
+include::footer.txt[]
diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf
new file mode 100644
index 00000000..92e01179
--- /dev/null
+++ b/doc/asciidoc.conf
@@ -0,0 +1,64 @@
+#
+# Inspired by/borrowed from the GIT source tree at Documentation/asciidoc.conf
+#
+
+## manlink: macro
+#
+# Usage: manlink:command[manpage-section]
+#
+# Note, {0} is the manpage section, while {target} is the command.
+#
+# Show man link as: <command>(<section>); if section is defined, else just show
+# the command.
+
+[attributes]
+plus=&#43;
+caret=&#94;
+startsb=&#91;
+endsb=&#93;
+tilde=&#126;
+
+ifdef::backend-docbook[]
+[manlink-inlinemacro]
+{0%{target}}
+{0#<citerefentry>}
+{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
+{0#</citerefentry>}
+endif::backend-docbook[]
+
+ifdef::backend-docbook[]
+# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this.
+[listingblock]
+<example><title>{title}</title>
+<literallayout>
+|
+</literallayout>
+{title#}</example>
+endif::backend-docbook[]
+
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[header]
+template::[header-declarations]
+<refentry>
+<refentryinfo>
+<date>{pacman_date}</date>
+</refentryinfo>
+<refmeta>
+<refentrytitle>{mantitle}</refentrytitle>
+<manvolnum>{manvolnum}</manvolnum>
+<refmiscinfo class="source">Pacman</refmiscinfo>
+<refmiscinfo class="version">{pacman_version}</refmiscinfo>
+<refmiscinfo class="manual">Pacman Manual</refmiscinfo>
+</refmeta>
+<refnamediv>
+ <refname>{manname}</refname>
+ <refpurpose>{manpurpose}</refpurpose>
+</refnamediv>
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
+ifdef::backend-xhtml11[]
+[manlink-inlinemacro]
+<a href="{target}.{0}.html">{target}{0?({0})}</a>
+endif::backend-xhtml11[]
diff --git a/doc/footer.txt b/doc/footer.txt
new file mode 100644
index 00000000..d1ee9d1e
--- /dev/null
+++ b/doc/footer.txt
@@ -0,0 +1,24 @@
+/////
+vim:set ts=4 sw=4 syntax=asciidoc noet:
+/////
+See the Arch Linux website at <http://www.archlinux.org> for more current
+information on the distribution and the pacman family of tools, and
+<http://wiki.archlinux.org/index.php/Arch_Packaging_Standards> for
+recommendations on packaging standards.
+
+
+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>.
+
+
+Authors
+-------
+* 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.
diff --git a/doc/libalpm.3 b/doc/libalpm.3
deleted file mode 100644
index e78e9eca..00000000
--- a/doc/libalpm.3
+++ /dev/null
@@ -1,53 +0,0 @@
-." 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 (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
-alpm_list List Functions
-alpm_log Logging Functions
-alpm_misc Miscellaneous Functions
-alpm_packages Package Functions
-alpm_sync Sync Functions
-alpm_trans Transaction Functions
-.fi
-
-.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>
-.fi
-
-See the 'AUTHORS' file for additional contributors.
diff --git a/doc/libalpm.3.txt b/doc/libalpm.3.txt
new file mode 100644
index 00000000..d8fb58e8
--- /dev/null
+++ b/doc/libalpm.3.txt
@@ -0,0 +1,39 @@
+/////
+vim:set ts=4 sw=4 syntax=asciidoc noet:
+/////
+libalpm(3)
+==========
+
+Name
+----
+libalpm - Arch Linux Package Management (ALPM) library
+
+
+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.
+
+*alpm_databases*:: Database Functions
+*alpm_interface*:: Interface Functions
+*alpm_list*:: List Functions
+*alpm_log*:: Logging Functions
+*alpm_misc*:: Miscellaneous Functions
+*alpm_packages*:: Package Functions
+*alpm_sync*:: Sync Functions
+*alpm_trans*:: Transaction Functions
+
+
+Configuration
+-------------
+See manlink:pacman.conf[5] for more details on configuring libalpm using the
+'pacman.conf' file.
+
+
+See Also
+--------
+manlink:pacman[8], manlink:makepkg[8], manlink:pacman.conf[5]
+
+include::footer.txt[]
diff --git a/doc/makepkg.8 b/doc/makepkg.8
deleted file mode 100644
index 9135be21..00000000
--- a/doc/makepkg.8
+++ /dev/null
@@ -1,146 +0,0 @@
-." 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 makepkg 8 "Feb 07, 2007" "makepkg version \*(VR" "\*(DS Utilities"
-.SH NAME
-makepkg \- package build utility
-
-.SH SYNOPSIS
-.B makepkg
-[\fIoptions\fR]
-
-.SH DESCRIPTION
-\fBmakepkg\fP is a script to automate the building of packages. All it needs is
-a build-capable Linux platform and a custom build script for each package you
-wish to build (known as a \fB\*(PB\fP). See
-.BR \*(PB (5)
-for details on creating your own build scripts.
-
-The advantage to a script-based build is that the work is only done once. Once
-you have the build script for a package, makepkg will do the rest: download and
-validate source files, check dependencies, configure the build-time 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 OPTIONS
-.TP
-.B \-b, --builddeps
-Build missing dependencies from source. When \fBmakepkg\fP finds missing
-build-time or run-time dependencies, it will look for the dependencies'
-\fB\*(PB\fP files under \fIABSROOT\fP (set in \fBmakepkg.conf\fP). If it finds
-them it will call \fBmakepkg\fP to build and install the missing dependencies.
-The child calls will be made with the \fB-b\fP and \fB-i\fP options.
-.TP
-.B \-c, --clean
-Clean up leftover work files and directories after a successful build.
-.TP
-.B \-C, --cleancache
-Removes all cached source files from the directory specified in \fISRCDEST\fP
-in \fBmakepkg.conf\fP.
-.TP
-.B \-d, --nodeps
-Do not perform any dependency checks. This will let you override and ignore any
-dependencies required. There is a good chance this option will break the build
-process if all of the dependencies are not installed.
-.TP
-.B \-e, --noextract
-Do not extract source files; use whatever source already exists in the src/
-directory. This is handy if you want to go into src and manually patch or tweak
-code, then make a package out of the result. Keep in mind that creating a patch
-may be a better solution to allow others to use your \fB\*(PB\fP.
-.TP
-.B \-f, --force
-\fBmakepkg\fP will not build a package if a built package already exists in the
-\fIPKGDEST\fP (set in \fBmakepkg.conf\fP) directory, which may default to the
-current directory. This allows the built package to be overwritten.
-.TP
-.B \-g, --geninteg
-For each source file in the source array of \fB\*(PB\fP, download the file if
-required and generate integrity checks. The integrity checks generated are
-determined by the value of the \fIINTEGRITY_CHECK\fP array in makepkg.conf.
-This output can be redirected into your \fB\*(PB\fP for source validation
-(makepkg -g >> \*(PB).
-.TP
-.B \-h, --help
-Output syntax and command line options.
-.TP
-.B \-i, --install
-Install or upgrade the package after a successful build using \fBpacman\fP.
-.TP
-.B \-L, --log
-Log the package build progress to a file. This file is stored in the build
-directory with a name similar to that of the built package.
-.TP
-.B \-m, --nocolor
-Disable color in output messages.
-.TP
-.B \-o, --nobuild
-Download and extract files only, but do not build them. Useful with the
-\fB--noextract\fP option if you wish to tweak the files in src/ before
-building.
-.TP
-.B \-p \fIbuildscript\fP
-Read the package script \fIbuildscript\fP instead of the default, \fI\*(PB\fP.
-.TP
-.B \-r, --rmdeps
-Upon successful build, remove any dependencies installed by \fBmakepkg\fP
-during dependency auto-resolution (using \fB-b\fP or \fB-s\fP).
-.TP
-.B \-R, --repackage
-Repackage contents of pkg/ without rebuilding the package. This is useful if
-you forgot a depend or install file in your \fB\*(PB\fP and the build itself
-will not change.
-.TP
-.B \-s, --syncdeps
-Install missing dependencies using \fBpacman\fP. When missing build-time or
-run-time dependencies are found, \fBpacman\fP will try to resolve them. If
-successful, the missing packages will be downloaded and installed.
-.TP
-.B \--asroot
-This option allows you to run \fBmakepkg\fP as root. You should not normally
-run \fBmakepkg\fP as root unless you know what you are doing. For any
-operations that require \fBpacman\fP, \fBsudo\fP is normally used; this switch
-will call \fBpacman\fP directly.
-.TP
-.B \--noconfirm
-(Passed to \fBpacman\fP) Prevent \fBpacman\fP from waiting for user input
-before proceeding with operations.
-.TP
-.B \--noprogressbar
-(Passed to \fBpacman\fP) Prevent \fBpacman\fP from displaying a progress bar;
-useful if you are redirecting makepkg output to file.
-
-.SH CONFIGURATION
-See
-.BR makepkg.conf (5)
-for more details on configuring \fBmakepkg\fP using the \fBmakepkg.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 makepkg.conf (5),
-.BR \*(PB (5),
-.BR pacman (8)
-
-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>
-.fi
-
-See the 'AUTHORS' file for additional contributors.
diff --git a/doc/makepkg.8.txt b/doc/makepkg.8.txt
new file mode 100644
index 00000000..02d29f32
--- /dev/null
+++ b/doc/makepkg.8.txt
@@ -0,0 +1,143 @@
+/////
+vim:set ts=4 sw=4 syntax=asciidoc noet:
+/////
+makepkg(8)
+==========
+
+Name
+----
+makepkg - package build utility
+
+
+Synopsis
+--------
+makepkg [options]
+
+
+Description
+-----------
+makepkg is a script to automate the building of packages. All it needs is a
+build-capable Linux platform and a custom build script for each package you
+wish to build (known as a PKGBUILD). See manlink:PKGBUILD[5] for details on
+creating your own build scripts.
+
+The advantage to a script-based build is that the work is only done once. Once
+you have the build script for a package, makepkg will do the rest: download and
+validate source files, check dependencies, configure the build-time settings,
+build the package, install the package into a temporary root, make
+customizations, generate meta-info, and package the whole thing up for pacman
+to use.
+
+makeworld can be used to rebuild an entire package group or the entire build
+tree. See `makeworld \--help` for syntax.
+
+Options
+-------
+*-A, \--ignorearch*::
+ Ignore a missing or incomplete arch field in the build script. This is
+ for rebuilding packages from source when the PKGBUILD may be slightly
+ outdated and not updated with an `$$arch=('yourarch')$$` field.
+
+*-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 makepkg.conf). If it finds them it
+ will call makepkg to build and install the missing dependencies. The
+ child calls will be made with the `-b` and `-i` options.
+
+*-c, \--clean*::
+ Clean up leftover work files and directories after a successful build.
+
+*-C, \--cleancache*::
+ Removes all cached source files from the directory specified in SRCDEST
+ in manlink:makepkg.conf[5].
+
+*-d, \--nodeps*::
+ Do not perform any dependency checks. This will let you override and
+ ignore any dependencies required. There is a good chance this option
+ will break the build process if all of the dependencies are not
+ installed.
+
+*-e, \--noextract*::
+ Do not extract source files; use whatever source already exists in the
+ src/ directory. This is handy if you want to go into src and manually
+ patch or tweak code, then make a package out of the result. Keep in mind
+ that creating a patch may be a better solution to allow others to use
+ your PKGBUILD.
+
+*-f, \--force*::
+ makepkg will not build a package if a built package already exists in
+ the PKGDEST (set in manlink:makepkg.conf[5]) directory, which may
+ default to the current directory. This allows the built package to be
+ overwritten.
+
+*-g, \--geninteg*::
+ For each source file in the source array of PKGBUILD, download the file
+ if required and generate integrity checks. The integrity checks
+ generated are determined by the value of the INTEGRITY_CHECK array in
+ manlink:makepkg.conf[5]. This output can be redirected into your
+ PKGBUILD for source validation (`makepkg -g >> PKGBUILD`).
+
+*-h, \--help*::
+ Output syntax and command line options.
+
+*-i, \--install*::
+ Install or upgrade the package after a successful build using
+ manlink:pacman[8].
+
+*-m, \--nocolor*::
+ Disable color in output messages.
+
+*-o, \--nobuild*::
+ Download and extract files only, but do not build them. Useful with the
+ `\--noextract` option if you wish to tweak the files in src/ before
+ building.
+
+*-p* <`buildscript`>::
+ Read the package script `buildscript` instead of the default, see
+ manlink:PKGBUILD[5].
+
+*-r, \--rmdeps*::
+ Upon successful build, remove any dependencies installed by makepkg
+ during dependency auto-resolution (using `-b` or `-s`).
+
+*-R, \--repackage*::
+ Repackage contents of pkg/ without rebuilding the package. This is
+ useful if you forgot a depend or install file in your PKGBUILD and the
+ build itself will not change.
+
+*-s, \--syncdeps*::
+ Install missing dependencies using pacman. When missing build-time or
+ run-time dependencies are found, pacman will try to resolve them. If
+ successful, the missing packages will be downloaded and installed.
+
+*\--asroot*::
+ Allow makepkg to run as root. This is for security purposes as it is
+ normally dangerous to do so. This will also disable use of fakeroot and
+ sudo.
+
+*\--source*::
+ Do not actually build the package, but build a source-only tarball. This
+ is useful for passing a single tarball to another program such as a
+ chroot, remote builder, or an AUR upload.
+
+*\--noconfirm*::
+ (Passed to pacman) Prevent pacman from waiting for user input before
+ proceeding with operations.
+
+*\--noprogressbar*::
+ (Passed to pacman) Prevent pacman from displaying a progress bar;
+ useful if you are redirecting makepkg output to file.
+
+
+Configuration
+-------------
+See manlink:makepkg.conf[5] for more details on configuring makepkg using the
+'makepkg.conf' file.
+
+
+See Also
+--------
+manlink:makepkg.conf[5], manlink:PKGBUILD[5], manlink:pacman[8]
+
+include::footer.txt[]
diff --git a/doc/makepkg.conf.5 b/doc/makepkg.conf.5
deleted file mode 100644
index 08be3fc8..00000000
--- a/doc/makepkg.conf.5
+++ /dev/null
@@ -1,152 +0,0 @@
-." 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 !xdelta)
-This array contains 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
-.B fakeroot
-Allow building packages as a non-root user. This is \fIhighly\fP recommended.
-.TP
-.B 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
-.B color
-Colorize output messages, making output easier to read.
-.TP
-.B 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 placing \fB!ccache\fP in the \fB\*(PB\fP options array.
-.TP
-.B xdelta
-Generate delta patch from previous to current package. This is mainly useful
-for large package upgrades that have only minor changes between versions where
-a binary diff will be a much smaller download. This is only useful if using
-the xdelta download script for pacman.
-.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
-.B 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
-.B docs
-Save doc and info directories. If you wish to delete doc and info directories,
-specify "!docs" in the array.
-.TP
-.B libtool
-Leave libtool (.la) files in packages. Specify "!libtool" to remove them.
-.TP
-.B 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>
-.fi
-
-See the 'AUTHORS' file for additional contributors.
diff --git a/doc/makepkg.conf.5.txt b/doc/makepkg.conf.5.txt
new file mode 100644
index 00000000..17e4bd87
--- /dev/null
+++ b/doc/makepkg.conf.5.txt
@@ -0,0 +1,154 @@
+/////
+vim:set ts=4 sw=4 syntax=asciidoc noet:
+/////
+makepkg.conf(5)
+===============
+
+Name
+----
+makepkg.conf - makepkg configuration file
+
+
+Synopsis
+--------
+{sysconfdir}/makepkg.conf, ~/.makepkg.conf
+
+
+Description
+-----------
+Configuration options for makekpg are stored in makepkg.conf. 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. However, only the variables described below are exported to the
+build environment.
+
+NOTE: 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.
+
+
+Options
+-------
+**DLAGENTS=(**\'protocol::/path/to/command [options]' ...**)**::
+ Sets the download agents used to fetch source files specified with a URL in
+ the manlink:PKGBUILD[5] file. Options can be specified for each command as
+ well; the download URL is placed on the end of the command. This is more
+ flexible than the former `FTPAGENT` variable, as any protocol can have a
+ download agent. Several examples are provided in the default makepkg.conf.
+
+**CARCH=**"carch"::
+ Specifies your computer architecture; possible values include such things
+ as ``i686'', ``x86_64'', ``ppc'', etc. This should be automatically set on
+ installation.
+
+**CHOST=**"chost"::
+ A string such as ``i686-pc-linux-gnu'', do not touch unless you know what
+ you are doing. This can be commented out by most users if desired.
+
+**CFLAGS=**"cflags"::
+ 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 gcc(1) for more details on the wide
+ variety of compiler flags available.
+
+**CXXFLAGS=**"cxxflags"::
+ Flags used for the C++ compiler; see CFLAGS for more info.
+
+**MAKEFLAGS=**"makeflags"::
+ This is often used to set the number of jobs used, for example, `-j2`.
+ Other flags that make accepts can also be passed.
+
+**BUILDENV=(**fakeroot !distcc color !ccache !xdelta**)**::
+ This array contains 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:
+
+ *fakeroot*;;
+ Allow building packages as a non-root user. This is highly recommended.
+
+ *distcc*;;
+ Use the distributed C/C++/ObjC compiler to spread compilation among
+ multiple machines. If this is enabled, `DISTCC_HOSTS` must be specified
+ as well.
+
+ *color*;;
+ Colorize output messages, making output easier to read.
+
+ *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 placing `!ccache` in the
+ PKGBUILD options array.
+
+ *xdelta*;;
+ Generate an xdelta binary patch from previous to current package. The
+ previous package must be available in the makepkg cache directory for
+ this to occur.
+
+**DISTCC_HOSTS=**"host1 ..."::
+ 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
+ `MAKEFLAGS`.
+
+**OPTIONS=(**strip !docs libtool emptydirs**)**::
+ This array contains 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:
+
+ *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.
+
+ *docs*;;
+ Save doc and info directories. If you wish to delete doc and info
+ directories, specify `!docs' in the array.
+
+ *libtool*;;
+ Leave libtool (.la) files in packages. Specify `!libtool' to remove
+ them.
+
+ *emptydirs*;;
+ Leave empty directories in packages.
+
+**INTEGRITY_CHECK=(**check1 ...**)**::
+ 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`.
+
+**DOC_DIRS=(**usr/{,share/}{info,doc} ...**)**::
+ If "!docs" is specified in the OPTIONS 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.
+
+**PKGDEST=**"/path/to/folder"::
+ If this value is not set, packages will by default be placed in the
+ current directory (location of the manlink:PKGBUILD[5]). Many people
+ like to keep all their packages in one place so this option allows
+ this behavior. A common location is ``/home/packages''.
+
+**SRCDEST=**"/path/to/folder"::
+ 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.
+
+**PACKAGER=**"John Doe <john@doe.com>"::
+ 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.
+
+*BUILDSCRIPT*, *PKGEXT*, *SRCEXT*, *DB_COMPRESSION*, *DB_CHECKSUMS*::
+ Do not touch these unless you know what you are doing.
+
+
+See Also
+--------
+manlink:makepkg[8], manlink:pacman[8], manlink:PKGBUILD[5]
+
+include::footer.txt[]
diff --git a/doc/pacman.8 b/doc/pacman.8
deleted file mode 100644
index 79097783..00000000
--- a/doc/pacman.8
+++ /dev/null
@@ -1,293 +0,0 @@
-." 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 pacman 8 "Feb 07, 2007" "pacman version \*(VR" "\*(DS Utilities"
-.SH NAME
-pacman \- package manager utility
-
-.SH SYNOPSIS
-.B pacman
-<\fIoperation\fR> [\fIoptions\fR] [\fIpackages\fR]
-
-.SH DESCRIPTION
-\fBpacman\fP is a \fIpackage management\fP utility that tracks installed
-packages on a Linux system. It features dependency support, package groups,
-install and uninstall hooks, and the ability to sync your local machine with a
-remote ftp server to automatically upgrade packages. \fBpacman\fP packages are
-a zipped tar format.
-
-Since version 3.0.0, \fBpacman\fP has been the frontend to \fBlibalpm\fP, the
-"Arch Linux Package Management" library. This library allows alternative front
-ends to be written (for instance, a GUI front end).
-
-.SH OPERATIONS
-.TP
-.B \-A, --add (deprecated)
-Add a package to the system. Either a URL or file path can be specified. The
-package will be uncompressed into the installation root and the database will
-be updated. The package will not be installed if another version is already
-installed. NOTE: please use \fB--upgrade\fP in place of this option.
-.TP
-.B \-F, --freshen
-This is like \fB--upgrade\fP except it will only upgrade packages already
-installed on the system.
-.TP
-.B \-Q, --query
-Query the package database. This operation allows you to view installed
-packages and their files, as well as meta-information 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
-is used. See \fBREMOVE OPTIONS\fP below.
-.TP
-.B \-S, --sync
-Synchronize packages. Packages are installed directly from the ftp servers,
-including all dependencies required to run the packages. For example,
-\fBpacman -S qt\fP will download and install \fBqt\fP and all the packages it
-depends on. You can also use \fBpacman -Su\fP to upgrade all packages that are
-out of date. See \fBSYNC OPTIONS\fP below.
-.TP
-.B \-U, --upgrade
-Upgrade or add a package to the system. Either a URL or file path can be
-specified. This is 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 \--ask \fInumber\fP
-Pre-specify answers to questions. It is doubtful whether this option even
-works, so I would not recommend using it. TODO: document this more, as I have
-no idea how it works or when you would use it, or if we should just dump it.
-.TP
-.B \-b, --dbpath \fIpath\fP
-Specify an alternative database location (default is "/var/lib/pacman/"). This
-should not be used unless you know what you are doing.
-.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.
-.TP
-.B \-f, --force
-Bypass file conflict checks and overwrite 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 \fIpath\fP
-Specify an alternative installation root (default is "/"). This should
-\fInot\fP be used as a way to install software into /usr/local instead of /usr.
-This option is 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 and cache location to use.
-.TP
-.B \-v, --verbose
-Output more status messages, such as the Root and DBPath.
-.TP
-.B \--cachedir \fIdir\fP
-Specify an alternative package cache location (default is
-"/var/cache/pacman/pkg/"). This should not be used unless you know what you are
-doing.
-.TP
-.B \--config \fIfilepath\fP
-Specify an alternate configuration file.
-.TP
-.B \--noconfirm
-Bypass any and all "Are you sure?" messages. It's not a good idea to do this
-unless you want to run pacman from a script.
-.TP
-.B \--noprogressbar
-Do not show a progress bar when downloading files. This can be useful for
-scripts that call pacman and capture the output.
-.TP
-.B \--noscriptlet
-If an install scriptlet exists, do not execute it. Do not use this unless you
-know what you are doing.
-
-.SH QUERY OPTIONS
-.TP
-.B \-c, --changelog
-View the ChangeLog of a package. Not every package will provide one but it
-will be shown if available.
-.TP
-.B \-e, --orphans
-List all packages that were pulled in by a previously installed package but no
-longer required by any installed package.
-.TP
-.B \-g, --groups
-Display all packages that are members of a named group. If not name is
-specified, list all grouped packages.
-.TP
-.B \-i, --info
-Display information on a given package. The \fB-p\fP option can be used if
-querying a package file instead of the local database.
-.TP
-.B \-l, --list
-List all files owned by a given package. Multiple packages can be specified on
-the command line.
-.TP
-.B \-m, --foreign
-List all packages that were not found in the sync database(s). Typically these
-are packages that were downloaded manually and installed with \fB--upgrade\fP.
-.TP
-.B \-o, --owns \fIfile\fP
-Search for the package that owns \fIfile\fP.
-.TP
-.B \-p, --file
-Signifies that the package supplied on the command line is a file and not an
-entry in the database. The file will be decompressed and queried. This is
-useful in combination with \fB--info\fP and \fB--list\fP.
-.TP
-.B \-s, --search \fIregexp\fP
-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.
-
-.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
-removed from the system the database is checked to see if the file should be
-renamed with a .pacsave extension.
-.TP
-.B \-s, --recursive
-Remove each target specified including all dependencies, provided that (A) they
-are not required by other packages; and (B) they were not explicitly installed
-by the user. This option is analogous to a backwards \fB--sync\fP operation.
-
-.SH SYNC OPTIONS
-.TP
-.B \-c, --clean
-Remove old packages from the cache to free up disk space. When \fBpacman\fP
-downloads packages, it saves them in \fI/var/cache/pacman/pkg\fP. Use one
-\fB--clean\fP switch to remove \fIold\fP packages; use two to remove \fIall\fP
-packages from the cache.
-.TP
-.B \-e, --dependsonly
-Install all dependencies of a package, but not the specified package itself.
-This is pretty useless and we're not sure why it even exists.
-.TP
-.B \-g, --groups
-Display all the members for each package group specified. If no group names
-are provided, all groups will be listed; pass the flag twice to view all
-groups and their members.
-.TP
-.B \-i, --info
-Display dependency and other information for a given package. This will search
-through all repositories for a matching package.
-.TP
-.B \-l, --list
-List all packages in the specified repositories. Multiple repositories can be
-specified on the command line.
-.TP
-.B \-p, --print-uris
-Print out URIs for each package that will be installed, including any
-dependencies yet to be installed. These can be piped to a file and downloaded
-at a later time, using a program like wget.
-.TP
-.B \-s, --search \fIregexp\fP
-This will search each package in the sync databases for names or descriptions
-that match \fIregexp\fP.
-.TP
-.B \-u, --sysupgrade
-Upgrades all packages that are out of date. Each currently-installed package
-will be examined and upgraded if a newer package exists. A report of all
-packages to upgrade will be presented and the operation 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 server(s) defined in
-\fBpacman.conf\fP. This should typically be used each time you use
-\fB--sysupgrade\fP or \fB-u\fP. Passing two \fB--refresh\fP or \fB-y\fP flags
-will force a refresh of all package lists even if they are thought to be
-up to date.
-.TP
-.B \--ignore \fIpackage\fP
-Directs \fBpacman\fP to ignore upgrades of \fIpackage\fP even if there is one
-available.
-
-.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, 3 md5 hashes are used 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 overwrites are not an issue Install the new
-file.
-.TP
-original=\fBX\fP, current=\fBX\fP, new=\fBY\fP
-The current file is the same as the original but the new one differs. Since
-the user did not ever modify the file, and the new one may contain improvements
-or bugfixes, 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. Leave the current file in place.
-.TP
-original=\fBX\fP, current=\fBY\fP, new=\fBY\fP
-The new file is identical to the current file. Install the new file.
-.TP
-original=\fBX\fP, current=\fBY\fP, new=\fBZ\fP
-All three files are different, so install the new file with a .pacnew extension
-and warn the user. The user must then manually merge any necessary changes into
-the original file.
-
-.SH CONFIGURATION
-See
-.BR pacman.conf (5)
-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
-to be wrong, send us an email with as much detail as possible to
-<pacman-dev@archlinux.org>.
-
-.SH SEE ALSO
-.BR pacman.conf (5),
-.BR makepkg (8),
-.BR libalpm (3)
-
-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>
-.fi
-
-See the 'AUTHORS' file for additional contributors.
diff --git a/doc/pacman.8.txt b/doc/pacman.8.txt
new file mode 100644
index 00000000..5e5d2f55
--- /dev/null
+++ b/doc/pacman.8.txt
@@ -0,0 +1,313 @@
+/////
+vim:set ts=4 sw=4 syntax=asciidoc noet:
+/////
+pacman(8)
+=========
+
+Name
+----
+pacman - package manager utility
+
+
+Synopsis
+--------
+'pacman' <operation> [options] [packages]
+
+
+Description
+-----------
+Pacman is a package management utility that tracks installed packages on a Linux
+system. It features dependency support, package groups, install and uninstall
+hooks, and the ability to sync your local machine with a remote ftp server to
+automatically upgrade packages. Pacman packages are a zipped tar format.
+
+Since version 3.0.0, pacman has been the frontend to manlink:libalpm[3], the
+"Arch Linux Package Management" library. This library allows alternative front
+ends to be written (for instance, a GUI front end).
+
+
+Operations
+----------
+*-A, \--add* (deprecated)::
+ Add a package to the system. Either a URL or file path can be specified.
+ The package will be uncompressed into the installation root and the
+ database will be updated. The package will not be installed if another
+ version is already installed. *NOTE*: please use '\--upgrade' in place of
+ this option.
+
+*-F, \--freshen*::
+ This is like '\--upgrade' except it will only upgrade packages already
+ installed on the system.
+
+*-Q, \--query*::
+ Query the package database. This operation allows you to view installed
+ packages and their files, as well as meta-information 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 <<QO,Query Options>> below.
+
+*-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 `.pacsave` extension unless the
+ '\--nosave' option is used. See <<RO,Remove Options>> below.
+
+*-S, \--sync*::
+ Synchronize packages. Packages are installed directly from the ftp
+ servers, including all dependencies required to run the packages. For
+ example, `pacman -S qt` will download and install qt and all the
+ packages it depends on. You can also use `pacman -Su` to upgrade all
+ packages that are out of date. See <<SO,Sync Options>> below.
+
+*-U, \--upgrade*::
+ Upgrade or add a package to the system. Either a URL or file path can be
+ specified. This is a "remove-then-add" process. See <<HCF,Handling Config
+ Files>> for an explanation on how pacman takes care of config files.
+
+*-V, \--version*::
+ Display version and exit.
+
+*-h, \--help*::
+ Display syntax for the given operation. If no operation was supplied
+ then the general syntax is shown.
+
+
+Options
+-------
+*\--asdeps*::
+ Install packages non-explicitly; in other works, fake their install reason
+ to be installed as a dependency. This is useful for makepkg and other
+ build from source tools that need to install dependencies before building
+ the package.
+
+*\--ask* <'number'>::
+ Pre-specify answers to questions. It is doubtful whether this option
+ even works, so I would not recommend using it. *TODO*: document this
+ more, as I have no idea how it works or when you would use it, or if we
+ should just dump it.
+
+*-b, \--dbpath* <'path'>::
+ Specify an alternative database location (default is ``/var/lib/pacman'').
+ This should not be used unless you know what you are doing.
+
+*-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.
+
+*-f, \--force*::
+ Bypass file conflict checks and overwrite 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.
+
+*-r, \--root* <'path'>::
+ Specify an alternative installation root (default is ``/''). This should
+ not be used as a way to install software into ``/usr/local'' instead of
+ ``/usr''. This option is used if you want to install a package on a
+ temporary mounted partition which is "owned" by another system.
+
+*-v, --verbose*::
+ Output more status messages, such as the Root, DBPath, CacheDir, etc.
+
+*\--cachedir* <'dir'>::
+ Specify an alternative package cache location (default is
+ ``/var/cache/pacman/pkg''). Multiple cache directories can be specified,
+ and they are tried in the order they are passed to pacman.
+
+*\--config* <'file'>::
+ Specify an alternate configuration file.
+
+*\--noconfirm*::
+ Bypass any and all "Are you sure?" messages. It's not a good idea to do
+ this unless you want to run pacman from a script.
+
+*\--noprogressbar*::
+ Do not show a progress bar when downloading files. This can be useful
+ for scripts that call pacman and capture the output.
+
+*\--noscriptlet*::
+ If an install scriptlet exists, do not execute it. Do not use this
+ unless you know what you are doing.
+
+
+Query Options[[QO]]
+-------------------
+*-c, \--changelog*::
+ View the ChangeLog of a package. Not every package will provide one but
+ it will be shown if available.
+
+*-d, \--deps*::
+ List all packages installed as dependencies. This option can be combined
+ with '-t' for listing real orphans- packages that were installed as
+ dependencies but are no longer required by any installed package. ('-Qdt'
+ is equivalent to the pacman 3.0.X '-Qe' option.)
+
+*-e, \--explicit*::
+ List all packages explicitly installed. This option can be combined with
+ '-t' to list top-level packages- those packages that were explicitly
+ installed but are not required by any other package. ('-Qet' is equivalent
+ to the pacman 2.9.X '-Qe' option.)
+
+*-g, \--groups*::
+ Display all packages that are members of a named group. If not name is
+ specified, list all grouped packages.
+
+*-i, \--info*::
+ Display information on a given package. The '-p' option can be used if
+ querying a package file instead of the local database.
+
+*-l, \--list*::
+ List all files owned by a given package. Multiple packages can be
+ specified on the command line.
+
+*-m, \--foreign*::
+ Restrict or filter output to packages that were not found in the sync
+ database(s). Typically these are packages that were downloaded manually
+ and installed with '\--upgrade'.
+
+*-o, \--owns* <'file'>::
+ Search for the package that owns file. The path can be relative or
+ absolute.
+
+*-p, \--file*::
+ Signifies that the package supplied on the command line is a file and
+ not an entry in the database. The file will be decompressed and queried.
+ This is useful in combination with '\--info' and '\--list'.
+
+*-s, \--search* <'regexp'>::
+ This will search each locally-installed package for names or
+ descriptions that match `regexp`.
+
+*-t, \--orphans*::
+ Restrict or filter output to packages not required by any currently
+ installed package.
+
+*-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 '-Sy'.
+
+*\--test*::
+ Run some brief checks looking at the consistency of the local database.
+
+
+Remove Options[[RO]]
+--------------------
+*-c, \--cascade*::
+ Remove all target packages, as well as all packages that depend on one
+ or more target packages. This operation is recursive.
+
+*-k, \--keep*::
+ Removes the database entry only. Leaves all files in place.
+
+*-n, \--nosave*::
+ Instructs pacman to ignore file backup designations. Normally, when a
+ file is removed from the system the database is checked to see if the
+ file should be renamed with a ``.pacsave'' extension.
+
+*-s, \--recursive*::
+ Remove each target specified including all dependencies, provided that
+ (A) they are not required by other packages; and (B) they were not
+ explicitly installed by the user. This option is analogous to a
+ backwards '\--sync' operation.
+
+
+Sync Options[[SO]]
+------------------
+*-c, \--clean*::
+ Remove old packages from the cache to free up disk space. When pacman
+ downloads packages, it saves them in ``/var/cache/pacman/pkg''. Use one
+ '\--clean' switch to remove old packages; use two to remove all packages
+ from the cache.
+
+*-e, \--dependsonly*::
+ Install all dependencies of a package, but not the specified package
+ itself. This is pretty useless and we're not sure why it even exists.
+
+*-g, \--groups*::
+ Display all the members for each package group specified. If no group
+ names are provided, all groups will be listed; pass the flag twice to
+ view all groups and their members.
+
+*-i, \--info*::
+ Display dependency and other information for a given package. This will
+ search through all repositories for a matching package.
+
+*-l, \--list*::
+ List all packages in the specified repositories. Multiple repositories
+ can be specified on the command line.
+
+*-p, \--print-uris*::
+ Print out URIs for each package that will be installed, including any
+ dependencies yet to be installed. These can be piped to a file and
+ downloaded at a later time, using a program like wget.
+
+*-s, \--search* <'regexp'>::
+ This will search each package in the sync databases for names or
+ descriptions that match `regexp`.
+
+*-u, \--sysupgrade*::
+ Upgrades all packages that are out of date. Each currently-installed
+ package will be examined and upgraded if a newer package exists. A
+ report of all packages to upgrade will be presented and the operation
+ will not proceed without user confirmation. Dependencies are
+ automatically resolved at this level and will be installed/upgraded if
+ necessary.
+
+*-w, \--downloadonly*::
+ Retrieve all packages from the server, but do not install/upgrade
+ anything.
+
+*-y, \--refresh*::
+ Download a fresh copy of the master package list from the server(s)
+ defined in pacman.conf. This should typically be used each time you use
+ '\--sysupgrade' or '-u'. Passing two '\--refresh' or '-y' flags will force
+ a refresh of all package lists even if they are thought to be up to date.
+
+*\--ignore* <'package'>::
+ Directs pacman to ignore upgrades of package even if there is one
+ available.
+
+
+Handling Config Files[[HCF]]
+----------------------------
+Pacman uses the same logic as rpm to determine action against files that are
+designated to be backed up. During an upgrade, 3 md5 hashes are used 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:
+
+original=X, current=X, new=X::
+ All three files are the same, so overwrites are not an issue Install the
+ new file.
+
+original=X, current=X, new=Y::
+ The current file is the same as the original but the new one differs.
+ Since the user did not ever modify the file, and the new one may contain
+ improvements or bugfixes, install the new file.
+
+original=X, current=Y, new=X::
+ Both package versions contain the exact same file, but the one on the
+ filesystem has been modified. Leave the current file in place.
+
+original=X, current=Y, new=Y::
+ The new file is identical to the current file. Install the new file.
+
+original=X, current=Y, new=Z::
+ All three files are different, so install the new file with a '.pacnew'
+ extension and warn the user. The user must then manually merge any
+ necessary changes into the original file.
+
+
+Configuration
+-------------
+See manlink:pacman.conf[5] for more details on configuring pacman using the
+'pacman.conf' file.
+
+
+See Also
+--------
+manlink:pacman.conf[5], manlink:makepkg[8], manlink:libalpm[3]
+
+include::footer.txt[]
diff --git a/doc/pacman.conf.5 b/doc/pacman.conf.5
deleted file mode 100644
index f7304aa5..00000000
--- a/doc/pacman.conf.5
+++ /dev/null
@@ -1,143 +0,0 @@
-." 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 \*(PB 5 "Feb 07, 2007" "pacman.conf version \*(VR" "\*(DS Files"
-.SH NAME
-pacman.conf \- pacman package manager configuration file
-
-.SH DESCRIPTION
-\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
-.nf
-#
-# pacman.conf
-#
-[options]
-NoUpgrade = etc/passwd etc/group etc/shadow
-NoUpgrade = etc/fstab
-
-[current]
-Include = /etc/pacman.d/current
-
-[custom]
-Server = file:///home/pkgs
-.fi
-.RE
-
-.SH OPTIONS
-.TP
-.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 = \fIpath/to/cache/dir\fP
-Overrides the default location of the package cache directory. The default is
-\fIvar/cache/pacman\fP.
-.TP
-.B HoldPkg = \fIpackage\fP ...
-If a user tries to \fB--remove\fP a package that's listed in \fBHoldPkg\fI,
-\fBpacman\fP will ask for confirmation before proceeding.
-.TP
-.B IgnorePkg = \fIpackage\fP ...
-Instructs \fBpacman\fP to ignore any upgrades for this package when performing a
-\fB--sysupgrade\fP.
-.TP
-.B Include = \fIpath\fP
-Include another config file. This file can include repositories or general
-configuration options.
-.TP
-.B XferCommand = \fI/path/to/command %u\fP
-If set, an external program will be used to download all remote files. All
-instances of \fB%u\fP will be replaced with the download URL. 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 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 = \fIfile\fP ...
-All files listed with a \fBNoUpgrade\fP directive will never be touched during
-a package install/upgrade. Do \fInot\fP include the leading slash when
-specifying files.
-.TP
-.B NoExtract = \fIfile\fP ...
-All files listed with a \fBNoExtract\fP directive will never be extracted from
-a package into the filesystem. This can be useful when you don't want part of a
-package to be installed. For example, if your httpd root uses an index.php,
-then you would not want the index.html file to be extracted from the
-\fBapache\fP package.
-.TP
-.B UseSyslog
-Log action messages through \fBsyslog()\fP. This will insert log entries into
-\fI/var/log/messages\fP or equivalent.
-.TP
-.B LogFile = \fI/path/to/file\fP
-Log actions directly to a file. Default is \fI/var/log/pacman.log\fP.
-.TP
-.B ShowSize
-Display the size of individual packages for \fB--sync\fP and \fB--query\fP
-modes.
-
-.SH REPOSITORY SECTIONS
-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 (the two above are 'current' and 'custom'). Locations are
-defined with the \fBServer\fP directive and follow a URL naming structure. If
-you want to use a local directory, you can specify the full path with
-a 'file://' prefix, as shown above.
-
-The order of repositories in the file matters; repositories listed first will
-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.
-
-.RS
-.nf
-repo-add /home/pkgs/custom.db.tar.gz /home/pkgs/*.pkg.tar.gz
-.fi
-.RE
-
-The above command will generate a compressed database named
-\fI/home/pkgs/custom.db.tar.gz\fP. 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 \fBpacman\fP's --refresh option.
-
-For more information on the \fBrepo-add\fP command, use \fB repo-add --help\fP.
-
-.SH SEE ALSO
-.BR pacman (8),
-.BR libalpm (3)
-
-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>
-.fi
-
-See the 'AUTHORS' file for additional contributors.
diff --git a/doc/pacman.conf.5.txt b/doc/pacman.conf.5.txt
new file mode 100644
index 00000000..d422a4b9
--- /dev/null
+++ b/doc/pacman.conf.5.txt
@@ -0,0 +1,147 @@
+/////
+vim:set ts=4 sw=4 syntax=asciidoc noet:
+/////
+pacman.conf(5)
+==============
+
+Name
+----
+pacman.conf - pacman package manager configuration file
+
+
+Synopsis
+--------
+{sysconfdir}/pacman.conf
+
+
+Description
+-----------
+Pacman, using manlink:libalpm[3], will attempt to read pacman.conf each time it
+is invoked. This configuration file is divided into sections or repositories.
+Each section defines a package repository that pacman can use when searching
+for packages in '\--sync' mode. The exception to this is the options section,
+which defines global options.
+
+
+Example
+-------
+--------
+#
+# pacman.conf
+#
+[options]
+NoUpgrade = etc/passwd etc/group etc/shadow
+NoUpgrade = etc/fstab
+
+[current]
+Include = /etc/pacman.d/current
+
+[custom]
+Server = file:///home/pkgs
+--------
+
+
+Options
+-------
+*RootDir =* path/to/root::
+ Set the default root directory for pacman to install to.
+
+*DBPath =* path/to/db/dir::
+ Overrides the default location of the toplevel database directory.
+ The default is ``/var/lib/pacman/''.
+
+*CacheDir =* path/to/cache/dir::
+ Overrides the default location of the package cache directory. The default
+ is ``/var/cache/pacman/pkg/''. Multiple cache directories can be specified,
+ and they are tried in the order they are listed in the config file. If a
+ file is not found in any cache directory, it will be downloaded to the
+ first cache directory with write access.
+
+*LogFile =* '/path/to/file'::
+ Log actions directly to a file. Default is ``/var/log/pacman.log''.
+
+*HoldPkg =* package ...::
+ If a user tries to '\--remove' a package that's listed in `HoldPkg`,
+ pacman will ask for confirmation before proceeding.
+
+*IgnorePkg =* package ...::
+ Instructs pacman to ignore any upgrades for this package when performing
+ a '\--sysupgrade'.
+
+*Include =* path::
+ Include another config file. This file can include repositories or
+ general configuration options.
+
+*XferCommand =* /path/to/command %u::
+ If set, an external program will be used to download all remote files.
+ All instances of `%u` will be replaced with the download URL. If present,
+ instances of `%o` 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 built-in
+ http/ftp support, or need the more advanced proxy support that comes with
+ utilities like wget.
+
+*NoPassiveFtp*::
+ Disables passive ftp connections when downloading packages. (aka Active Mode)
+
+*NoUpgrade =* file ...::
+ All files listed with a `NoUpgrade` directive will never be touched during
+ a package install/upgrade. Do not include the leading slash when specifying
+ files.
+
+*NoExtract =* file ...::
+ All files listed with a `NoExtract` directive will never be extracted from
+ a package into the filesystem. This can be useful when you don't want part
+ of a package to be installed. For example, if your httpd root uses an
+ 'index.php', then you would not want the 'index.html' file to be extracted
+ from the 'apache' package.
+
+*UseSyslog*::
+ Log action messages through syslog(). This will insert log entries into
+ ``/var/log/messages'' or equivalent.
+
+*ShowSize*::
+ Display the size of individual packages for '\--sync' and '\--query' modes.
+
+
+Repository Sections
+-------------------
+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 (the two above are 'current' and 'custom'). Locations are
+defined with the 'Server' directive and follow a URL naming structure. If you
+want to use a local directory, you can specify the full path with a ``file://''
+prefix, as shown above.
+
+The order of repositories in the file matters; repositories listed first will
+take precedence over those listed later in the file when packages in two
+repositories have identical names, regardless of version number.
+
+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 '\--upgrade'
+option. All you need to do is generate a compressed package database in the
+directory with these packages so pacman can find it when run with '\--refresh'.
+
+ repo-add /home/pkgs/custom.db.tar.gz /home/pkgs/*.pkg.tar.gz
+
+The above command will generate a compressed database named
+'/home/pkgs/custom.db.tar.gz'. Note that the database must be of the form
+'{treename}.db.tar.gz', where '{treename}' is the name of the section defined in
+the configuration file. That's it! Now configure your custom 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.
+
+For more information on the repo-add command, see ``repo-add \--help'' or
+manlink:repo-add[8].
+
+
+See Also
+--------
+manlink:pacman[8], manlink:libalpm[3]
+
+include::footer.txt[]
diff --git a/doc/repo-add.8.txt b/doc/repo-add.8.txt
new file mode 100644
index 00000000..27e0e93f
--- /dev/null
+++ b/doc/repo-add.8.txt
@@ -0,0 +1,51 @@
+/////
+vim:set ts=4 sw=4 syntax=asciidoc noet:
+/////
+repo-add(8)
+==========
+
+Name
+----
+////
+* If we use this below line, the manpage name comes out all weird. We also
+* can't use two separate lines, which is quite annoying. *
+repo-add, repo-remove - package database maintenance utilities
+////
+repo-add - package database maintenance utility
+
+
+Synopsis
+--------
+repo-add <path-to-db> [--force] <package> ...
+
+repo-remove <path-to-db> <packagename> ...
+
+
+Description
+-----------
+repo-add and repo-remove are two scripts to help build a package database for
+packages built with manlink:makepkg[8] and installed with manlink:pacman[8].
+
+repo-add will update a package database by reading a built package file.
+Multiple packages to add can be specified on the command line.
+
+repo-remove will update a package database by removing the package name
+specified on the command line. Multiple packages to remove can be specified
+on the command line.
+
+
+Options
+-------
+*--force* (repo-add only)::
+ Add a force entry to the sync database, which tells pacman to skip version
+ number comparison and update the package regardless. This flag can be
+ specified in the middle of the command line, with any packages listed
+ before the flag being added as normal entries, and any specified after
+ being marked as force upgrades.
+
+
+See Also
+--------
+manlink:makepkg[8], manlink:pacman[8]
+
+include::footer.txt[]