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

diff --git a/doc/pacman-key.8.asciidoc b/doc/pacman-key.8.asciidoc
new file mode 100644
index 00000000..f0b5ac08
--- /dev/null
+++ b/doc/pacman-key.8.asciidoc
@@ -0,0 +1,145 @@
+pacman-key(8)
+=============
+
+
+Name
+----
+pacman-key - manage pacman's list of trusted keys
+
+
+Synopsis
+--------
+'pacman-key' [options] operation [targets]
+
+
+Description
+-----------
+'pacman-key' is a wrapper script for GnuPG used to manage pacman's keyring, which
+is the collection of PGP keys used to check signed packages and databases. It
+provides the ability to import and export keys, fetch keys from keyservers and
+update the key trust database.
+
+More complex keyring management can be achieved using GnuPG directly combined with
+the '\--homedir' option pointing at the pacman keyring (located in
++{sysconfdir}/pacman.d/gnupg+ by default).
+
+Invoking pacman-key consists of supplying an operation with any potential
+options and targets to operate on. Depending on the operation, a 'target' may
+be a valid key identifier, filename, or directory.
+
+
+Operations
+----------
+*-a, \--add*::
+	Add the key(s) contained in the specified file or files to pacman's
+	keyring. If a key already exists, update it.
+
+*-d, \--delete*::
+	Remove the key(s) identified by the specified keyid(s) from pacman's
+	keyring.
+
+*-e, \--export*::
+	Export key(s) identified by the specified keyid(s) to 'stdout'. If no keyid
+	is specified, all keys will be exported.
+
+*\--edit-key*::
+	Present a menu for key management task on the specified keyid(s). Useful
+	for adjusting a keys trust level.
+
+*-f, \--finger*::
+	List a fingerprint for each specified keyid, or for all known keys if no
+	keyids are specified.
+
+*-h, \--help*::
+	Output syntax and command line options.
+
+*\--import*::
+	Imports keys from `pubring.gpg` into the public keyring from the specified
+	directories.
+
+*\--import-trustdb*::
+	Imports ownertrust values from `trustdb.gpg` into the shared trust database
+	from the specified directories.
+
+*\--init*::
+	Ensure the keyring is properly initialized and has the required access
+	permissions.
+
+*-l, \--list-keys*::
+	Lists all or specified keys from the public keyring.
+
+*\--list-sigs*::
+	Same as '\--list-keys', but the signatures are listed too.
+
+*\--lsign-key*::
+	Locally sign the given key. This is primarily used to root the web of trust
+	in the local private key generated by '\--init'.
+
+*\--nocolor*::
+	Disable colored output from pacman-key.
+
+*-r, \--recv-keys*::
+	Equivalent to '\--recv-keys' in GnuPG.
+
+*\--refresh-keys*::
+	Equivalent to '\--refresh-keys' in GnuPG.
+
+*\--populate*::
+	Reload the default keys from the (optionally provided) keyrings in
+	+{pkgdatadir}/keyrings+. For more information, see
+	<<PK,Providing a Keyring for Import>> below.
+
+*-u, \--updatedb*::
+	Equivalent to '\--check-trustdb' in GnuPG. This operation can be specified with
+	other operations.
+
+*-V, \--version*::
+	Displays the program version.
+
+*-v, \--verify*::
+	Verify the file(s) specified by the signature(s).
+
+
+Options
+-------
+*\--config* <file>::
+	Use an alternate configuration file instead of the +{sysconfdir}/pacman.conf+
+	default.
+
+*\--gpgdir* <dir>::
+	Set an alternate home directory for GnuPG. If unspecified, the value is
+	read from +{sysconfdir}/pacman.conf+.
+
+*\--keyserver* <keyserver>::
+	Use the specified keyserver if the operation requires one. This will take
+	precedence over any keyserver option specified in a `gpg.conf`
+	configuration file. Running '\--init' with this option will set the default
+	keyserver if one was not already configured.
+
+
+Providing a Keyring for Import[[PK]]
+------------------------------------
+A distribution or other repository provided may want to provide a set of
+PGP keys used in the signing of its packages and repository databases that can
+be readily imported into the pacman keyring. This is achieved by providing a
+PGP keyring file `foo.gpg` that contains the keys for the foo keyring in the
+directory +{pkgdatadir}/keyrings+.
+
+Optionally, the file `foo-trusted` can be provided containing a list of trusted
+key IDs for that keyring. This is a file in a format compatible with 'gpg
+\--export-ownertrust' output. This file will inform the user which keys a user
+needs to verify and sign to build a local web of trust, in addition to
+assigning provided owner trust values.
+
+Also optionally, the file `foo-revoked` can be provided containing a list of
+revoked key IDs for that keyring. Revoked is defined as "no longer valid for
+any signing", so should be used with prudence. A key being marked as revoked
+will be disabled in the keyring and no longer treated as valid, so this always
+takes priority over it's trusted state in any other keyring.
+
+
+See Also
+--------
+linkman:pacman[8], linkman:pacman.conf[5]
+
+include::footer.asciidoc[]