g10: Remove skeleton options files.
[gnupg.git] / doc / gpg.texi
index 781a188..aa55cb8 100644 (file)
 @command{@gpgname} is the OpenPGP part of the GNU Privacy Guard (GnuPG). It
 is a tool to provide digital encryption and signing services using the
 OpenPGP standard. @command{@gpgname} features complete key management and
-all bells and whistles you can expect from a decent OpenPGP
+all the bells and whistles you would expect from a full OpenPGP
 implementation.
 
+There are two main versions of GnuPG: GnuPG 1.x and GnuPG 2.x.  GnuPG
+2.x supports modern encryption algorithms and thus should be preferred
+over GnuPG 1.x.  You only need to use GnuPG 1.x if your platform
+doesn't support GnuPG 2.x, or you need support for some features that
+GnuPG 2.x has deprecated, e.g., decrypting data created with PGP-2
+keys.
+
 @ifclear gpgtwohack
-Note that this version of GnuPG features all modern algorithms and
-should thus be preferred over older GnuPG versions.  If you are
-looking for version 1 of GnuPG, you may find that version installed
-under the name @command{gpg1}.
+If you are looking for version 1 of GnuPG, you may find that version
+installed under the name @command{gpg1}.
 @end ifclear
 @ifset gpgtwohack
-In contrast to the standalone command gpg from GnuPG 1.x, which
-might be better suited for server and embedded platforms, the 2.x
-version is commonly installed under the name @command{@gpgname} and
-targeted to the desktop as it requires several other modules to be
-installed.
+In contrast to the standalone command @command{gpg} from GnuPG 1.x,
+the 2.x version is commonly installed under the name
+@command{@gpgname}.
 @end ifset
 
 @manpause
@@ -106,16 +109,13 @@ Developer information:
 @section Commands
 
 Commands are not distinguished from options except for the fact that
-only one command is allowed.
+only one command is allowed.  Generally speaking, irrelevant options
+are silently ignored, and may not be checked for correctness.
 
-@command{@gpgname} may be run with no commands, in which case it will
+@command{@gpgname} may be run with no commands. In this case it will
 perform a reasonable action depending on the type of file it is given
 as input (an encrypted message is decrypted, a signature is verified,
-a file containing keys is listed).
-
-Please remember that option as well as command parsing stops as soon as
-a non-option is encountered, you can explicitly stop parsing by
-using the special option @option{--}.
+a file containing keys is listed, etc.).
 
 
 @menu
@@ -140,8 +140,9 @@ cannot abbreviate this command.
 @item --help
 @itemx -h
 @opindex help
-Print a usage message summarizing the most useful command line options.
-Note that you cannot abbreviate this command.
+Print a usage message summarizing the most useful command-line options.
+Note that you cannot arbitrarily abbreviate this command
+(though you can use its short form @option{-h}).
 
 @item --warranty
 @opindex warranty
@@ -166,22 +167,24 @@ abbreviate this command.
 @item --sign
 @itemx -s
 @opindex sign
-Make a signature. This command may be combined with @option{--encrypt}
-(for a signed and encrypted message), @option{--symmetric} (for a
-signed and symmetrically encrypted message), or @option{--encrypt} and
-@option{--symmetric} together (for a signed message that may be
-decrypted via a secret key or a passphrase).  The key to be used for
-signing is chosen by default or can be set with the
+Sign a message. This command may be combined with @option{--encrypt}
+(to sign and encrypt a message), @option{--symmetric} (to sign and
+symmetrically encrypt a message), or both @option{--encrypt} and
+@option{--symmetric} (to sign and encrypt a message that can be
+decrypted using a secret key or a passphrase).  The signing key is
+chosen by default or can be set explicitly using the
 @option{--local-user} and @option{--default-key} options.
 
-@item --clearsign
+@item --clear-sign
+@opindex clear-sign
+@itemx --clearsign
 @opindex clearsign
-Make a clear text signature.  The content in a clear text signature is
+Make a cleartext signature.  The content in a cleartext signature is
 readable without any special software. OpenPGP software is only needed
-to verify the signature.  Clear text signatures may modify end-of-line
+to verify the signature.  cleartext signatures may modify end-of-line
 whitespace for platform independence and are not intended to be
-reversible.  The key to be used for signing is chosen by default or
-can be set with the @option{--local-user} and @option{--default-key}
+reversible.  The signing key is chosen by default or can be set
+explicitly using the @option{--local-user} and @option{--default-key}
 options.
 
 
@@ -193,18 +196,18 @@ Make a detached signature.
 @item --encrypt
 @itemx -e
 @opindex encrypt
-Encrypt data. This option may be combined with @option{--sign} (for a
-signed and encrypted message), @option{--symmetric} (for a message that
-may be decrypted via a secret key or a passphrase), or @option{--sign}
-and @option{--symmetric} together (for a signed message that may be
-decrypted via a secret key or a passphrase).
+Encrypt data. This command may be combined with @option{--sign} (to
+sign and encrypt a message), @option{--symmetric} (to encrypt a
+message that can decrypted using a secret key or a passphrase), or
+@option{--sign} and @option{--symmetric} together (for a signed
+message that can be decrypted using a secret key or a passphrase).
 
 @item --symmetric
 @itemx -c
 @opindex symmetric
 Encrypt with a symmetric cipher using a passphrase. The default
 symmetric cipher used is @value{GPGSYMENCALGO}, but may be chosen with the
-@option{--cipher-algo} option. This option may be combined with
+@option{--cipher-algo} option. This command may be combined with
 @option{--sign} (for a signed and symmetrically encrypted message),
 @option{--encrypt} (for a message that may be decrypted via a secret key
 or a passphrase), or @option{--sign} and @option{--encrypt} together
@@ -223,35 +226,43 @@ is specified) and write it to STDOUT (or the file specified with
 @option{--output}). If the decrypted file is signed, the signature is also
 verified. This command differs from the default operation, as it never
 writes to the filename which is included in the file and it rejects
-files which don't begin with an encrypted message.
+files that don't begin with an encrypted message.
 
 @item --verify
 @opindex verify
 Assume that the first argument is a signed file and verify it without
 generating any output.  With no arguments, the signature packet is
-read from STDIN.  If only a one argument is given, it is expected to
-be a complete signature.
+read from STDIN.  If only one argument is given, the specified file is
+expected to include a complete signature.
 
-With more than 1 argument, the first should be a detached signature
-and the remaining files ake up the the signed data. To read the signed
-data from STDIN, use @samp{-} as the second filename.  For security
-reasons a detached signature cannot read the signed material from
-STDIN without denoting it in the above way.
+With more than one argument, the first argument should specify a file
+with a detached signature and the remaining files should contain the
+signed data. To read the signed data from STDIN, use @samp{-} as the
+second filename.  For security reasons, a detached signature will not
+read the signed material from STDIN if not explicitly specified.
 
 Note: If the option @option{--batch} is not used, @command{@gpgname}
-may assume that a single argument is a file with a detached signature
+may assume that a single argument is a file with a detached signature,
 and it will try to find a matching data file by stripping certain
 suffixes.  Using this historical feature to verify a detached
-signature is strongly discouraged; always specify the data file too.
+signature is strongly discouraged; you should always specify the data file
+explicitly.
 
-Note: When verifying a cleartext signature, @command{gpg} verifies
+Note: When verifying a cleartext signature, @command{@gpgname} verifies
 only what makes up the cleartext signed data and not any extra data
-outside of the cleartext signature or header lines following directly
+outside of the cleartext signature or the header lines directly following
 the dash marker line.  The option @code{--output} may be used to write
-out the actual signed data; but there are other pitfalls with this
+out the actual signed data, but there are other pitfalls with this
 format as well.  It is suggested to avoid cleartext signatures in
 favor of detached signatures.
 
+Note: Sometimes the use of the @command{gpgv} tool is easier than
+using the full-fledged @command{gpg} with this option.  @command{gpgv}
+is designed to compare signed data against a list of trusted keys and
+returns with success only for a good signature.  It has its own manual
+page.
+
+
 @item --multifile
 @opindex multifile
 This modifies certain other commands to accept multiple files for
@@ -277,23 +288,30 @@ Identical to @option{--multifile --decrypt}.
 @itemx -k
 @itemx --list-public-keys
 @opindex list-keys
-List all keys from the public keyrings, or just the keys given on the
-command line.
+List the specified keys.  If no keys are specified, then all keys from
+the configured public keyrings are listed.
 
-Avoid using the output of this command in scripts or other programs as
-it is likely to change as GnuPG changes. See @option{--with-colons} for a
-machine-parseable key listing command that is appropriate for use in
-scripts and other programs.
+Never use the output of this command in scripts or other programs.
+The output is intended only for humans and its format is likely to
+change.  The @option{--with-colons} option emits the output in a
+stable, machine-parseable format, which is intended for use by scripts
+and other programs.
 
 @item --list-secret-keys
 @itemx -K
 @opindex list-secret-keys
