* Nice overhaul of manpages. It is at least a start.

* Alphabetized options in pacman usage.

1 files changed, 130 insertions, 440 deletions

diff --git a/doc/makepkg.8 b/doc/makepkg.8
index 51cb50ce..90944d93 100644
--- a/doc/makepkg.8
+++ b/doc/makepkg.8
@@ -1,455 +1,145 @@
-.TH makepkg 8 "January 30, 2006" "makepkg #VERSION#" ""
+." the string declarations are a start to try and make distro independent
+.ds DS Arch Linux
+.ds PB PKGBUILD
+.ds VR 3.0.0
+.TH makepkg 8 "Feb 07, 2007" "makepkg version \*(VR" "\*(DS Utilities"
 .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 options
-This array allows you to override some of makepkg's default behaviour
-when building packages.  To set an option, just include the option name
-in the \fBoptions\fP array.
-.TP
-.RS
-\fIAvailable Options:\fP
-.RS
-.TP
-.B FORCE
-force the package to be upgraded by \fB--sysupgrade\fP, even
-if its an older version.
-.TP
-.B KEEPDOCS
-do not remove /usr/share/doc and /usr/share/info directories.
-.TP
-.B NOSTRIP
-do not strip debugging symbols from binaries and libraries.
-.RE
-.RE
-
-.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
-This field specifies the license(s) that apply to the package.  Commonly-used
-licenses are typically found in \fI/usr/share/licenses/common\fP.  If you
-see the package's license there, simply reference it in the license field
-(eg, \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 itself should be placed in a directory called
-\fI$startdir/pkg/usr/share/licenses/$pkgname\fP.
-.TP
-.RE
-If multiple licenses are applied, use the array form: \fBlicense=('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 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 >>PKGBUILD\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 SYNOPSIS
+.B makepkg
+[\fIoptions\fR]
 
-.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 "\-B, \-\-noccache"
-Do not use ccache during build.
-.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 "\-e, \-\-noextract"
-Do not extract source files.  Instead, use whatever already exists in the
-src/ directory.  This is handy if you want to go into src and manually
-patch/tweak code, then make a package out of the result.
-.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 "\-S, \-\-sudosync"
-Install missing dependencies using pacman and sudo. This is the same as \fB-s\fP
-except that makepkg will call pacman with sudo. This means you don't have to
+.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). 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 \-B, --noccache
+Disable the use of \fBccache\fP during build (useful for select packages that
+have problems with \fBccache\fP).
+.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 \-j \fIjobs\fP
+Sets MAKEFLAGS="-j\fIjobs\fP" before building the package. This is useful for
+overriding the \fIMAKEFLAGS\fP setting in \fBmakepkg.conf\fP.
+.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 \-S, --sudosync
+Install missing dependencies using \fBpacman\fP and \fBsudo\fP. This is the
+same as \fB-s\fP except that \fBsudo\fP is used, meaning you do not have to
 build as root to use dependency auto-resolution.
 .TP
-.B "\-w <destdir>"
-Write the resulting package file to the directory \fI<destdir>\fP instead of the
-current working directory.
-.TP
-.B "\-\-noconfirm"
-When calling pacman to resolve dependencies or conflicts, makepkg can pass
-the \fI--noconfirm\fP option to it so it does not wait for any user
-input before proceeding with operations.
+.B \--noconfirm
+(Passed to \fBpacman\fP) Prevent \fBpacman\fP from waiting for user input
+before proceeding with operations.
 .TP
-.B "\-\-noprogressbar"
-When calling pacman, makepkg can pass the \fI--noprogressbar\fP option to it.
-This is useful if one is directing makepkg's output to a non-terminal (ie, a file).
+.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
-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.
+Configuration options are stored in \fBmakepkg.conf\fP.  This file is sourced,
+so you can include any special compiler flags you wish to use. This is helpful
+for building for different architectures, or with different optimizations.
+
+\fBNOTE:\fP This does not guarantee that all package Makefiles will use your
+exported variables.  Some of them are non-standard...
+
+The file is fairly well commented, so follow directions given there for
+customization.
 
-\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.
+.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.
 
-See the Arch Linux Documentation for package-building guidelines if you wish
-to contribute packages to the Arch Linux project.
-.SH AUTHOR
+.SH AUTHORS
 .nf
 Judd Vinet <jvinet@zeroflux.org>
+Aurelien Foret <aurelien@archlinux.org>
+Aaron Griffin <aaron@archlinux.org>
+Dan McGee <dan@archlinux.org>
+See the 'AUTHORS' file for additional contributors.
 .fi