Ensure better text editor automatic filetype detection

Since we no longer use vim-specific modelines, use the .asciidoc file
extension which is, well, reserved for asciidoc formatted files. This
should presumably work everywhere without needing editor-specific
workarounds and configuration.

Also add a shebang to makepkg.conf to indicate it contains bash content.

Signed-off-by: Eli Schwartz <eschwartz@archlinux.org>
Signed-off-by: Allan McRae <allan@archlinux.org>

1 files changed, 0 insertions, 525 deletions

diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt
deleted file mode 100644
index 795dde45..00000000
--- a/doc/PKGBUILD.5.txt
+++ /dev/null
@@ -1,525 +0,0 @@
-PKGBUILD(5)
-===========
-
-Name
-----
-PKGBUILD - Arch Linux package build description file
-
-
-Synopsis
---------
-PKGBUILD
-
-
-Description
------------
-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}'
-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.
-
-
-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
-of them will be directly transferred to the built package. The mandatory
-fields for a minimally functional PKGBUILD are *pkgname*, *pkgver*, *pkgrel*
-and *arch*.
-
-If you need to create any custom variables for use in your build process, it is
-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)*::
-	Either the name of the package or an array of names for split packages.
-	Valid characters for members of this array are alphanumerics, and any of
-	the following characters: ```@ . _ + -`''. Additionally, names are not
-	allowed to start with hyphens or dots.
-
-*pkgver*::
-	The version of the software as released from the author (e.g., '2.7.1').
-	The variable is not allowed to contain colons, forward slashes, hyphens
-	or whitespace.
-+
-The `pkgver` variable can be automatically updated by providing a `pkgver()`
-function in the PKGBUILD that outputs the new package version.
-This is run after downloading and extracting the sources and running the
-`prepare()` function (if present), so it can use those files in determining the
-new `pkgver`.  This is most useful when used with sources from version control
-systems (see below).
-
-*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. This is typically set to '1' for each new upstream
-	software release and incremented for intermediate PKGBUILD updates. The
-	variable is not allowed to contain hyphens.
-
-*epoch*::
-	Used to force the package to be seen as newer than any previous versions
-	with a lower epoch, even if the version number would normally not trigger
-	such an upgrade. This value is required to be a positive integer; the
-	default value if left unspecified is '0'. This is useful when the version
-	numbering scheme of a package changes (or is alphanumeric), breaking normal
-	version comparison logic. See linkman:pacman[8] for more information on
-	version comparisons.
-
-*pkgdesc*::
-	This should be a brief description of the package and its functionality.
-	Try to keep the description to one line of text and to not use the package's
-	name.
-
-*url*::
-	This field contains a URL that is associated with the software being
-	packaged. This is typically the project's web site.
-
-*license (array)*::
-	This field specifies the license(s) that apply to the package.
-	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
-	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
-	multiple licenses are applicable, 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`).
-
-*changelog*::
-	Specifies a changelog file that is to be included in the package.
-	The changelog file should end in a single newline.
-	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., `changelog=$pkgname.changelog`).
-
-*source (array)*::
-	An array of source files required to build the package. Source files
-	must either reside in the same directory as the PKGBUILD, or be a
-	fully-qualified URL that makepkg can use to download the file.
-	To simplify the maintenance of PKGBUILDs, use the `$pkgname` and `$pkgver`
-	variables when specifying the download location, if possible.
-	Compressed files will be extracted automatically unless found in the
-	noextract array described below.
-+
-Additional architecture-specific sources can be added by appending an
-underscore and the architecture name e.g., 'source_x86_64=()'. There must be a
-corresponding integrity array with checksums, e.g. 'md5sums_x86_64=()'.
-+
-It is also possible to change the name of the downloaded file, which is helpful
-with weird URLs and for handling multiple source files with the same
-name. The syntax is: `source=('filename::url')`.
-+
-makepkg also supports building developmental versions of packages using sources
-downloaded from version control systems (VCS). For more information, see
-<<VCS,Using VCS Sources>> below.
-+
-Files in the source array with extensions `.sig`, `.sign` or, `.asc` are
-recognized by makepkg as PGP signatures and will be automatically used to verify
-the integrity of the corresponding source file.
-
-*validpgpkeys (array)*::
-	An array of PGP fingerprints. If this array is non-empty, makepkg will
-	only accept signatures from the keys listed here and will ignore the
-	trust values from the keyring. If the source file was signed with a
-	subkey, makepkg will still use the primary key for comparison.
-+
-Only full fingerprints are accepted. They must be uppercase and must not
-contain whitespace characters.
-
-*noextract (array)*::
-	An array of file names 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 that use compressed data directly.
-
-*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. If 'SKIP' is put in the array
-	in place of a normal hash, the integrity check for that source file will
-	be skipped. To easily generate md5sums, run ``makepkg -g >> PKGBUILD''.
-	If desired, move the md5sums line to an appropriate location.
-
-*sha1sums, sha256sums, sha384sums, sha512sums (arrays)*::
-	Alternative integrity checks that makepkg supports; these all behave
-	similar to the md5sums option described above. To enable use and generation
-	of these checksums, be sure to set up the `INTEGRITY_CHECK` option in
-	linkman:makepkg.conf[5].
-
-*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')`). Packages that contain no architecture specific
-	files should use `arch=('any')`. Valid characters for members of this array
-	are alphanumerics and ```_`''.
-
-*backup (array)*::
-	An array of file names, 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 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
-	than or equal to), `<=` (less than or equal to), `=` (equal to), `>`
-	(greater than), or `<` (less than).
-+
-If the dependency name appears to be a library (ends with .so), makepkg will
-try to find a binary that depends on the library in the built package and
-append the version needed by the binary. Appending the version yourself
-disables automatic detection.
-+
-Additional architecture-specific depends can be added by appending an
-underscore and the architecture name e.g., 'depends_x86_64=()'.
-
-*makedepends (array)*::
-	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.
-+
-Additional architecture-specific makedepends can be added by appending an
-underscore and the architecture name e.g., 'makedepends_x86_64=()'.
-
-*checkdepends (array)*::
-	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.
-+
-Additional architecture-specific checkdepends can be added by appending an
-underscore and the architecture name e.g., 'checkdepends_x86_64=()'.
-
-*optdepends (array)*::
-	An array of packages (and accompanying reasons) that are not essential for
-	base functionality, but may be necessary to make full use of the contents
-	of this package. optdepends are currently for informational purposes only
-	and are not utilized by pacman during dependency resolution. The format
-	for specifying optdepends is:
-
-	optdepends=('python: for library bindings')
-+
-Additional architecture-specific optdepends can be added by appending an
-underscore and the architecture name e.g., 'optdepends_x86_64=()'.
-
-*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. Versioned conflicts are supported using the
-	operators as described in `depends`.
-+
-Additional architecture-specific conflicts can be added by appending an
-underscore and the architecture name e.g., 'conflicts_x86_64=()'.
-
-*provides (array)*::
-	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'.
-+
-Versioned provisions are also possible, in the 'name=version' format. For
-example, dcron can provide 'cron=2.0' to satisfy the 'cron>=2.0' dependency of
-other packages. Provisions involving the `>` and `<` operators are invalid as
-only specific versions of a package may be provided.
-+
-If the provision name appears to be a library (ends with .so), makepkg will
-try to find the library in the built package and append the correct
-version. Appending the version yourself disables automatic detection.
-+
-Additional architecture-specific provides can be added by appending an
-underscore and the architecture name e.g., 'provides_x86_64=()'.
-
-*replaces (array)*::
-	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. Versioned replaces are
-	supported using the operators as described in `depends`.
-+
-Sysupgrade is currently the only pacman operation that utilizes this field.
-A normal sync or upgrade will not use its value.
-+
-Additional architecture-specific replaces can be added by appending an
-underscore and the architecture name e.g., 'replaces_x86_64=()'.
-
-*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 linkman:makepkg.conf[5].
-	*NOTE:* 'force' is a now-removed option in favor of the top level 'epoch'
-	variable.
-
-	*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 directories. If you wish to delete doc directories,
-		specify `!docs` in the array.
-
-	*libtool*;;
-		Leave libtool (.la) files in packages. Specify `!libtool` to
-		remove them.
-
-	*staticlibs*;;
-		Leave static library (.a) files in packages. Specify `!staticlibs` to
-		remove them (if they have a shared counterpart).
-
-	*emptydirs*;;
-		Leave empty directories in packages.
-
-	*zipman*;;
-		Compress man and info pages with gzip.
-
-	*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.
-
-	*buildflags*;;
-		Allow the use of user-specific buildflags (CPPFLAGS, CFLAGS, CXXFLAGS,
-		LDFLAGS) during build as specified in linkman:makepkg.conf[5]. More
-		useful in its negative form `!buildflags` with select packages that
-		have problems building with custom buildflags.
-
-	*makeflags*;;
-		Allow the use of user-specific makeflags during build as specified
-		in linkman: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).
-
-	*debug*;;
-		Add the user-specified debug flags (DEBUG_CFLAGS, DEBUG_CXXFLAGS) to
-		their counterpart buildflags as specified in linkman:makepkg.conf[5].
-		When used in combination with the `strip' option, a separate package
-		containing the debug symbols is created.
-
-
-Packaging Functions
--------------------
-In addition to the above directives, PKGBUILDs require a set of functions that
-provide instructions to build and install the package. As a minimum, the
-PKGBUILD must contain a `package()` function which installs all the package's
-files into the packaging directory, with optional `prepare()`, `build()`, and
-`check()` functions being used to create those files from source.
-
-*package() Function*::
-	The `package()` function is used to install files into the directory that
-	will become the root directory of the built package and is run after all
-	the optional functions listed below. The packaging stage is run using
-	fakeroot to ensure correct file permissions in the resulting package.
-	All other functions will be run as the user calling makepkg.
-
-*prepare() Function*::
-	An optional `prepare()` function can be specified in which operations to
-	prepare the sources for building, such as patching, are performed. This
-	function is run after the source extraction and before the `build()`
-	function. The `prepare()` function is skipped when source extraction
-	is skipped.
-
-*build() Function*::
-	The optional `build()` function is use to compile and/or adjust the source
-	files in preparation to be installed by the `package()` function. This is
-	directly sourced and executed by makepkg, so anything that Bash or the
-	system has available is available for use here. Be sure any exotic
-	commands used are covered by the `makedepends` array.
-+
-If you create any variables of your own in the `build()` function, it is
-recommended to use the Bash `local` keyword to scope the variable to inside
-the `build()` function.
-
-*check() Function*::
-	An optional `check()` function can be specified in which a package's
-	test-suite may be run. This function is run between the `build()` and
-	`package()` functions. Be sure any exotic commands used are covered by the
-	`checkdepends` array.
-
-All of the above variables such as `$pkgname` and `$pkgver` are available for
-use in the packaging functions. In addition, makepkg defines the following
-variables:
-
-*srcdir*::
-	This contains the directory where makepkg extracts, or copies, all source
-	files.
-+
-All of the packaging functions defined above are run starting inside `$srcdir`
-
-*pkgdir*::
-	This contains the directory where makepkg bundles the installed package.
-	This directory will become the root directory of your built package. This
-	variable should only be used in the `package()` function.
-
-*startdir*::
-	This contains the absolute path to the directory where the PKGBUILD is
-	located, which is usually the output of `$(pwd)` when makepkg is started.
-	Use of this variable is deprecated and strongly discouraged.
-
-
-Package Splitting
------------------
-makepkg supports building multiple packages from a single PKGBUILD. This is
-achieved by assigning an array of package names to the `pkgname` directive.
-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 in the PKGBUILD. Nevertheless, the following ones can be overridden within
-each split package's packaging function:
-`pkgdesc`, `arch`, `url`, `license`, `groups`, `depends`, `optdepends`,
-`provides`, `conflicts`, `replaces`, `backup`, `options`, `install`, and
-`changelog`.
-
-Note that makepkg does not consider split package `depends` when checking
-if dependencies are installed before package building and with `--syncdeps`.
-All packages required to make the package are required to be specified in
-the global `depends` and `makedepends` arrays.
-
-An optional global directive is available when building a split package:
-
-*pkgbase*::
-	The name used to refer to the group of packages in the output of makepkg
-	and in the naming of source-only tarballs. If not specified, the first
-	element in the `pkgname` array is used. Valid characters for this
-	variable are alphanumerics, and any of the following characters:
-	```@ . _ + -`''. Additionally, the variable is not allowed to start with
-	hyphens or dots.
-
-
-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 perform an opposite action upon removal.
-
-The exact time the script is run varies with each operation, and should be
-self-explanatory. Note that during an upgrade operation, none of the install
-or remove functions will be called.
-
-Scripts are passed either one or two ``full version strings'', where a full
-version string is either 'pkgver-pkgrel' or 'epoch:pkgver-pkgrel', if epoch is
-non-zero.
-
-*pre_install*::
-	Run right before files are extracted. One argument is passed:
-	new package full version string.
-
-*post_install*::
-	Run right after files are extracted. One argument is passed:
-	new package full version string.
-
-*pre_upgrade*::
-	Run right before files are extracted. Two arguments are passed in this
-	order: new package full version string, old package full version string.
-
-*post_upgrade*::
-	Run after files are extracted. Two arguments are passed in this order:
-	new package full version string, old package full version string.
-
-*pre_remove*::
-	Run right before files are removed. One argument is passed:
-	old package full version string.
-
-*post_remove*::
-	Run right after files are removed. One argument is passed:
-	old package full version string.
-
-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 '{pkgdatadir}' as 'proto.install' for
-reference with all of the available functions defined.
-
-
-Using VCS Sources[[VCS]]
-------------------------
-Building a developmental version of a package using sources from a version
-control system (VCS) is enabled by specifying the source in the form
-`source=('directory::url#fragment?query')`. Currently makepkg supports the
-Bazaar, Git, Subversion, and Mercurial version control systems. For other
-version control systems, manual cloning of upstream repositories must be done
-in the `prepare()` function.
-
-The source URL is divided into four components:
-
-*directory*::
-	(optional) Specifies an alternate directory name for makepkg to download
-	the VCS source into.
-
-*url*::
-	The URL to the VCS repository. This must include the VCS in the URL protocol
-	for makepkg to recognize this as a VCS source. If the protocol does not
-	include the VCS name, it can be added by prefixing the URL with `vcs+`. For
-	example, using a Git repository over HTTPS would have a source URL in the
-	form:
-	`git+https://...`.
-
-*fragment*::
-	(optional) Allows specifying a revision number or branch for makepkg to checkout
-	from the VCS. For example, to checkout a given revision, the source line would
-	have the format `source=(url#revision=123)`. The available fragments depends on
-	the VCS being used:
-
-	*bzr*;;
-		revision (see `'bzr help revisionspec'` for details)
-
-	*git*;;
-		branch, commit, tag
-
-	*hg*;;
-		branch, revision, tag
-
-	*svn*;;
-		revision
-
-*query*::
-	(optional) Allows specifying whether a VCS checkout should be checked for
-	PGP-signed revisions. The source line should have the format
-	`source=(url#fragment?signed)` or `source=(url?signed#fragment)`. Currently
-	only supported by Git.
-
-Example
--------
-The following is an example PKGBUILD for the 'patch' package. For more
-examples, look through the build files of your distribution's packages. For
-those using Arch Linux, consult the Arch Build System (ABS) tree.
-
-[source,sh]
--------------------------------
-include::PKGBUILD-example.txt[]
--------------------------------
-
-
-See Also
---------
-linkman:makepkg[8], linkman:pacman[8], linkman:makepkg.conf[5]
-
-include::footer.txt[]