-List all keys from the secret keyrings, or just the ones given on the
-command line. A @code{#} after the letters @code{sec} means that the
-secret key is not usable (for example, if it was created via
-@option{--export-secret-subkeys}).
-
-@item --list-sigs
+List the specified secret keys.  If no keys are specified, then all
+known secret keys are listed.  A @code{#} after the intial tags
+@code{sec} or @code{ssb} means that the secret key or subkey is
+currently not usable.  We also say that this key has been taken
+offline (for example, a primary key can be taken offline by exported
+the key using the command @option{--export-secret-subkeys}).  A
+@code{>} after these tags indicate that the key is stored on a
+smartcard.  See also @option{--list-keys}.
+
+@item --list-signatures
+@opindex list-signatures
+@itemx --list-sigs
 @opindex list-sigs
 Same as @option{--list-keys}, but the signatures are listed too.
 This command has the same effect as
@@ -312,9 +330,11 @@ notation (see @option{--cert-notation}), "X" for an eXpired signature
 above to indicate trust signature levels (see the @option{--edit-key}
 command "tsign").
 
-@item --check-sigs
+@item --check-signatures
+@opindex check-signatures
+@itemx --check-sigs
 @opindex check-sigs
-Same as @option{--list-sigs}, but the signatures are verified.  Note
+Same as @option{--list-signatures}, but the signatures are verified.  Note
 that for performance reasons the revocation status of a signing key is
 not shown.
 This command has the same effect as
@@ -322,7 +342,7 @@ using @option{--list-keys} with @option{--with-sig-check}.
 
 The status of the verification is indicated by a flag directly following
 the "sig" tag (and thus before the flags described above for
-@option{--list-sigs}).  A "!" indicates that the signature has been
+@option{--list-signatures}).  A "!" indicates that the signature has been
 successfully verified, a "-" denotes a bad signature and a "%" is used
 if an error occurred while checking the signature (e.g. a non supported
 algorithm).
@@ -340,18 +360,22 @@ be used to locate a key.  Only public keys are listed.
 List all keys (or the specified ones) along with their
 fingerprints. This is the same output as @option{--list-keys} but with
 the additional output of a line with the fingerprint. May also be
-combined with @option{--list-sigs} or @option{--check-sigs}.  If this
+combined with @option{--list-signatures} or @option{--check-signatures}.  If this
 command is given twice, the fingerprints of all secondary keys are
-listed too.
+listed too.  This command also forces pretty printing of fingerprints
+if the keyid format has been set to "none".
 
 @item --list-packets
 @opindex list-packets
-List only the sequence of packets. This is mainly useful for
+List only the sequence of packets.  This command is only useful for
 debugging.  When used with option @option{--verbose} the actual MPI
-values are dumped and not only their lengths.
+values are dumped and not only their lengths.  Note that the output of
+this command may change with new releases.
 
 
-@item --card-edit
+@item --edit-card
+@opindex edit-card
+@itemx --card-edit
 @opindex card-edit
 Present a menu to work with a smartcard. The subcommand "help" provides
 an overview on available commands. For a detailed description, please
@@ -366,7 +390,7 @@ Show the content of the smart card.
 @opindex change-pin
 Present a menu to allow changing the PIN of a smartcard. This
 functionality is also available as the subcommand "passwd" with the
-@option{--card-edit} command.
+@option{--edit-card} command.
 
 @item --delete-keys @code{name}
 @itemx --delete-keys @code{name}
@@ -376,13 +400,20 @@ safeguard against accidental deletion of multiple keys.
 
 @item --delete-secret-keys @code{name}
 @opindex delete-secret-keys
-Remove key from the secret keyring. In batch mode the key
-must be specified by fingerprint.
+Remove key from the secret keyring. In batch mode the key must be
+specified by fingerprint.  The option @option{--yes} can be used to
+advice gpg-agent not to request a confirmation.  This extra
+pre-caution is done because @command{@gpgname} can't be sure that the
+secret key (as controlled by gpg-agent) is only used for the given
+OpenPGP public key.
+
 
 @item --delete-secret-and-public-key @code{name}
 @opindex delete-secret-and-public-key
 Same as @option{--delete-key}, but if a secret key exists, it will be
 removed first. In batch mode the key must be specified by fingerprint.
+The option @option{--yes} can be used to advice gpg-agent not to
+request a confirmation.
 
 @item --export
 @opindex export
@@ -398,7 +429,7 @@ Similar to @option{--export} but sends the keys to a keyserver.
 Fingerprints may be used instead of key IDs. Option @option{--keyserver}
 must be used to give the name of this keyserver. Don't send your
 complete keyring to a keyserver --- select only those keys which are new
-or changed by you.  If no key IDs are given, @command{gpg} does nothing.
+or changed by you.  If no key IDs are given, @command{@gpgname} does nothing.
 
 @item --export-secret-keys
 @itemx --export-secret-subkeys
@@ -407,21 +438,20 @@ or changed by you.  If no key IDs are given, @command{gpg} does nothing.
 Same as @option{--export}, but exports the secret keys instead.  The
 exported keys are written to STDOUT or to the file given with option
 @option{--output}.  This command is often used along with the option
-@option{--armor} to allow easy printing of the key for paper backup;
-however the external tool @command{paperkey} does a better job for
+@option{--armor} to allow for easy printing of the key for paper backup;
+however the external tool @command{paperkey} does a better job of
 creating backups on paper.  Note that exporting a secret key can be a
-security risk if the exported keys are send over an insecure channel.
+security risk if the exported keys are sent over an insecure channel.
 
 The second form of the command has the special property to render the
 secret part of the primary key useless; this is a GNU extension to
 OpenPGP and other implementations can not be expected to successfully
-import such a key.  Its intended use is to generated a full key with
-an additional signing subkey on a dedicated machine and then using
-this command to export the key without the primary key to the main
-machine.
+import such a key.  Its intended use is in generating a full key with
+an additional signing subkey on a dedicated machine.  This command
+then exports the key without the primary key to the main machine.
 
 GnuPG may ask you to enter the passphrase for the key.  This is
-required because the internal protection method of the secret key is
+required, because the internal protection method of the secret key is
 different from the one specified by the OpenPGP protocol.
 
 @item --export-ssh-key
@@ -448,7 +478,9 @@ Most notable here is the @option{--import-options merge-only} option
 which does not insert new keys but does only the merging of new
 signatures, user-IDs and subkeys.
 
-@item --recv-keys @code{key IDs}
+@item --receive-keys @code{key IDs}
+@opindex receive-keys
+@itemx --recv-keys @code{key IDs}
 @opindex recv-keys
 Import the keys with the given key IDs from a keyserver. Option
 @option{--keyserver} must be used to give the name of this keyserver.
@@ -476,7 +508,8 @@ only LDAP supports them all.
 @opindex fetch-keys
 Retrieve keys located at the specified URIs. Note that different
 installations of GnuPG may support different protocols (HTTP, FTP,
-LDAP, etc.)
+LDAP, etc.).  When using HTTPS the system provided root certificates
+are used by this command.
 
 @item --update-trustdb
 @opindex update-trustdb
@@ -522,7 +555,7 @@ corrupted trustdb.  Example:
 Update the trustdb with the ownertrust values stored in @code{files} (or
 STDIN if not given); existing values will be overwritten.  In case of a
 severely damaged trustdb and if you have a recent backup of the
-ownertrust values (e.g. in the file @file{otrust.txt}, you may re-create
+ownertrust values (e.g. in the file @file{otrust.txt}), you may re-create
 the trustdb using these commands:
 @c man:.RS
 @example
@@ -560,14 +593,14 @@ Use the source, Luke :-). The output format is still subject to change.
 
 
 @item --enarmor
-@item --dearmor
+@itemx --dearmor
 @opindex enarmor
 @opindex dearmor
 Pack or unpack an arbitrary input into/from an OpenPGP ASCII armor.
 This is a GnuPG extension to OpenPGP and in general not very useful.
 
-@item --tofu-set-policy @code{auto|good|unknown|bad|ask}  @code{key...}
-@opindex tofu-set-policy
+@item --tofu-policy @code{auto|good|unknown|bad|ask}  @code{key...}
+@opindex tofu-policy
 Set the TOFU policy for all the bindings associated with the specified
 keys.  For more information about the meaning of the policies,
 @pxref{trust-model-tofu}.  The keys may be specified either by their
@@ -587,23 +620,41 @@ fingerprint (preferred) or their keyid.
 @node OpenPGP Key Management
 @subsection How to manage your keys
 
-This section explains the main commands for key management
+This section explains the main commands for key management.
 
 @table @gnupgtabopt
 
-@item --quick-gen-key @code{user-id}
-@opindex quick-gen-key
+@item --quick-generate-key @code{user-id} [@code{algo} [@code{usage} [@code{expire}]]]
+@opindex quick-generate-key
 This is a simple command to generate a standard key with one user id.
-In contrast to @option{--gen-key} the key is generated directly
+In contrast to @option{--generate-key} the key is generated directly
 without the need to answer a bunch of prompts.  Unless the option
 @option{--yes} is given, the key creation will be canceled if the
-given user id already exists in the key ring.
+given user id already exists in the keyring.
 
 If invoked directly on the console without any special options an
 answer to a ``Continue?'' style confirmation prompt is required.  In
-case the user id already exists in the key ring a second prompt to
+case the user id already exists in the keyring a second prompt to
 force the creation of the key will show up.
 
