doc/PKGBUILD: misc changes

Signed-off-by: Florian Pritz <bluewind@xinu.at>
Signed-off-by: Dan McGee <dan@archlinux.org>

doc/PKGBUILD.5.txt

@@ -16,12 +16,12 @@ PKGBUILD
 
 Description
 -----------
-This manual page is meant to describe general rules about PKGBUILDs. Once a
+This manual page describes general rules about PKGBUILDs. Once a
 PKGBUILD is written, the actual package is built using makepkg and installed
 with pacman.
 
-NOTE: An example PKGBUILD, useful for reference, is located in '{pkgdatadir}'.
+NOTE: An example PKGBUILD, useful for reference, is located in '{pkgdatadir}'
-Also located there are other example files such as a ChangeLog and an install
+along with other example files such as a ChangeLog and an install
 script. You can copy the provided PKGBUILD.proto file to a new package build
 directory and make customizations to suit your needs.
 
@@ -30,18 +30,18 @@ Options and Directives
 ----------------------
 The following is a list of standard options and directives available for use
 in a PKGBUILD. These are all understood and interpreted by makepkg, and most
-will be directly transferred to the built package.
+of them will be directly transferred to the built package.
 
 If you need to create any custom variables for use in your build process, it is
-recommended to name your custom variables with an '_' (underscore) prefix.
+recommended to prefix their name with an '_' (underscore).
 This will prevent any possible name clashes with internal makepkg variables.
 For example, to store the base kernel version in a variable, use something
 similar to `$_basekernver`.
 
 *pkgname (array)*::
-	The name of the package. This has be a unix-friendly name as it will be
+	The name of the package or an array of names for split packages.
-	used in the package filename. Members of the array are not allowed to start
+	Because it will be used in the package filename, this has to be unix-friendly.
-	with hyphens.
+	Members of the array are not allowed to start with hyphens.
 
 *pkgver*::
 	The version of the software as released from the author (e.g. '2.7.1').
@@ -50,13 +50,13 @@ similar to `$_basekernver`.
 *pkgrel*::
 	This is the release number specific to the Arch Linux release. This
 	allows package maintainers to make updates to the package's configure
-	flags, for example. A pkgrel of '1' is typically used for each upstream
+	flags, for example. This is typically (re)set to '1' for each new upstream
-	software release and is incremented for intermediate PKGBUILD updates. The
+	software release and incremented for intermediate PKGBUILD updates. The
 	variable is not allowed to contain hyphens.
 
 *pkgdesc*::
 	This should be a brief description of the package and its functionality.
-	Try to keep the description to one line of text.
+	Try to keep the description to one line of text and not use the package's name.
 
 *epoch*::
 	Used to force the package to be seen as newer than any previous versions
@@ -69,18 +69,18 @@ similar to `$_basekernver`.
 
 *url*::
 	This field contains a URL that is associated with the software being
-	packaged. This is typically the project's website.
+	packaged. 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
+	Commonly used licenses can be 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
+	available in '/usr/share/licenses/common', then you should include it
 	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
+	'$pkgdir/usr/share/licenses/$pkgname/' when building the package. If
-	multiple licenses are applicable for a package, list all of them:
+	multiple licenses are applicable, list all of them:
 	`license=('GPL' 'FDL')`.
 
 *install*::
@@ -97,22 +97,21 @@ similar to `$_basekernver`.
 
 *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
+	must either reside in the same directory as the PKGBUILD, or be a
-	fully-qualified URL that makepkg will use to download the file. In order
+	fully-qualified URL that makepkg can use to download the file.
-	to make the PKGBUILD as useful as possible, use the $pkgname and $pkgver
+	To make the PKGBUILD as useful as possible, use the $pkgname and $pkgver
-	variables if possible when specifying the download location. Any files
+	variables if possible when specifying the download location. Compressed files
-	that are compressed will automatically be extracted, unless found in
+	will be extracted automatically unless found in
-	the noextract array listed below.
+	the noextract array described below.
 +
-It is also possible to specify an optional filename, which is helpful
+It is also possible to overwrite the filename, which is helpful
 with weird URLs and for handling multiple source files with the same
 name. The syntax is: `source=('filename::url')`.
 
 *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
+	is useful for packages that use compressed data directly.
-	not necessary to uncompress.
 
 *md5sums (array)*::
 	This array contains an MD5 hash for every source file specified in the
