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, 371 insertions, 0 deletions

diff --git a/doc/pacman.conf.5.asciidoc b/doc/pacman.conf.5.asciidoc
new file mode 100644
index 00000000..e5fffecf
--- /dev/null
+++ b/doc/pacman.conf.5.asciidoc
@@ -0,0 +1,371 @@
+pacman.conf(5)
+==============
+
+Name
+----
+pacman.conf - pacman package manager configuration file
+
+
+Synopsis
+--------
+{sysconfdir}/pacman.conf
+
+
+Description
+-----------
+Pacman, using linkman: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
+
+[core]
+Include = /etc/pacman.d/core
+
+[custom]
+Server = file:///home/pkgs
+--------
+
+NOTE: Each directive must be in CamelCase. If the case isn't respected, the
+directive won't be recognized. For example. noupgrade or NOUPGRADE will not
+work.
+
+
+Options
+-------
+*RootDir =* /path/to/root/dir::
+	Set the default root directory for pacman to install to. This option is
+	used if you want to install a package on a temporary mounted partition
+	which is "owned" by another system, or for a chroot install.
+	*NOTE*: If database path or log file are not specified on either the
+	command line or in linkman:pacman.conf[5], their default location will
+	be inside this root path.
+
+*DBPath =* /path/to/db/dir::
+	Overrides the default location of the toplevel database directory. The
+	default is +{localstatedir}/lib/pacman/+. Most users will not need to set
+	this option. *NOTE*: if specified, this is an absolute path and the root
+	path is not automatically prepended.
+
+*CacheDir =* /path/to/cache/dir::
+	Overrides the default location of the package cache directory. The
+	default is +{localstatedir}/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. *NOTE*: this is an absolute
+	path, the root path is not automatically prepended.
+
+*HookDir =* /path/to/hook/dir::
+	Add directories to search for alpm hooks in addition to the system hook
+	directory (+{datarootdir}/libalpm/hooks/+).  The default is
+	+{sysconfdir}/pacman.d/hooks+.  Multiple directories can be specified with
+	hooks in later directories taking precedence over hooks in earlier
+	directories.  *NOTE*: this is an absolute path, the root path is not
+	automatically prepended.  For more information on the alpm hooks, see
+	linkman:alpm-hooks[5].
+
+*GPGDir =* /path/to/gpg/dir::
+	Overrides the default location of the directory containing configuration
+	files for GnuPG. The default is +{sysconfdir}/pacman.d/gnupg/+.
+	This directory should contain two files: `pubring.gpg` and `trustdb.gpg`.
+	`pubring.gpg` holds the public keys of all packagers. `trustdb.gpg`
+	contains a so-called trust database, which specifies that the keys are
+	authentic and trusted.
+	*NOTE*: this is an absolute path, the root path is not automatically
+	prepended.
+
+*LogFile =* /path/to/log/file::
+	Overrides the default location of the pacman log file. The default
+	is +{localstatedir}/log/pacman.log+. This is an absolute path and the root directory
+	is not prepended.
+
+*HoldPkg =* package ...::
+	If a user tries to '\--remove' a package that's listed in `HoldPkg`,
+	pacman will ask for confirmation before proceeding. Shell-style glob
+	patterns are allowed.
+
+*IgnorePkg =* package ...::
+	Instructs pacman to ignore any upgrades for this package when performing
+	a '\--sysupgrade'. Shell-style glob patterns are allowed.
+
+*IgnoreGroup =* group ...::
+	Instructs pacman to ignore any upgrades for all packages in this
+	group when performing a '\--sysupgrade'. Shell-style glob patterns are
+	allowed.
+
+*Include =* /path/to/config/file::
+	Include another configuration file. This file can include repositories or
+	general configuration options. Wildcards in the specified paths will get
+	expanded based on linkman:glob[7] rules.
+
+*Architecture =* auto | i686 | x86_64 | ...::
+	If set, pacman will only allow installation of packages of the given
+	architecture (e.g. 'i686', 'x86_64', etc). The special value 'auto' will
+	use the system architecture, provided via ``uname -m''. If unset, no
+	architecture checks are made. *NOTE*: Packages with the special
+	architecture 'any' can always be installed, as they are meant to be
+	architecture independent.
+
+*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.
+
+*NoUpgrade =* file ...::
+	All files listed with a `NoUpgrade` directive will never be touched during
+	a package install/upgrade, and the new files will be installed with a
+	'.pacnew' extension.
+	These files refer to files in the package archive, so do not include the
+	leading slash (the RootDir) when specifying them. Shell-style glob patterns
+	are allowed. It is possible to invert matches by prepending a file with
+	an exclamation mark. Inverted files will result in previously blacklisted
+	files being whitelisted again. Subsequent matches will override previous
+	ones. A leading literal exclamation mark or backslash needs to be escaped.
+
+*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.
+	These files refer to files in the package archive, so do not include the
+	leading slash (the RootDir) when specifying them. Shell-style glob patterns
+	are allowed. It is possible to invert matches by prepending a file with
+	an exclamation mark. Inverted files will result in previously blacklisted
+	files being whitelisted again. Subsequent matches will override previous
+	ones. A leading literal exclamation mark or backslash needs to be escaped.
+
+*CleanMethod =* KeepInstalled &| KeepCurrent::
+	If set to `KeepInstalled` (the default), the '-Sc' operation will clean
+	packages that are no longer installed (not present in the local database).
+	If set to `KeepCurrent`, '-Sc' will clean outdated packages (not present in
+	any sync database).
+	The second behavior is useful when the package cache is shared among
+	multiple machines, where the local databases are usually different, but the
+	sync databases in use could be the same. If both values are specified,
+	packages are only cleaned if not installed locally and not present in any
+	known sync database.
+
+*SigLevel =* ...::
+	Set the default signature verification level. For more information, see
+	<<SC,Package and Database Signature Checking>> below.
+
+*LocalFileSigLevel =* ...::
+	Set the signature verification level for installing packages using the "-U"
+	operation on a local file. Uses the value from SigLevel as the default.
+
+*RemoteFileSigLevel =* ...::
+	Set the signature verification level for installing  packages using the "-U"
+	operation on a remote file URL. Uses the value from SigLevel as the default.
+
+*UseSyslog*::
+	Log action messages through syslog(). This will insert log entries into
+	+{localstatedir}/log/messages+ or equivalent.
+
+*Color*::
+	Automatically enable colors only when pacman's output is on a tty.
+
+*UseDelta* [= ratio]::
+	Download delta files instead of complete packages if possible. Requires
+	the `xdelta3` program to be installed. If a ratio is specified (e.g.,
+	`0.5`), then it is used as a cutoff for determining whether to use deltas.
+	Allowed values are between `0.0` and `2.0`; sensible values are between
+	`0.2` and `0.9`.  Using a value above `1.0` is not recommended.  The
+	default is `0.7` if left unspecified.
+
+*TotalDownload*::
+	When downloading, display the amount downloaded, download rate, ETA,
+	and completed percentage of the entire download list rather
+	than the percent of each individual download target. The progress
+	bar is still based solely on the current file download.
+	This option won't work if XferCommand is used.
+
+*CheckSpace*::
+	Performs an approximate check for adequate available disk space before
+	installing packages.
+
+*VerbosePkgLists*::
+	Displays name, version and size of target packages formatted
+	as a table for upgrade, sync and remove operations.
+
+*DisableDownloadTimeout*::
+	Disable defaults for low speed limit and timeout on downloads. Use this
+	if you have issues downloading files with proxy and/or security gateway.
+
+
+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 'core'  and  'custom'). Repository names
+must be unique and the name 'local' is reserved for the database of installed
+packages. 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.
+
+A common way to define DB locations utilizes the 'Include' directive. For each
+repository defined in the configuration file, a single 'Include' directive can
+contain a file that lists the servers for that repository.
+
+--------
+[core]
+# use this server first
+Server = ftp://ftp.archlinux.org/$repo/os/$arch
+# next use servers as defined in the mirrorlist below
+Include = {sysconfdir}/pacman.d/mirrorlist
+--------
+
+The order of repositories in the configuration files 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.
+
+*Include =* path::
+	Include another config file. This file can include repositories or
+	general configuration options. Wildcards in the specified paths will get
+	expanded based on linkman:glob[7] rules.
+
+*Server =* url::
+	A full URL to a location where the database, packages, and signatures (if
+	available) for this repository can be found.
++
+During parsing, pacman will define the `$repo` variable to the name of the
+current section. This is often utilized in files specified using the 'Include'
+directive so all repositories can use the same mirrorfile. pacman also defines
+the `$arch` variable to the value of `Architecture`, so the same mirrorfile can
+even be used for different architectures.
+
+*SigLevel =* ...::
+	Set the signature verification level for this repository. For more
+	information, see <<SC,Package and Database Signature Checking>> below.
+
+*Usage =* ...::
+	Set the usage level for this repository. This option takes a list of tokens
+	which must be at least one of the following:
+		*Sync*;;
+			Enables refreshes for this repository.
+		*Search*;;
+			Enables searching for this repository.
+		*Install*;;
+			Enables installation of packages from this repository during a '\--sync'
+			operation.
+		*Upgrade*;;
+			Allows this repository to be a valid source of packages when performing
+			a '\--sysupgrade'.
+		*All*;;
+			Enables all of the above features for the repository. This is the default
+			if not specified.
++
+Note that an enabled repository can be operated on explicitly, regardless of the Usage
+level set.
+
+
+Package and Database Signature Checking[[SC]]
+---------------------------------------------
+The 'SigLevel' directive is valid in both the `[options]` and repository
+sections. If used in `[options]`, it sets a default value for any repository
+that does not provide the setting.
+
+* If set to *Never*, no signature checking will take place.
+* If set to *Optional* , signatures will be checked when present, but unsigned
+  databases and packages will also be accepted.
+* If set to *Required*, signatures will be required on all packages and
+  databases.
+
+Alternatively, you can get more fine-grained control by combining some of
+the options and prefixes described below. All options in a config file are
+processed in top-to-bottom, left-to-right fashion, where later options override
+and/or supplement earlier ones. If 'SigLevel' is specified in a repository
+section, the starting value is that from the `[options]` section, or the
+built-in system default as shown below if not specified.
+
+The options are split into two main groups, described below. Terms used such as
+``marginally trusted'' are terms used by GnuPG, for more information please
+consult linkman:gpg[1].
+
+When to Check::
+	These options control if and when signature checks should take place.
+
+	*Never*;;
+		All signature checking is suppressed, even if signatures are present.
+
+	*Optional* (default);;
+		Signatures are checked if present; absence of a signature is not an
+		error. An invalid signature is a fatal error, as is a signature from a
+		key not in the keyring.
+
+	*Required*;;
+		Signatures are required; absence of a signature or an invalid signature
+		is a fatal error, as is a signature from a key not in the keyring.
+
+What is Allowed::
+	These options control what signatures are viewed as permissible. Note that
+	neither of these options allows acceptance of invalid or expired
+	signatures, or those from revoked keys.
+
+	*TrustedOnly* (default);;
+		If a signature is checked, it must be in the keyring and fully trusted;
+		marginal trust does not meet this criteria.
+
+	*TrustAll*;;
+		If a signature is checked, it must be in the keyring, but is not
+		required to be assigned a trust level (e.g., unknown or marginal
+		trust).
+
+Options in both groups can additionally be prefixed with either *Package* or
+*Database*, which will cause it to only take effect on the specified object
+type. For example, `PackageTrustAll` would allow marginal and unknown trust
+level signatures for packages.
+
+The built-in default is the following:
+
+--------
+SigLevel = Optional TrustedOnly
+--------
+
+
+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.{ext}', where '\{treename\}' is the name of the section
+defined in the configuration file and '\{ext\}' is a valid compression type as
+documented in linkman:repo-add[8]. 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
+linkman:repo-add[8].
+
+
+See Also
+--------
+linkman:pacman[8], linkman:libalpm[3]
+
+include::footer.asciidoc[]