+If @code{algo} or @code{usage} are given, only the primary key is
+created and no prompts are shown.  To specify an expiration date but
+still create a primary and subkey use ``default'' or
+``future-default'' for @code{algo} and ``default'' for @code{usage}.
+For a description of these optional arguments see the command
+@code{--quick-add-key}.  The @code{usage} accepts also the value
+``cert'' which can be used to create a certification only primary key;
+the default is to a create certification and signing key.
+
+The @code{expire} argument can be used to specify an expiration date
+for the key.  Several formats are supported; commonly the ISO formats
+``YYYY-MM-DD'' or ``YYYYMMDDThhmmss'' are used.  To make the key
+expire in N seconds, N days, N weeks, N months, or N years use
+``seconds=N'', ``Nd'', ``Nw'', ``Nm'', or ``Ny'' respectively.  Not
+specifying a value, or using ``-'' results in a key expiring in a
+reasonable default interval.  The values ``never'', ``none'' can be
+used for no expiration date.
+
 If this command is used with @option{--batch},
 @option{--pinentry-mode} has been set to @code{loopback}, and one of
 the passphrase options (@option{--passphrase},
@@ -612,23 +663,72 @@ supplied passphrase is used for the new key and the agent does not ask
 for it.  To create a key without any protection @code{--passphrase ''}
 may be used.
 
-@item --gen-key
+@item --quick-set-expire @code{fpr} @code{expire}
+@opindex quick-set-expire
+Directly set the expiration time of the primary key to @code{expire}.
+To remove the expiration time @code{0} can be used.
+
+
+@item --quick-add-key @code{fpr} [@code{algo} [@code{usage} [@code{expire}]]]
+@opindex quick-add-key
+Directly add a subkey to the key identified by the fingerprint
+@code{fpr}.  Without the optional arguments an encryption subkey is
+added.  If any of the arguments are given a more specific subkey is
+added.
+
+@code{algo} may be any of the supported algorithms or curve names
+given in the format as used by key listings.  To use the default
+algorithm the string ``default'' or ``-'' can be used.  Supported
+algorithms are ``rsa'', ``dsa'', ``elg'', ``ed25519'', ``cv25519'',
+and other ECC curves.  For example the string ``rsa'' adds an RSA key
+with the default key length; a string ``rsa4096'' requests that the
+key length is 4096 bits.  The string ``future-default'' is an alias
+for the algorithm which will likely be used as default algorithm in
+future versions of gpg.
+
+Depending on the given @code{algo} the subkey may either be an
+encryption subkey or a signing subkey.  If an algorithm is capable of
+signing and encryption and such a subkey is desired, a @code{usage}
+string must be given.  This string is either ``default'' or ``-'' to
+keep the default or a comma delimited list (or space delimited list)
+of keywords: ``sign'' for a signing subkey, ``auth'' for an
+authentication subkey, and ``encr'' for an encryption subkey
+(``encrypt'' can be used as alias for ``encr'').  The valid
+combinations depend on the algorithm.
+
+The @code{expire} argument can be used to specify an expiration date
+for the key.  Several formats are supported; commonly the ISO formats
+``YYYY-MM-DD'' or ``YYYYMMDDThhmmss'' are used.  To make the key
+expire in N seconds, N days, N weeks, N months, or N years use
+``seconds=N'', ``Nd'', ``Nw'', ``Nm'', or ``Ny'' respectively.  Not
+specifying a value, or using ``-'' results in a key expiring in a
+reasonable default interval.  The values ``never'', ``none'' can be
+used for no expiration date.
+
+@item --generate-key
+@opindex generate-key
+@itemx --gen-key
 @opindex gen-key
 Generate a new key pair using the current default parameters.  This is
 the standard command to create a new key.  In addition to the key a
 revocation certificate is created and stored in the
 @file{openpgp-revocs.d} directory below the GnuPG home directory.
 
-@item --full-gen-key
-@opindex gen-key
+@item --full-generate-key
+@opindex full-generate-key
+@itemx --full-gen-key
+@opindex full-gen-key
 Generate a new key pair with dialogs for all options.  This is an
-extended version of @option{--gen-key}.
+extended version of @option{--generate-key}.
 
 There is also a feature which allows you to create keys in batch
 mode. See the manual section ``Unattended key generation'' on how
 to use this.
 
-@item --gen-revoke @code{name}
+
+@item --generate-revocation @code{name}
+@opindex generate-revocation
+@itemx --gen-revoke @code{name}
 @opindex gen-revoke
 Generate a revocation certificate for the complete key.  To only revoke
 a subkey or a key signature, use the @option{--edit} command.
@@ -643,7 +743,9 @@ published, which is best done by sending the key to a keyserver
 to a file which is then send to frequent communication partners.
 
 
-@item --desig-revoke @code{name}
+@item --generate-designated-revocation @code{name}
+@opindex generate-designated-revocation
+@itemx --desig-revoke @code{name}
 @opindex desig-revoke
 Generate a designated revocation certificate for a key. This allows a
 user (with the permission of the keyholder) to revoke someone else's
@@ -671,12 +773,12 @@ line.
 
   @item sign
   @opindex keyedit:sign
-  Make a signature on key of user @code{name} If the key is not yet
-  signed by the default user (or the users given with -u), the program
+  Make a signature on key of user @code{name}. If the key is not yet
+  signed by the default user (or the users given with @option{-u}), the program
   displays the information of the key again, together with its
   fingerprint and asks whether it should be signed. This question is
   repeated for all users specified with
-  -u.
+  @option{-u}.
 
   @item lsign
   @opindex keyedit:lsign
@@ -847,7 +949,8 @@ signing.
   @opindex keyedit:delkey
   Remove a subkey (secondary key). Note that it is not possible to retract
   a subkey, once it has been send to the public (i.e. to a keyserver).  In
-  that case you better use @code{revkey}.
+  that case you better use @code{revkey}.  Also note that this only
+  deletes the public part of a key.
 
   @item revkey
   @opindex keyedit:revkey
@@ -905,17 +1008,17 @@ signing.
   currently have them. Cross-certification signatures protect against a
   subtle attack against signing subkeys. See
   @option{--require-cross-certification}.  All new keys generated have
-  this signature by default, so this option is only useful to bring
+  this signature by default, so this command is only useful to bring
   older keys up to date.
 
   @item save
   @opindex keyedit:save
-  Save all changes to the key rings and quit.
+  Save all changes to the keyrings and quit.
 
   @item quit
   @opindex keyedit:quit
   Quit the program without updating the
-  key rings.
+  keyrings.
 @end table
 
 @c man:.RS
@@ -986,18 +1089,38 @@ full flexibility of the "sign" subcommand from @option{--edit-key}.
 Its intended use is to help unattended key signing by utilizing a list
 of verified fingerprints.
 
-@item --quick-adduid  @var{user-id} @var{new-user-id}
-@opindex quick-adduid
+@item --quick-add-uid  @var{user-id} @var{new-user-id}
+@opindex quick-add-uid
 This command adds a new user id to an existing key.  In contrast to
 the interactive sub-command @code{adduid} of @option{--edit-key} the
 @var{new-user-id} is added verbatim with only leading and trailing
 white space removed, it is expected to be UTF-8 encoded, and no checks
 on its form are applied.
 
-@item --passwd @var{user_id}
+@item --quick-revoke-uid  @var{user-id} @var{user-id-to-revoke}
+@opindex quick-revoke-uid
+This command revokes a user ID on an existing key.  It cannot be used
+to revoke the last user ID on key (some non-revoked user ID must
+remain), with revocation reason ``User ID is no longer valid''.  If
+you want to specify a different revocation reason, or to supply
+supplementary revocation text, you should use the interactive
+sub-command @code{revuid} of @option{--edit-key}.
+
+@item --quick-set-primary-uid  @var{user-id} @var{primary-user-id}
+@opindex quick-set-primary-uid
+This command sets or updates the primary user ID flag on an existing
+key.  @var{user-id} specifies the key and @var{primary-user-id} the
+user ID which shall be flagged as the primary user ID.  The primary
+user ID flag is removed from all other user ids and the timestamp of
+all affected self-signatures is set one second ahead.
+
+
+@item --change-passphrase @var{user-id}
+@opindex change-passphrase
+@itemx --passwd @var{user-id}
 @opindex passwd
 Change the passphrase of the secret key belonging to the certificate
-specified as @var{user_id}.  This is a shortcut for the sub-command
+specified as @var{user-id}.  This is a shortcut for the sub-command
 @code{passwd} of the edit key menu.
 
 @end table
@@ -1021,7 +1144,7 @@ behaviour and to change the default configuration.
 * GPG Input and Output::        Input and Output.
 * OpenPGP Options::             OpenPGP protocol specific options.
 * Compliance Options::          Compliance options.
-* GPG Esoteric Options::        Doing things one usually don't want to do.
+* GPG Esoteric Options::        Doing things one usually doesn't want to do.
 * Deprecated Options::          Deprecated options.
 @end menu
 
@@ -1098,7 +1221,11 @@ filename given on the command line, gpg might still need to read from
 STDIN (in particular if gpg figures that the input is a
 detached signature and no data file has been specified).  Thus if you
 do not want to feed data via STDIN, you should connect STDIN to
-@file{/dev/null}.
+g@file{/dev/null}.
+
+It is highly recommended to use this option along with the options
+@option{--status-fd} and @option{--with-colons} for any unattended of
+@command{gpg}.
 
 @item --no-tty
 @opindex no-tty
@@ -1119,7 +1246,7 @@ Assume "no" on most questions.
 @opindex list-options
 This is a space or comma delimited string that gives options used when
 listing keys and signatures (that is, @option{--list-keys},
-@option{--list-sigs}, @option{--list-public-keys},
+@option{--list-signatures}, @option{--list-public-keys},
 @option{--list-secret-keys}, and the @option{--edit-key} functions).
 Options can be prepended with a @option{no-} (after the two dashes) to
 give the opposite meaning.  The options are:
@@ -1128,7 +1255,7 @@ give the opposite meaning.  The options are:
 
   @item show-photos
   @opindex list-options:show-photos
-  Causes @option{--list-keys}, @option{--list-sigs},
+  Causes @option{--list-keys}, @option{--list-signatures},
   @option{--list-public-keys}, and @option{--list-secret-keys} to
   display any photo IDs attached to the key.  Defaults to no. See also
   @option{--photo-viewer}.  Does not work with @option{--with-colons}:
@@ -1144,7 +1271,7 @@ give the opposite meaning.  The options are:
 
   @item show-policy-urls
   @opindex list-options:show-policy-urls
-  Show policy URLs in the @option{--list-sigs} or @option{--check-sigs}
+  Show policy URLs in the @option{--list-signatures} or @option{--check-signatures}
   listings.  Defaults to no.
 
   @item show-notations
@@ -1154,12 +1281,12 @@ give the opposite meaning.  The options are:
   @opindex list-options:show-std-notations
   @opindex list-options:show-user-notations
   Show all, IETF standard, or user-defined signature notations in the
-  @option{--list-sigs} or @option{--check-sigs} listings. Defaults to no.
+  @option{--list-signatures} or @option{--check-signatures} listings. Defaults to no.
 
   @item show-keyserver-urls
   @opindex list-options:show-keyserver-urls
-  Show any preferred keyserver URL in the @option{--list-sigs} or
-  @option{--check-sigs} listings. Defaults to no.
+  Show any preferred keyserver URL in the @option{--list-signatures} or
+  @option{--check-signatures} listings. Defaults to no.
 
   @item show-uid-validity
   @opindex list-options:show-uid-validity
@@ -1181,8 +1308,8 @@ give the opposite meaning.  The options are:
 
   @item show-sig-expire
   @opindex list-options:show-sig-expire
-  Show signature expiration dates (if any) during @option{--list-sigs} or
-  @option{--check-sigs} listings. Defaults to no.
+  Show signature expiration dates (if any) during @option{--list-signatures} or
+  @option{--check-signatures} listings. Defaults to no.
 
   @item show-sig-subpackets
   @opindex list-options:show-sig-subpackets
@@ -1190,7 +1317,7 @@ give the opposite meaning.  The options are:
   optional argument list of the subpackets to list. If no argument is
   passed, list all subpackets. Defaults to no. This option is only
   meaningful when using @option{--with-colons} along with
-  @option{--list-sigs} or @option{--check-sigs}.
+  @option{--list-signatures} or @option{--check-signatures}.
 
 @end table
 
@@ -1246,8 +1373,8 @@ the opposite meaning. The options are:
   Enable PKA lookups to verify sender addresses. Note that PKA is based
   on DNS, and so enabling this option may disclose information on when
   and what signatures are verified or to whom data is encrypted. This
-  is similar to the "web bug" described for the auto-key-retrieve
-  feature.
+  is similar to the "web bug" described for the @option{--auto-key-retrieve}
+  option.
 
   @item pka-trust-increase
   @opindex verify-options:pka-trust-increase
@@ -1259,7 +1386,7 @@ the opposite meaning. The options are:
 @itemx --disable-large-rsa
 @opindex enable-large-rsa
 @opindex disable-large-rsa
-With --gen-key and --batch, enable the creation of RSA secret keys as
+With --generate-key and --batch, enable the creation of RSA secret keys as
 large as 8192 bit.  Note: 8192 bit is more than is generally
 recommended.  These large keys don't significantly improve security,
 but they are more expensive to use, and their signatures and
@@ -1295,9 +1422,10 @@ executing it from GnuPG does not make it secure.
 
 @item --exec-path @code{string}
 @opindex exec-path
+@efindex PATH
 Sets a list of directories to search for photo viewers and keyserver
 helpers. If not provided, keyserver helpers use the compiled-in
-default directory, and photo viewers use the $PATH environment
+default directory, and photo viewers use the @code{PATH} environment
 variable.
 Note, that on W32 system this value is ignored when searching for
 keyserver helpers.
@@ -1314,6 +1442,10 @@ Note that this adds a keyring to the current list. If the intent is to
 use the specified keyring alone, use @option{--keyring} along with
 @option{--no-default-keyring}.
 
+If the option @option{--no-keyring} has been used no keyrings will
+be used at all.
+
+
 @item --secret-keyring @code{file}
 @opindex secret-keyring
 This is an obsolete option and ignored.  All secret keys are stored in
@@ -1363,7 +1495,7 @@ Valid values for @code{name} are:
 
   @item koi8-r
   @opindex display-charset:koi8-r
-  The usual Russian set (rfc1489).
+  The usual Russian set (RFC-1489).
 
   @item utf-8
   @opindex display-charset:utf-8
@@ -1374,7 +1506,7 @@ Valid values for @code{name} are:
 @item --utf8-strings
 @itemx --no-utf8-strings
 @opindex utf8-strings
-Assume that command line arguments are given as UTF8 strings. The
+Assume that command line arguments are given as UTF-8 strings. The
 default (@option{--no-utf8-strings}) is to assume that arguments are
 encoded in the character set as specified by
 @option{--display-charset}. These options affect all following
@@ -1488,17 +1620,17 @@ Set what trust model GnuPG should follow. The models are:
 @table @asis
 
   @item pgp
-  @opindex trust-mode:pgp
+  @opindex trust-model:pgp
   This is the Web of Trust combined with trust signatures as used in PGP
   5.x and later. This is the default trust model when creating a new
   trust database.
 
   @item classic
-  @opindex trust-mode:classic
+  @opindex trust-model:classic
   This is the standard Web of Trust as introduced by PGP 2.
 
   @item tofu
-  @opindex trust-mode:tofu
+  @opindex trust-model:tofu
   @anchor{trust-model-tofu}
   TOFU stands for Trust On First Use.  In this trust model, the first
   time a key is seen, it is memorized.  If later another key is seen
@@ -1528,7 +1660,7 @@ Set what trust model GnuPG should follow. The models are:
   keys and email addresses (which are extracted from user ids and
   normalized).  There are five policies, which can be set manually
   using the @option{--tofu-policy} option.  The default policy can be
-  set using the @option{--tofu-default-policy} policy.
+  set using the @option{--tofu-default-policy} option.
 
   The TOFU policies are: @code{auto}, @code{good}, @code{unknown},
   @code{bad} and @code{ask}.  The @code{auto} policy is used by
@@ -1544,7 +1676,7 @@ Set what trust model GnuPG should follow. The models are:
   @code{undefined} trust level is returned.
 
   @item tofu+pgp
-  @opindex trust-mode:tofu+pgp
+  @opindex trust-model:tofu+pgp
   This trust model combines TOFU with the Web of Trust.  This is done
   by computing the trust level for each model and then taking the
   maximum trust level where the trust levels are ordered as follows:
@@ -1557,12 +1689,16 @@ Set what trust model GnuPG should follow. The models are:
   which some security-conscious users don't like.
 
   @item direct
-  @opindex trust-mode:direct
+  @opindex trust-model:direct
   Key validity is set directly by the user and not calculated via the
-  Web of Trust.
+  Web of Trust.  This model is soley based on the key and does
+  not distinguish user IDs.  Note that when changing to another trust
+  model the trust values assigned to a key are transformed into
+  ownertrust values, which also indicate how you trust the owner of
+  the key to sign other keys.
 
   @item always
-  @opindex trust-mode:always
+  @opindex trust-model:always
   Skip key validation and assume that used keys are always fully
   valid. You generally won't use this unless you are using some
   external validation scheme. This option also suppresses the
@@ -1572,7 +1708,7 @@ Set what trust model GnuPG should follow. The models are:
   disabled keys.
 
   @item auto
-  @opindex trust-mode:auto
+  @opindex trust-model:auto
   Select the trust model depending on whatever the internal trust
   database says. This is the default model if such a database already
   exists.
@@ -1590,7 +1726,7 @@ mechanisms, in the order they are to be tried:
 @table @asis
 
   @item cert
-  Locate a key using DNS CERT, as specified in rfc4398.
+  Locate a key using DNS CERT, as specified in RFC-4398.
 
   @item pka
   Locate a key using DNS PKA.
@@ -1599,6 +1735,10 @@ mechanisms, in the order they are to be tried:
   Locate a key using DANE, as specified
   in draft-ietf-dane-openpgpkey-05.txt.
 
+  @item wkd
+  Locate a key using the Web Key Directory protocol.
+  This is an experimental method and semantics may change.
+
   @item ldap
   Using DNS Service Discovery, check the domain in question for any LDAP
   keyservers to use.  If this fails, attempt to locate the key using the
@@ -1613,7 +1753,7 @@ mechanisms, in the order they are to be tried:
   may be used here to query that particular keyserver.
 
   @item local
-  Locate the key using the local keyrings.  This mechanism allows to
+  Locate the key using the local keyrings.  This mechanism allows the user to
   select the order a local key lookup is done.  Thus using
   @samp{--auto-key-locate local} is identical to
   @option{--no-auto-key-locate}.
@@ -1630,13 +1770,34 @@ mechanisms, in the order they are to be tried:
 
 @end table
 
-@item --keyid-format @code{short|0xshort|long|0xlong}
+@item --auto-key-retrieve
+@itemx --no-auto-key-retrieve
+@opindex auto-key-retrieve
+@opindex no-auto-key-retrieve
+This option enables the automatic retrieving of keys from a keyserver
+when verifying signatures made by keys that are not on the local
+keyring.
+
+If the method "wkd" is included in the list of methods given to
+@option{auto-key-locate}, the signer's user ID is part of the
+signature, and the option @option{--disable-signer-uid} is not used,
+the "wkd" method may also be used to retrieve a key.
+
+Note that this option makes a "web bug" like behavior possible.
+Keyserver or Web Key Directory operators can see which keys you
+request, so by sending you a message signed by a brand new key (which
+you naturally will not have on your local keyring), the operator can
+tell both your IP address and the time when you verified the
+signature.
+
+@item --keyid-format @code{none|short|0xshort|long|0xlong}
 @opindex keyid-format
-Select how to display key IDs. "short" is the traditional 8-character
-key ID. "long" is the more accurate (but less convenient)
-16-character key ID. Add an "0x" to either to include an "0x" at the
-beginning of the key ID, as in 0x99242560.  Note that this option is
-ignored if the option --with-colons is used.
+Select how to display key IDs.  "none" does not show the key ID at all
+but shows the fingerprint in a separate line.  "short" is the
+traditional 8-character key ID.  "long" is the more accurate (but less
+convenient) 16-character key ID.  Add an "0x" to either to include an
+"0x" at the beginning of the key ID, as in 0x99242560.  Note that this
+option is ignored if the option @option{--with-colons} is used.
 
 @item --keyserver @code{name}
 @opindex keyserver
@@ -1644,7 +1805,7 @@ This option is deprecated - please use the @option{--keyserver} in
 @file{dirmngr.conf} instead.
 
 Use @code{name} as your keyserver. This is the server that
-@option{--recv-keys}, @option{--send-keys}, and @option{--search-keys}
+@option{--receive-keys}, @option{--send-keys}, and @option{--search-keys}
 will communicate with to receive keys from, send keys to, and search for
 keys on. The format of the @code{name} is a URI:
 `scheme:[//]keyservername[:port]' The scheme is the type of keyserver:
@@ -1687,15 +1848,8 @@ are available for all keyserver types, some common options are:
   used with HKP keyservers.
 
   @item auto-key-retrieve
-  This option enables the automatic retrieving of keys from a keyserver
-  when verifying signatures made by keys that are not on the local
-  keyring.
-
-  Note that this option makes a "web bug" like behavior possible.
-  Keyserver operators can see which keys you request, so by sending you
-  a message signed by a brand new key (which you naturally will not have
-  on your local keyring), the operator can tell both your IP address and
-  the time when you verified the signature.
+  This is an obsolete alias for the option @option{auto-key-retrieve}.
+  Please do not use it; it will be removed in future versions..
 
   @item honor-keyserver-url
   When using @option{--refresh-keys}, if the key in question has a preferred
@@ -1707,9 +1861,9 @@ are available for all keyserver types, some common options are:
   refreshed.  Thus this option is not enabled by default.
 
   @item honor-pka-record
-  If auto-key-retrieve is set, and the signature being verified has a
-  PKA record, then use the PKA information to fetch the key. Defaults
-  to "yes".
+  If @option{--auto-key-retrieve} is used, and the signature being
+  verified has a PKA record, then use the PKA information to fetch
+  the key. Defaults to "yes".
 
   @item include-subkeys
   When receiving a key, include subkeys as potential targets. Note that
@@ -1720,12 +1874,12 @@ are available for all keyserver types, some common options are:
   Tell the keyserver helper program how long (in seconds) to try and
   perform a keyserver action before giving up. Note that performing
   multiple actions at the same time uses this timeout value per action.
-  For example, when retrieving multiple keys via @option{--recv-keys}, the
+  For example, when retrieving multiple keys via @option{--receive-keys}, the
   timeout applies separately to each key retrieval, and not to the
-  @option{--recv-keys} command as a whole. Defaults to 30 seconds.
+  @option{--receive-keys} command as a whole. Defaults to 30 seconds.
 
   @item http-proxy=@code{value}
-  This options is deprecated.
+  This option is deprecated.
   Set the proxy to use for HTTP and HKP keyservers.
   This overrides any proxy defined in @file{dirmngr.conf}.
 
@@ -1760,26 +1914,7 @@ key signer (defaults to 3)
 @item --tofu-default-policy @code{auto|good|unknown|bad|ask}
 @opindex tofu-default-policy
 The default TOFU policy (defaults to @code{auto}).  For more
-information about the meaning of this option, @xref{trust-model-tofu}.
-
-@item --tofu-db-format @code{auto|split|flat}
-@opindex tofu-default-policy
-The format for the TOFU DB.
-
-The split file format splits the data across many DBs under the
-@code{tofu.d} directory (one per email address and one per key).  This
-makes it easier to automatically synchronize the data using a tool
-such as Unison (@url{https://www.cis.upenn.edu/~bcpierce/unison/}),
-since the individual files change rarely.
-
-The flat file format keeps all of the data in the single file
-@code{tofu.db}.  This format results in better performance.
-
-If set to auto (which is the default), GnuPG will first check for the
-existence of @code{tofu.d} and @code{tofu.db}.  If one of these
-exists, the corresponding format is used.  If neither or both of these
-exist, then GnuPG defaults to the @code{split} format.  In the latter
-case, a warning is emitted.
+information about the meaning of this option, @pxref{trust-model-tofu}.
 
 @item --max-cert-depth @code{n}
 @opindex max-cert-depth
@@ -1789,7 +1924,7 @@ Maximum depth of a certification chain (default is 5).
 @opindex no-sig-cache
 Do not cache the verification status of key signatures.
 Caching gives a much better performance in key listings. However, if
-you suspect that your public keyring is not save against write
+you suspect that your public keyring is not safe against write
 modifications, you can use this option to disable the caching. It
 probably does not make sense to disable it because all kind of damage
 can be done if someone else has write access to your public keyring.
@@ -1823,9 +1958,7 @@ file name.
 @item --dirmngr-program @var{file}
 @opindex dirmngr-program
 Specify a dirmngr program to be used for keyserver access.  The
-default value is @file{@value{BINDIR}/dirmngr}.  This is only used as a
-fallback when the environment variable @code{DIRMNGR_INFO} is not set or
-a running dirmngr cannot be connected.
+default value is @file{@value{BINDIR}/dirmngr}.
 
 @item --no-autostart
 @opindex no-autostart
@@ -1961,6 +2094,22 @@ limited countermeasure against traffic analysis. If this option or
 @option{--recipient} is not specified, GnuPG asks for the user ID unless
 @option{--default-recipient} is given.
 
+@item --recipient-file @var{file}
+@itemx -f
+@opindex recipient-file
+This option is similar to @option{--recipient} except that it
+encrypts to a key stored in the given file.  @var{file} must be the
+name of a file containing exactly one key.  @command{@gpgname} assumes that
+the key in this file is fully valid.
+
+@item --hidden-recipient-file @var{file}
+@itemx -F
+@opindex hidden-recipient-file
+This option is similar to @option{--hidden-recipient} except that it
+encrypts to a key stored in the given file.  @var{file} must be the
+name of a file containing exactly one key.  @command{@gpgname} assumes that
+the key in this file is fully valid.
+
 @item --encrypt-to @code{name}
 @opindex encrypt-to
 Same as @option{--recipient} but this one is intended for use in the
@@ -1979,17 +2128,12 @@ recipients given either by use of @option{--recipient} or by the asked user id.
 No trust checking is performed for these user ids and even disabled
 keys can be used.
 
-@item --encrypt-to-default-key
-@opindex encrypt-to-default-key
-If the default secret key is taken from @option{--default-key}, then
-also encrypt to that key.
-
 @item --no-encrypt-to
 @opindex no-encrypt-to
 Disable the use of all @option{--encrypt-to} and
 @option{--hidden-encrypt-to} keys.
 
-@item --group @code{name=value}
+@item --group @code{name=value}
 @opindex group
 Sets up a named group, which is similar to aliases in email programs.
 Any time the group name is a recipient (@option{-r} or
@@ -2019,11 +2163,20 @@ Remove all entries from the @option{--group} list.
 Use @var{name} as the key to sign with. Note that this option overrides
 @option{--default-key}.
 
+@item --sender @var{mbox}
+@opindex sender
+This option has two purposes.  @var{mbox} must either be a complete
+user id with a proper mail address or just a mail address.  When
+creating a signature this option tells gpg the user id of a key used
+to make a signature if the key was not directly specified by a user
+id.  When verifying a signature the @var{mbox} is used to restrict the
+information printed by the TOFU code to matching user ids.
+
 @item --try-secret-key @var{name}
 @opindex try-secret-key
 For hidden recipients GPG needs to know the keys to use for trial
 decryption.  The key set with @option{--default-key} is always tried
-first, but this is often not sufficient.  This option allows to set more
+first, but this is often not sufficient.  This option allows setting more
 keys to be used for trial decryption.  Although any valid user-id
 specification may be used for @var{name} it makes sense to use at least
 the long keyid to avoid ambiguities.  Note that gpg-agent might pop up a
@@ -2075,7 +2228,8 @@ Assume the input data is not in ASCII armored format.
 @item --output @var{file}
 @itemx -o @var{file}
 @opindex output
-Write output to @var{file}.
+Write output to @var{file}.  To write to stdout use @code{-} as the
+filename.
 
 @item --max-output @code{n}
 @opindex max-output
@@ -2087,6 +2241,15 @@ works properly with such messages, there is often a desire to set a
 maximum file size that will be generated before processing is forced to
 stop by the OS limits. Defaults to 0, which means "no limit".
 
+@item --input-size-hint @var{n}
+@opindex input-size-hint
+This option can be used to tell GPG the size of the input data in
+bytes.  @var{n} must be a positive base-10 number.  This option is
+only useful if the input is not taken from a file.  GPG may use this
+hint to optimize its buffer allocation strategy.  It is also used by
+the @option{--status-fd} line ``PROGRESS'' to provide a value for
+``total'' if that is not available by other means.
+
 @item --import-options @code{parameters}
 @opindex import-options
 This is a space or comma delimited string that gives options for
@@ -2106,7 +2269,7 @@ opposite meaning. The options are:
   a formerly deleted key does not automatically gain an ownertrust
   values merely due to import.  On the other hand it is sometimes
   necessary to re-import a trusted set of keys again but keeping
-  already assigned ownertrust values.  This can be achived by using
+  already assigned ownertrust values.  This can be achieved by using
   this option.
 
   @item repair-pks-subkey-bug
@@ -2115,7 +2278,19 @@ opposite meaning. The options are:
   that this cannot completely repair the damaged key as some crucial data
   is removed by the keyserver, but it does at least give you back one
   subkey. Defaults to no for regular @option{--import} and to yes for
-  keyserver @option{--recv-keys}.
+  keyserver @option{--receive-keys}.
+
+  @item import-show
+  Show a listing of the key as imported right before it is stored.
+  This can be combined with the option @option{--dry-run} to only look
+  at keys.
+
+  @item import-export
+  Run the entire import code but instead of storing the key to the
+  local keyring write it to the output.  The export options
+  @option{export-pka} and @option{export-dane} affect the output.  This
+  option can be used to remove all invalid parts from a key without the
+  need to store it.
 
   @item merge-only
   During import, allow key updates to existing keys, but do not allow
@@ -2134,13 +2309,106 @@ opposite meaning. The options are:
   the most recent self-signature on each user ID. This option is the
   same as running the @option{--edit-key} command "minimize" after import.
   Defaults to no.
+
+  @item restore
+  @itemx import-restore
+  Import in key restore mode.  This imports all data which is usually
+  skipped during import; including all GnuPG specific data.  All other
+  contradicting options are overridden.
+@end table
+
+@item --import-filter @code{@var{name}=@var{expr}}
+@itemx --export-filter @code{@var{name}=@var{expr}}
+@opindex import-filter
+@opindex export-filter
+These options define an import/export filter which are applied to the
+imported/exported keyblock right before it will be stored/written.
+@var{name} defines the type of filter to use, @var{expr} the
+expression to evaluate.  The option can be used several times which
+then appends more expression to the same @var{name}.
+
+@noindent
+The available filter types are:
+
+@table @asis
+
+  @item keep-uid
+  This filter will keep a user id packet and its dependent packets in
+  the keyblock if the expression evaluates to true.
+
+  @item drop-subkey
+  This filter drops the selected subkeys.
+  Currently only implemented for --export-filter.
+
+  @item drop-sig
+  This filter drops the selected key signatures on user ids.
+  Self-signatures are not considered.
+  Currently only implemented for --import-filter.
+
+@end table
+
+For the syntax of the expression see the chapter "FILTER EXPRESSIONS".
+The property names for the expressions depend on the actual filter
+type and are indicated in the following table.
+
+The available properties are:
+
+@table @asis
+
+  @item uid
+  A string with the user id.  (keep-uid)
+
+  @item mbox
+  The addr-spec part of a user id with mailbox or the empty string.
+  (keep-uid)
+
+  @item key_algo
+  A number with the public key algorithm of a key or subkey packet.
+  (drop-subkey)
+
+  @item key_created
+  @itemx key_created_d
+  The first is the timestamp a public key or subkey packet was
+  created.  The second is the same but given as an ISO string,
+  e.g. "2016-08-17". (drop-subkey)
+
+  @item primary
+  Boolean indicating whether the user id is the primary one.  (keep-uid)
+
+  @item expired
+  Boolean indicating whether a user id (keep-uid), a key (drop-subkey), or a
+  signature (drop-sig) expired.
+
+  @item revoked
+  Boolean indicating whether a user id (keep-uid) or a key (drop-subkey) has
+  been revoked.
+
+  @item disabled
+  Boolean indicating whether a primary key is disabled. (not used)
+
+  @item secret
+  Boolean indicating whether a key or subkey is a secret one.
+  (drop-subkey)
+
+  @item sig_created
+  @itemx sig_created_d
+  The first is the timestamp a signature packet was created.  The
+  second is the same but given as an ISO date string,
+  e.g. "2016-08-17". (drop-sig)
+
+  @item sig_algo
+  A number with the public key algorithm of a signature packet. (drop-sig)
+
+  @item sig_digest_algo
+  A number with the digest algorithm of a signature packet. (drop-sig)
+
 @end table
 
 @item --export-options @code{parameters}
 @opindex export-options
 This is a space or comma delimited string that gives options for
-exporting keys. Options can be prepended with a `no-' to give the
-opposite meaning. The options are:
+exporting keys.  Options can be prepended with a `no-' to give the
+opposite meaning.  The options are:
 
 @table @asis
 
@@ -2168,6 +2436,13 @@ opposite meaning. The options are:
   @c when the exported subkey is to be used on an unattended machine where
   @c a passphrase doesn't necessarily make sense. Defaults to no.
 
+  @item backup
+  @itemx export-backup
+  Export for use as a backup.  The exported data includes all data
+  which is needed to restore the key or keys later with GnuPG.  The
+  format is basically the OpenPGP format but enhanced with GnuPG
+  specific data.  All other contradicting options are overridden.
+
   @item export-clean
   Compact (remove all signatures from) user IDs on the key being
   exported if the user IDs are not usable. Also, do not export any
@@ -2182,6 +2457,18 @@ opposite meaning. The options are:
   most recent self-signature on each user ID. This option is the same as
   running the @option{--edit-key} command "minimize" before export except
   that the local copy of the key is not modified. Defaults to no.
+
+  @item export-pka
+  Instead of outputting the key material output PKA records suitable
+  to put into DNS zone files.  An ORIGIN line is printed before each
+  record to allow diverting the records to the corresponding zone file.
+
+  @item export-dane
+  Instead of outputting the key material output OpenPGP DANE records
+  suitable to put into DNS zone files.  An ORIGIN line is printed before
+  each record to allow diverting the records to the corresponding zone
+  file.
+
 @end table
 
 @item --with-colons
@@ -2193,20 +2480,6 @@ as it is easily machine parsed. The details of this format are
 documented in the file @file{doc/DETAILS}, which is included in the GnuPG
 source distribution.
 
-
-@item --print-pka-records
-@opindex print-pka-records
-Modify the output of the list commands to print PKA records suitable
-to put into DNS zone files.  An ORIGIN line is printed before each
-record to allow diverting the records to the corresponding zone file.
-
-@item --print-dane-records
-@opindex print-dane-records
-Modify the output of the list commands to print OpenPGP DANE records
-suitable to put into DNS zone files.  An ORIGIN line is printed before
-each record to allow diverting the records to the corresponding zone
-file.
-
 @item --fixed-list-mode
 @opindex fixed-list-mode
 Do not merge primary user ID and primary key in @option{--with-colon}
@@ -2219,20 +2492,34 @@ obsolete; it does not harm to use it though.
 Revert to the pre-2.1 public key list mode.  This only affects the
 human readable output and not the machine interface
 (i.e. @code{--with-colons}).  Note that the legacy format does not
-allow to convey suitable information for elliptic curves.
+convey suitable information for elliptic curves.
 
 @item --with-fingerprint
 @opindex with-fingerprint
 Same as the command @option{--fingerprint} but changes only the format
 of the output and may be used together with another command.
 
+@item --with-subkey-fingerprint
+@opindex with-subkey-fingerprint
+If a fingerprint is printed for the primary key, this option forces
+printing of the fingerprint for all subkeys.  This could also be
+achieved by using the @option{--with-fingerprint} twice but by using
+this option along with keyid-format "none" a compact fingerprint is
+printed.
+
 @item --with-icao-spelling
 @opindex with-icao-spelling
 Print the ICAO spelling of the fingerprint in addition to the hex digits.
 
 @item --with-keygrip
 @opindex with-keygrip
-Include the keygrip in the key listings.
+Include the keygrip in the key listings.  In @code{--with-colons} mode
+this is implicitly enable for secret keys.
+
+@item --with-wkd-hash
+@opindex with-wkd-hash
+Print a Web Key Directory identifier along with each user ID in key
+listings.  This is an experimental feature and semantics may change.
 
 @item --with-secret
 @opindex with-secret
@@ -2245,7 +2532,7 @@ done with @code{--with-colons}.
 @c ********  OPENPGP OPTIONS  ****************
 @c *******************************************
 @node OpenPGP Options
-@subsection OpenPGP protocol specific options.
+@subsection OpenPGP protocol specific options
 
 @table @gnupgtabopt
 
@@ -2280,6 +2567,14 @@ Disable the use of the modification detection code. Note that by
 using this option, the encrypted message becomes vulnerable to a
 message modification attack.
 
+@item --disable-signer-uid
+@opindex disable-signer-uid
+By default the user ID of the signing key is embedded in the data
+signature.  As of now this is only done if the signing key has been
+specified with @option{local-user} using a mail address.  This
+information can be helpful for verifier to locate the key; see
+option @option{--auto-key-retrieve}.
+
 @item --personal-cipher-preferences @code{string}
 @opindex personal-cipher-preferences
 Set the list of personal cipher preferences to @code{string}.  Use
@@ -2299,7 +2594,7 @@ to safely override the algorithm chosen by the recipient key
 preferences, as GPG will only select an algorithm that is usable by
 all recipients.  The most highly ranked digest algorithm in this list
 is also used when signing without encryption
-(e.g. @option{--clearsign} or @option{--sign}).
+(e.g. @option{--clear-sign} or @option{--sign}).
 
 @item --personal-compress-preferences @code{string}
 @opindex personal-compress-preferences
@@ -2380,6 +2675,13 @@ Reset all packet, cipher and digest options to strict RFC-4880
 behavior. Note that this is currently the same thing as
 @option{--openpgp}.
 
+@item --rfc4880bis
+@opindex rfc4880bis
+Enable experimental features from proposed updates to RFC-4880.  This
+option can be used in addition to the other compliance options.
+Warning: The behavior may change with any GnuPG release and created
+keys or data may not be usable with future GnuPG versions.
+
 @item --rfc2440
 @opindex rfc2440
 Reset all packet, cipher and digest options to strict RFC-2440
@@ -2391,7 +2693,7 @@ Set up all options to be as PGP 6 compliant as possible. This
 restricts you to the ciphers IDEA (if the IDEA plugin is installed),
 3DES, and CAST5, the hashes MD5, SHA1 and RIPEMD160, and the
 compression algorithms none and ZIP. This also disables
---throw-keyids, and making signatures with signing subkeys as PGP 6
+@option{--throw-keyids}, and making signatures with signing subkeys as PGP 6
 does not understand signatures made by signing subkeys.
 
 This option implies @option{--disable-mdc --escape-from-lines}.
@@ -2411,6 +2713,12 @@ this does is disable @option{--throw-keyids} and set
 @option{--escape-from-lines}.  All algorithms are allowed except for the
 SHA224, SHA384, and SHA512 digests.
 
+@item --compliance @var{string}
+@opindex compliance
+This option can be used instead of one of the options above.  Valid
+values for @var{string} are the above option names (without the double
+dash) and possibly others as shown when using "help" for @var{value}.
+
 @end table
 
 
@@ -2418,7 +2726,7 @@ SHA224, SHA384, and SHA512 digests.
 @c ********  ESOTERIC OPTIONS  ***************
 @c *******************************************
 @node GPG Esoteric Options
-@subsection Doing things one usually doesn't want to do.
+@subsection Doing things one usually doesn't want to do
 
 @table @gnupgtabopt
 
@@ -2430,7 +2738,7 @@ Don't make any changes (this is not completely implemented).
 @item --list-only
 @opindex list-only
 Changes the behaviour of some commands. This is like @option{--dry-run} but
-different in some cases. The semantic of this command may be extended in
+different in some cases. The semantic of this option may be extended in
 the future. Currently it only skips the actual decryption pass and
 therefore enables a fast listing of the encryption keys.
 
@@ -2490,6 +2798,9 @@ forth to @var{epoch} which is the number of seconds elapsed since the year
 1970.  Alternatively @var{epoch} may be given as a full ISO time string
 (e.g. "20070924T154812").
 
+If you suffix @var{epoch} with an exclamation mark (!), the system time
+will appear to be frozen at the specified time.
+
 @item --enable-progress-filter
 @opindex enable-progress-filter
 Enable certain PROGRESS status outputs. This option allows frontends
@@ -2513,9 +2824,8 @@ Write log output to file descriptor @code{n} and not to STDERR.
 @item --log-file @code{file}
 @itemx --logger-file @code{file}
 @opindex log-file
-Same as @option{--logger-fd}, except the logger data is written to file
-@code{file}.  Note that @option{--log-file} is only implemented for
-GnuPG-2.
+Same as @option{--logger-fd}, except the logger data is written to
+file @code{file}.  Use @file{socket://} to log to socket.
 
 @item --attribute-fd @code{n}
 @opindex attribute-fd
@@ -2532,7 +2842,7 @@ file @code{file}.
 @item --comment @code{string}
 @itemx --no-comments
 @opindex comment
-Use @code{string} as a comment string in clear text signatures and ASCII
+Use @code{string} as a comment string in cleartext signatures and ASCII
 armored messages or keys (see @option{--armor}). The default behavior is
 not to use a comment string. @option{--comment} may be repeated multiple
 times to get multiple comment strings. @option{--no-comments} removes
@@ -2546,9 +2856,9 @@ protected by the signature.
 @opindex emit-version
 Force inclusion of the version string in ASCII armored output.  If
 given once only the name of the program and the major number is
-emitted (default), given twice the minor is also emitted, given triple
-the micro is added, and given quad an operating system identification
-is also emitted.  @option{--no-emit-version} disables the version
+emitted, given twice the minor is also emitted, given thrice
+the micro is added, and given four times an operating system identification
+is also emitted.  @option{--no-emit-version} (default) disables the version
 line.
 
 @item --sig-notation @code{name=value}
@@ -2564,7 +2874,7 @@ must contain a '@@' character in the form keyname@@domain.example.com
 is to help prevent pollution of the IETF reserved notation
 namespace. The @option{--expert} flag overrides the '@@'
 check. @code{value} may be any printable string; it will be encoded in
-UTF8, so you should check that your @option{--display-charset} is set
+UTF-8, so you should check that your @option{--display-charset} is set
 correctly. If you prefix @code{name} with an exclamation mark (!), the
 notation data will be flagged as critical
 (rfc4880:5.2.3.16). @option{--sig-notation} sets a notation for data
@@ -2609,7 +2919,7 @@ The same %-expandos used for notation data are available here as well.
 @opindex set-filename
 Use @code{string} as the filename which is stored inside messages.
 This overrides the default, which is to use the actual filename of the
-file being encrypted.  Using the empty string for @var{string}
+file being encrypted.  Using the empty string for @code{string}
 effectively removes the filename from the output.
 
 @item --for-your-eyes-only
@@ -2625,7 +2935,7 @@ to display the message. This option overrides @option{--set-filename}.
 @itemx --no-use-embedded-filename
 @opindex use-embedded-filename
 Try to create a file with a name as embedded in the data. This can be
-a dangerous option as it allows to overwrite files. Defaults to no.
+a dangerous option as it enables overwriting files. Defaults to no.
 
 @item --cipher-algo @code{name}
 @opindex cipher-algo
@@ -2857,6 +3167,10 @@ and do not provide alternate keyrings via @option{--keyring} or
 @option{--secret-keyring}, then GnuPG will still use the default public or
 secret keyrings.
 
+@item --no-keyring
+@opindex no-keyring
+Do not add use any keyrings even if specified as options.
+
 @item --skip-verify
 @opindex skip-verify
 Skip the signature verification step. This may be
@@ -2902,13 +3216,17 @@ inappropriate plaintext so they can take action against the offending
 user.
 
 @item --override-session-key @code{string}
+@itemx --override-session-key-fd @code{fd}
 @opindex override-session-key
-Don't use the public key but the session key @code{string}. The format
-of this string is the same as the one printed by
-@option{--show-session-key}. This option is normally not used but comes
-handy in case someone forces you to reveal the content of an encrypted
-message; using this option you can do this without handing out the
-secret key.
+Don't use the public key but the session key @code{string} respective
+the session key taken from the first line read from file descriptor
+@code{fd}.  The format of this string is the same as the one printed
+by @option{--show-session-key}. This option is normally not used but
+comes handy in case someone forces you to reveal the content of an
+encrypted message; using this option you can do this without handing
+out the secret key.  Note that using @option{--override-session-key}
+may reveal the session key to all local users via the global process
+table.
 
 @item --ask-sig-expire
 @itemx --no-ask-sig-expire
@@ -2942,6 +3260,13 @@ letter d (for days), w (for weeks), m (for months), or y (for years)
 (for example "2m" for two months, or "5y" for five years), or an
 absolute date in the form YYYY-MM-DD. Defaults to "0".
 
+@item --default-new-key-algo @var{string}
+@opindex default-new-key-algo @var{string}
+This option can be used to change the default algorithms for key
+generation.  Note that the advanced key generation commands can always
+be used to specify a key algorithm directly.  Please consult the
+source code to learn the syntax of @var{string}.
+
 @item --allow-secret-key-import
 @opindex allow-secret-key-import
 This is an obsolete option and is not used anywhere.
@@ -2961,7 +3286,7 @@ workaround!
 
 @item --enable-special-filenames
 @opindex enable-special-filenames
-This options enables a mode in which filenames of the form
+This option enables a mode in which filenames of the form
 @file{-&n}, where n is a non-negative decimal number,
 refer to the file descriptor n and not to a file with that name.
 
@@ -3008,7 +3333,7 @@ internally used by the @command{gpgconf} tool.
 @opindex gpgconf-test
 This is more or less dummy action.  However it parses the configuration
 file and returns with failure if the configuration file would prevent
-@command{gpg} from startup.  Thus it may be used to run a syntax check
+@command{@gpgname} from startup.  Thus it may be used to run a syntax check
 on the configuration file.
 
 @end table
@@ -3024,7 +3349,7 @@ on the configuration file.
 @item --show-photos
 @itemx --no-show-photos
 @opindex show-photos
-Causes @option{--list-keys}, @option{--list-sigs},
+Causes @option{--list-keys}, @option{--list-signatures},
 @option{--list-public-keys}, @option{--list-secret-keys}, and verifying
 a signature to also display the photo ID attached to the key, if
 any. See also @option{--photo-viewer}. These options are deprecated. Use
@@ -3044,7 +3369,7 @@ Identical to @option{--trust-model always}. This option is deprecated.
 @item --show-notation
 @itemx --no-show-notation
 @opindex show-notation
-Show signature notations in the @option{--list-sigs} or @option{--check-sigs} listings
+Show signature notations in the @option{--list-signatures} or @option{--check-signatures} listings
 as well as when verifying a signature with a notation in it. These
 options are deprecated. Use @option{--list-options [no-]show-notation}
 and/or @option{--verify-options [no-]show-notation} instead.
@@ -3052,7 +3377,7 @@ and/or @option{--verify-options [no-]show-notation} instead.
 @item --show-policy-url
 @itemx --no-show-policy-url
 @opindex show-policy-url
-Show policy URLs in the @option{--list-sigs} or @option{--check-sigs}
+Show policy URLs in the @option{--list-signatures} or @option{--check-signatures}
 listings as well as when verifying a signature with a policy URL in
 it. These options are deprecated. Use @option{--list-options
 [no-]show-policy-url} and/or @option{--verify-options
@@ -3078,7 +3403,7 @@ current home directory (@pxref{option --homedir}).
 @table @file
 
   @item gpg.conf
-  @cindex gpg.conf
+  @efindex gpg.conf
   This is the standard configuration file read by @command{@gpgname} on
   startup.  It may contain any valid long option; the leading two dashes
   may not be entered and the option may not be abbreviated.  This default
@@ -3087,7 +3412,6 @@ current home directory (@pxref{option --homedir}).
 
 @end table
 
-@c man:.RE
 Note that on larger installations, it is useful to put predefined files
 into the directory @file{@value{SYSCONFSKELDIR}} so that
 newly created users start up with a working configuration.
@@ -3095,32 +3419,46 @@ For existing users a small
 helper script is provided to create these files (@pxref{addgnupghome}).
 
 For internal purposes @command{@gpgname} creates and maintains a few other
-files; They all live in in the current home directory (@pxref{option
+files; They all live in the current home directory (@pxref{option
 --homedir}).  Only the @command{@gpgname} program may modify these files.
 
 
 @table @file
+  @item ~/.gnupg
+  @efindex ~/.gnupg
+  This is the default home directory which is used if neither the
+  environment variable @code{GNUPGHOME} nor the option
+  @option{--homedir} is given.
+
   @item ~/.gnupg/pubring.gpg
+  @efindex pubring.gpg
   The public keyring.  You should backup this file.
 
   @item ~/.gnupg/pubring.gpg.lock
   The lock file for the public keyring.
 
   @item ~/.gnupg/pubring.kbx
-  The public keyring using a different format.  This file is sharred
+  @efindex pubring.kbx
+  The public keyring using a different format.  This file is shared
   with @command{gpgsm}.  You should backup this file.
 
   @item ~/.gnupg/pubring.kbx.lock
   The lock file for @file{pubring.kbx}.
 
   @item ~/.gnupg/secring.gpg
+  @efindex secring.gpg
   A secret keyring as used by GnuPG versions before 2.1.  It is not
   used by GnuPG 2.1 and later.
 
+  @item ~/.gnupg/secring.gpg.lock
+  The lock file for the secret keyring.
+
   @item ~/.gnupg/.gpg-v21-migrated
+  @efindex .gpg-v21-migrated
   File indicating that a migration to GnuPG 2.1 has been done.
 
   @item ~/.gnupg/trustdb.gpg
+  @efindex trustdb.gpg
   The trust database.  There is no need to backup this file; it is better
   to backup the ownertrust values (@pxref{option --export-ownertrust}).
 
@@ -3128,12 +3466,11 @@ files; They all live in in the current home directory (@pxref{option
   The lock file for the trust database.
 
   @item ~/.gnupg/random_seed
+  @efindex random_seed
   A file used to preserve the state of the internal random pool.
 
-  @item ~/.gnupg/secring.gpg.lock
-  The lock file for the secret keyring.
-
   @item ~/.gnupg/openpgp-revocs.d/
+  @efindex openpgp-revocs.d
   This is the directory where gpg stores pre-generated revocation
   certificates.  The file name corresponds to the OpenPGP fingerprint of
   the respective key.  It is suggested to backup those certificates and
@@ -3143,43 +3480,40 @@ files; They all live in in the current home directory (@pxref{option
   You should backup all files in this directory and take care to keep
   this backup closed away.
 
-  @item @value{DATADIR}/options.skel
-  The skeleton options file.
-
-  @item @value{LIBDIR}/
-  Default location for extensions.
-
 @end table
 
-@c man:.RE
 Operation is further controlled by a few environment variables:
 
 @table @asis
 
   @item HOME
+  @efindex HOME
   Used to locate the default home directory.
 
   @item GNUPGHOME
+  @efindex GNUPGHOME
   If set directory used instead of "~/.gnupg".
 
   @item GPG_AGENT_INFO
-  This variable was used by GnuPG versions before 2.1
+  This variable is obsolete; it was used by GnuPG versions before 2.1.
 
   @item PINENTRY_USER_DATA
+  @efindex PINENTRY_USER_DATA
   This value is passed via gpg-agent to pinentry.  It is useful to convey
   extra information to a custom pinentry.
 
   @item COLUMNS
   @itemx LINES
+  @efindex COLUMNS
+  @efindex LINES
   Used to size some displays to the full size of the screen.
 
-
   @item LANGUAGE
+  @efindex LANGUAGE
   Apart from its use by GNU, it is used in the W32 version to override the
   language selection done through the Registry.  If used and set to a
   valid and available language name (@var{langid}), the file with the
   translation is loaded from
-
   @code{@var{gpgdir}/gnupg.nls/@var{langid}.mo}.  Here @var{gpgdir} is the
   directory out of which the gpg binary has been loaded.  If it can't be
   loaded the Registry is tried and as last resort the native Windows
@@ -3202,8 +3536,8 @@ Operation is further controlled by a few environment variables:
 @item gpg -se -r @code{Bob} @code{file}
 sign and encrypt for user Bob
 
-@item gpg --clearsign @code{file}
-make a clear text signature
+@item gpg --clear-sign @code{file}
+make a cleartext signature
 
 @item gpg -sb @code{file}
 make a detached signature
@@ -3218,14 +3552,16 @@ show keys
 show fingerprint
 
 @item gpg --verify @code{pgpfile}
-@itemx gpg --verify @code{sigfile}
-Verify the signature of the file but do not output the data. The
-second form is used for detached signatures, where @code{sigfile}
-is the detached signature (either ASCII armored or binary) and
-are the signed data; if this is not given, the name of
-the file holding the signed data is constructed by cutting off the
-extension (".asc" or ".sig") of @code{sigfile} or by asking the
-user for the filename.
+@itemx gpg --verify @code{sigfile} [@code{datafile}]
+Verify the signature of the file but do not output the data unless
+requested.  The second form is used for detached signatures, where
+@code{sigfile} is the detached signature (either ASCII armored or
+binary) and @code{datafile} are the signed data; if this is not given, the name of the
+file holding the signed data is constructed by cutting off the
+extension (".asc" or ".sig") of @code{sigfile} or by asking the user
+for the filename.  If the option @option{--output} is also used the
+signed data is written to the file specified by that option; use
+@code{-} to write the signed data to stdout.
 @end table
 
 
@@ -3239,6 +3575,135 @@ user for the filename.
 @include specify-user-id.texi
 @end ifset
 
+@mansect filter expressions
+@chapheading FILTER EXPRESSIONS
+
+The options @option{--import-filter} and @option{--export-filter} use
+expressions with this syntax (square brackets indicate an optional
+part and curly braces a repetition, white space between the elements
+are allowed):
+
+@c man:.RS
+@example
+  [lc] @{[@{flag@}] PROPNAME op VALUE [lc]@}
+@end example
+@c man:.RE
+
+The name of a property (@var{PROPNAME}) may only consist of letters,
+digits and underscores.  The description for the filter type
+describes which properties are defined.  If an undefined property is
+used it evaluates to the empty string.  Unless otherwise noted, the
+@var{VALUE} must always be given and may not be the empty string.  No
+quoting is defined for the value, thus the value may not contain the
+strings @code{&&} or @code{||}, which are used as logical connection
+operators.  The flag @code{--} can be used to remove this restriction.
+
+Numerical values are computed as long int; standard C notation
+applies.  @var{lc} is the logical connection operator; either
+@code{&&} for a conjunction or @code{||} for a disjunction.  A
+conjunction is assumed at the begin of an expression.  Conjunctions
+have higher precedence than disjunctions.  If @var{VALUE} starts with
+one of the characters used in any @var{op} a space after the
+@var{op} is required.
+
+@noindent
+The supported operators (@var{op}) are:
+
+@table @asis
+
+  @item =~
+  Substring must match.
+
+  @item  !~
+  Substring must not match.
+
+  @item  =
+  The full string must match.
+
+  @item  <>
+  The full string must not match.
+
+  @item  ==
+  The numerical value must match.
+
+  @item  !=
+  The numerical value must not match.
+
+  @item  <=
+  The numerical value of the field must be LE than the value.
+
+  @item  <
+  The numerical value of the field must be LT than the value.
+
+  @item  >
+  The numerical value of the field must be GT than the value.
+
+  @item  >=
+  The numerical value of the field must be GE than the value.
+
+  @item  -le
+  The string value of the field must be less or equal than the value.
+
+  @item  -lt
+  The string value of the field must be less than the value.
+
+  @item  -gt
+  The string value of the field must be greater than the value.
+
+  @item  -ge
+  The string value of the field must be greater or equal than the value.
+
+  @item  -n
+  True if value is not empty (no value allowed).
+
+  @item  -z
+  True if value is empty (no value allowed).
+
+  @item  -t
+  Alias for "PROPNAME != 0" (no value allowed).
+
+  @item  -f
+  Alias for "PROPNAME == 0" (no value allowed).
+
+@end table
+
+@noindent
+Values for @var{flag} must be space separated.  The supported flags
+are:
+
+@table @asis
+  @item --
+  @var{VALUE} spans to the end of the expression.
+  @item -c
+  The string match in this part is done case-sensitive.
+@end table
+
+The filter options concatenate several specifications for a filter of
+the same type.  For example the four options in this example:
+
+@c man:.RS
+@example
+ --import-option keep-uid="uid =~ Alfa"
+ --import-option keep-uid="&& uid !~ Test"
+ --import-option keep-uid="|| uid =~ Alpha"
+ --import-option keep-uid="uid !~ Test"
+@end example
+@c man:.RE
+
+@noindent
+which is equivalent to
+
+@c man:.RS
+@example
+ --import-option \
+  keep-uid="uid =~ Alfa" && uid !~ Test" || uid =~ Alpha" && "uid !~ Test"
+@end example
+@c man:.RE
+
+imports only the user ids of a key containing the strings "Alfa"
+or "Alpha" but not the string "test".
+
+
 @mansect return value
 @chapheading RETURN VALUE
 
@@ -3323,23 +3788,74 @@ already been reported to our bug tracker at http://bugs.gnupg.org .
 @node Unattended Usage of GPG
 @section Unattended Usage
 
-@command{gpg} is often used as a backend engine by other software.  To help
+@command{@gpgname} is often used as a backend engine by other software.  To help
 with this a machine interface has been defined to have an unambiguous
 way to do this.  The options @option{--status-fd} and @option{--batch}
 are almost always required for this.
 
 @menu
+* Programmatic use of GnuPG:: Programmatic use of GnuPG
+* Ephemeral home directories:: Ephemeral home directories
+* The quick key manipulation interface:: The quick key manipulation interface
 * Unattended GPG key generation::  Unattended key generation
 @end menu
 
 
+@node Programmatic use of GnuPG
+@subsection Programmatic use of GnuPG
+
+Please consider using GPGME instead of calling @command{@gpgname}
+directly.  GPGME offers a stable, backend-independent interface for
+many cryptographic operations.  It supports OpenPGP and S/MIME, and
+also allows interaction with various GnuPG components.
+
+GPGME provides a C-API, and comes with bindings for C++, Qt, and
+Python.  Bindings for other languages are available.
+
+@node Ephemeral home directories
+@subsection Ephemeral home directories
+
+Sometimes you want to contain effects of some operation, for example
+you want to import a key to inspect it, but you do not want this key
+to be added to your keyring.  In earlier versions of GnuPG, it was
+possible to specify alternate keyring files for both public and secret
+keys.  In modern GnuPG versions, however, we changed how secret keys
+are stored in order to better protect secret key material, and it was
+not possible to preserve this interface.
+
+The preferred way to do this is to use ephemeral home directories.
+This technique works across all versions of GnuPG.
+
+Create a temporary directory, create (or copy) a configuration that
+meets your needs, make @command{@gpgname} use this directory either
+using the environment variable @var{GNUPGHOME}, or the option
+@option{--homedir}.  GPGME supports this too on a per-context basis,
+by modifying the engine info of contexts.  Now execute whatever
+operation you like, import and export key material as necessary.  Once
+finished, you can delete the directory.  All GnuPG backend services
+that were started will detect this and shut down.
+
+@node The quick key manipulation interface
+@subsection The quick key manipulation interface
+
+Recent versions of GnuPG have an interface to manipulate keys without
+using the interactive command @option{--edit-key}.  This interface was
+added mainly for the benefit of GPGME (please consider using GPGME,
+see the manual subsection ``Programmatic use of GnuPG'').  This
+interface is described in the subsection ``How to manage your keys''.
+
 @node Unattended GPG key generation
 @subsection Unattended key generation
 
-The command @option{--gen-key} may be used along with the option
-@option{--batch} for unattended key generation.  The parameters are
-either read from stdin or given as a file on the command line.
-The format of the parameter file is as follows:
+The command @option{--generate-key} may be used along with the option
+@option{--batch} for unattended key generation.  This is the most
+flexible way of generating keys, but it is also the most complex one.
+Consider using the quick key manipulation interface described in the
+previous subsection ``The quick key manipulation interface''.
+
+The parameters for the key are either read from stdin or given as a
+file on the command line.  The format of the parameter file is as
+follows:
 
 @itemize @bullet
   @item Text only, line length is limited to about 1000 characters.
@@ -3382,16 +3898,21 @@ Perform the key generation.  Note that an implicit commit is done at
 the next @asis{Key-Type} parameter.
 
 @item %pubring @var{filename}
-@itemx %secring @var{filename}
 Do not write the key to the default or commandline given keyring but
 to @var{filename}.  This must be given before the first commit to take
 place, duplicate specification of the same filename is ignored, the
 last filename before a commit is used.  The filename is used until a
 new filename is used (at commit points) and all keys are written to
 that file. If a new filename is given, this file is created (and
-overwrites an existing one).  For GnuPG versions prior to 2.1, both
-control statements must be given. For GnuPG 2.1 and later
-@samp{%secring} is a no-op.
+overwrites an existing one).
+
+See the previous subsection ``Ephemeral home directories'' for a more
+robust way to contain side-effects.
+
+@item %secring @var{filename}
+This option is a no-op for GnuPG 2.1 and later.
+
+See the previous subsection ``Ephemeral home directories''.
 
 @item %ask-passphrase
 @itemx %no-ask-passphrase
@@ -3449,7 +3970,7 @@ can be handled.  See also @samp{Key-Type} above.
 
 @item Subkey-Length: @var{nbits}
 Length of the secondary key (subkey) in bits.  The default is returned
-by running the command @samp{@gpgname --gpgconf-list}".
+by running the command @samp{@gpgname --gpgconf-list}.
 
 @item Subkey-Usage: @var{usage-list}
 Key usage lists for a subkey; similar to @samp{Key-Usage}.
@@ -3509,8 +4030,9 @@ generation to associate a key parameter block with a status line.
 @end table
 
 @noindent
-Here is an example on how to create a key:
+Here is an example on how to create a key in an ephemeral home directory:
 @smallexample
+$ export GNUPGHOME="$(mktemp -d)"
 $ cat >foo <<EOF
      %echo Generating a basic OpenPGP key
      Key-Type: DSA
@@ -3522,23 +4044,21 @@ $ cat >foo <<EOF
      Name-Email: joe@@foo.bar
      Expire-Date: 0
      Passphrase: abc
-     %pubring foo.pub
-     %secring foo.sec
      # Do a commit here, so that we can later print "done" :-)
      %commit
      %echo done
 EOF
-$ @gpgname --batch --gen-key foo
+$ @gpgname --batch --generate-key foo
  [...]
-$ @gpgname --no-default-keyring --secret-keyring ./foo.sec \
-       --keyring ./foo.pub --list-secret-keys
-/home/wk/work/gnupg-stable/scratch/foo.sec
-------------------------------------------
-sec  1024D/915A878D 2000-03-09 Joe Tester (with stupid passphrase) <joe@@foo.bar>
-ssb  1024g/8F70E2C0 2000-03-09
+$ @gpgname --list-secret-keys
+/tmp/tmp.0NQxB74PEf/pubring.kbx
+-------------------------------
+sec   dsa1024 2016-12-16 [SCA]
+      768E895903FC1C44045C8CB95EEBDB71E9E849D0
+uid           [ultimate] Joe Tester (with stupid passphrase) <joe@@foo.bar>
+ssb   elg1024 2016-12-16 [E]
 @end smallexample
 
-
 @noindent
 If you want to create a key with the default algorithms you would use
 these parameters:
@@ -3551,8 +4071,6 @@ these parameters:
      Name-Email: joe@@foo.bar
      Expire-Date: 0
      Passphrase: abc
-     %pubring foo.pub
-     %secring foo.sec
      # Do a commit here, so that we can later print "done" :-)
      %commit
      %echo done