@@ -135,16 +134,16 @@ name. The syntax is: `source=('filename::url')`.
 *arch (array)*::
 	Defines on which architectures the given package is available (e.g.
 	`arch=('i686' 'x86_64')`). Packages that contain no architecture specific
-	files may use arch=('any').
+	files should use arch=('any').
 
 *backup (array)*::
-	A space-delimited array of filenames, without preceding slashes, that
+	An 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 linkman:pacman[8] for more information.
 
 *depends (array)*::
-	An array of packages that this package depends on to run. Packages in
+	An array of packages this package depends on to run. Entries 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 five comparisons: >= (greater
@@ -152,12 +151,12 @@ name. The syntax is: `source=('filename::url')`.
 	than), or < (less than).
 
 *makedepends (array)*::
-	An array of packages that this package depends on to build, but are not
+	An array of packages this package depends on to build but are not
 	needed at runtime. Packages in this list follow the same format as
 	depends.
 
 *checkdepends (array)*::
-	An array of packages that this package depends on to run its test suite,
+	An array of packages this package depends on to run its test suite
 	but are not needed at runtime. Packages in this list follow the same
 	format as depends. These dependencies are only considered when the
 	check() function is present and is to be run by makepkg.
@@ -177,7 +176,7 @@ name. The syntax is: `source=('filename::url')`.
 	same format as depends. Versioned conflicts are also supported.
 
 *provides (array)*::
-	An array of ``virtual provisions'' that this package provides. This allows
+	An array of ``virtual provisions'' 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'.
@@ -188,7 +187,7 @@ name. The syntax is: `source=('filename::url')`.
 	provided.
 
 *replaces (array)*::
-	An array of packages that this package should replace, and can be used
+	An array of packages this package should replace. This 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
@@ -248,7 +247,7 @@ name. The syntax is: `source=('filename::url')`.
 
 build() Function
 ----------------
-In addition to the above directives, the optional build() bash function usually
+In addition to the above directives, the optional build() function usually
 comprises the remainder of the PKGBUILD. This is directly sourced and executed
 by makepkg, so anything that bash or the system has available is available for
 use here. The function is run in `bash -e` mode, meaning any command that exits
@@ -256,22 +255,22 @@ with a non-zero status will cause the function to exit. Be sure any exotic
 commands used are covered by `makedepends`.
 
 All of the above variables such as `pkgname` and `pkgver` are available for use
-in the build function. In addition, makepkg defines three variables for your
+in the build function. In addition, makepkg defines the following three
-use during the build and install process. These three variables are as follows:
+variables for use during the build and install process:
 
 *startdir*::
-	This contains the absolute path to the directory where the PKGBUILD was
+	This contains the absolute path to the directory where the PKGBUILD is
 	located, which is usually the output of `$(pwd)` when makepkg is started.
 
 *srcdir*::
-	This points to the directory where makepkg extracts or copies all source
+	This points to the directory where makepkg extracts to or copies to all source
 	files.
 
 *pkgdir*::
 	This points to the directory where makepkg bundles the installed package
 	(this directory will become the root directory of your built package).
 
-If you create any variables of your own in the build function, it is
+If you create any variables on your own in the build function, it is
 recommended to use the bash `local` keyword to scope the variable to inside
 the build function.
 
@@ -301,8 +300,8 @@ Each split package uses a corresponding packaging function with name
 `package_foo()`, where `foo` is the name of the split package.
 
 All options and directives for the split packages default to the global values
-given within the PKGBUILD. However, some of these can be overridden within each
+given in the PKGBUILD. Nevertheless, the following ones can be overridden within
-split package's packaging function. The following variables can be overridden:
+each split package's packaging function:
 `pkgver`, `pkgrel`, `pkgdesc`, `arch`, `license`, `groups`, `depends`,
 `optdepends`, `provides`, `conflicts`, `replaces`, `backup`, `options`,
 `install` and `changelog`.
@@ -363,7 +362,7 @@ makepkg supports building development versions of packages without having to
 manually update the pkgver in the PKGBUILD. This was formerly done using the
 separate utility 'versionpkg'. In order to utilize this functionality, your
 PKGBUILD must use correct variable names depending on the SCM being fetched
-from.
+from (e.g., "makepkg-git", "mplayer-svn").
 
 *CVS*::
 	The generated pkgver will be the date the package is built.