gpg: Emit FAILURE stati now in almost all cases.
[gnupg.git] / doc / gpg.texi
index 9dceed9..d840b85 100644 (file)
@@ -196,11 +196,13 @@ Make a detached signature.
 @item --encrypt
 @itemx -e
 @opindex encrypt
-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).
+Encrypt data to one or more public keys. 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).  @option{--recipient}
+and related options specify which public keys to use for encryption.
 
 @item --symmetric
 @itemx -c
@@ -309,43 +311,36 @@ 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
-using @option{--list-keys} with @option{--with-sig-list}.
-
-For each signature listed, there are several flags in between the "sig"
-tag and keyid. These flags give additional information about each
-signature. From left to right, they are the numbers 1-3 for certificate
-check level (see @option{--ask-cert-level}), "L" for a local or
-non-exportable signature (see @option{--lsign-key}), "R" for a
-nonRevocable signature (see the @option{--edit-key} command "nrsign"),
-"P" for a signature that contains a policy URL (see
-@option{--cert-policy-url}), "N" for a signature that contains a
-notation (see @option{--cert-notation}), "X" for an eXpired signature
-(see @option{--ask-cert-expire}), and the numbers 1-9 or "T" for 10 and
-above to indicate trust signature levels (see the @option{--edit-key}
-command "tsign").
-
 @item --check-signatures
 @opindex check-signatures
 @itemx --check-sigs
 @opindex check-sigs
-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
+Same as @option{--list-keys}, but the key signatures are verified and
+listed too.  Note that for performance reasons the revocation status
+of a signing key is not shown.  This command has the same effect as
 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-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).
+The status of the verification is indicated by a flag directly
+following the "sig" tag (and thus before the flags described below.  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).  Signatures
+where the public key is not availabale are not listed; to see their
+keyids the command @option{--list-sigs} can be used.
+
+For each signature listed, there are several flags in between the
+signature status flag and keyid.  These flags give additional
+information about each key signature.  From left to right, they are
+the numbers 1-3 for certificate check level (see
+@option{--ask-cert-level}), "L" for a local or non-exportable
+signature (see @option{--lsign-key}), "R" for a nonRevocable signature
+(see the @option{--edit-key} command "nrsign"), "P" for a signature
+that contains a policy URL (see @option{--cert-policy-url}), "N" for a
+signature that contains a notation (see @option{--cert-notation}), "X"
+for an eXpired signature (see @option{--ask-cert-expire}), and the
+numbers 1-9 or "T" for 10 and above to indicate trust signature levels
+(see the @option{--edit-key} command "tsign").
+
 
 @item --locate-keys
 @opindex locate-keys
@@ -360,7 +355,7 @@ 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-signatures} or @option{--check-signatures}.  If this
+combined with @option{--check-signatures}.  If this
 command is given twice, the fingerprints of all secondary keys are
 listed too.  This command also forces pretty printing of fingerprints
 if the keyid format has been set to "none".
@@ -392,13 +387,13 @@ Present a menu to allow changing the PIN of a smartcard. This
 functionality is also available as the subcommand "passwd" with the
 @option{--edit-card} command.
 
-@item --delete-keys @code{name}
+@item --delete-keys @var{name}
 @opindex delete-keys
 Remove key from the public keyring. In batch mode either @option{--yes} is
 required or the key must be specified by fingerprint. This is a
 safeguard against accidental deletion of multiple keys.
 
-@item --delete-secret-keys @code{name}
+@item --delete-secret-keys @var{name}
 @opindex delete-secret-keys
 Remove key from the secret keyring. In batch mode the key must be
 specified by fingerprint.  The option @option{--yes} can be used to
@@ -408,7 +403,7 @@ secret key (as controlled by gpg-agent) is only used for the given
 OpenPGP public key.
 
 
-@item --delete-secret-and-public-key @code{name}
+@item --delete-secret-and-public-key @var{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.
@@ -423,13 +418,14 @@ those of the given name. The exported keys are written to STDOUT or to the
 file given with option @option{--output}.  Use together with
 @option{--armor} to mail those keys.
 
-@item --send-keys @code{key IDs}
+@item --send-keys @var{keyIDs}
 @opindex send-keys
 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{@gpgname} does nothing.
+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 @var{keyIDs}
+are given, @command{@gpgname} does nothing.
 
 @item --export-secret-keys
 @itemx --export-secret-subkeys
@@ -478,11 +474,11 @@ 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 --receive-keys @code{key IDs}
+@item --receive-keys @var{keyIDs}
 @opindex receive-keys
-@itemx --recv-keys @code{key IDs}
+@itemx --recv-keys @var{keyIDs}
 @opindex recv-keys
-Import the keys with the given key IDs from a keyserver. Option
+Import the keys with the given @var{keyIDs} from a keyserver. Option
 @option{--keyserver} must be used to give the name of this keyserver.
 
 @item --refresh-keys
@@ -494,9 +490,9 @@ the entire keyring. Option @option{--keyserver} must be used to give the
 name of the keyserver for all keys that do not have preferred keyservers
 set (see @option{--keyserver-options honor-keyserver-url}).
 
-@item --search-keys @code{names}
+@item --search-keys @var{names}
 @opindex search-keys
-Search the keyserver for the given names. Multiple names given here will
+Search the keyserver for the given @var{names}. Multiple names given here will
 be joined together to create the search string for the keyserver.
 Option @option{--keyserver} must be used to give the name of this
 keyserver.  Keyservers that support different search methods allow using
@@ -504,9 +500,9 @@ the syntax specified in "How to specify a user ID" below. Note that
 different keyserver types support different search methods. Currently
 only LDAP supports them all.
 
-@item --fetch-keys @code{URIs}
+@item --fetch-keys @var{URIs}
 @opindex fetch-keys
-Retrieve keys located at the specified URIs. Note that different
+Retrieve keys located at the specified @var{URIs}. Note that different
 installations of GnuPG may support different protocols (HTTP, FTP,
 LDAP, etc.).  When using HTTPS the system provided root certificates
 are used by this command.
@@ -572,14 +568,14 @@ When updating from version 1.0.6 to 1.0.7 this command should be used
 to create signature caches in the keyring. It might be handy in other
 situations too.
 
-@item --print-md @code{algo}
+@item --print-md @var{algo}
 @itemx --print-mds
 @opindex print-md
-Print message digest of algorithm ALGO for all given files or STDIN.
-With the second form (or a deprecated "*" as algo) digests for all
+Print message digest of algorithm @var{algo} for all given files or STDIN.
+With the second form (or a deprecated "*" for @var{algo}) digests for all
 available algorithms are printed.
 
-@item --gen-random @code{0|1|2} @code{count}
+@item --gen-random @var{0|1|2} @var{count}
 @opindex gen-random
 Emit @var{count} random bytes of the given quality level 0, 1 or 2. If
 @var{count} is not given or zero, an endless sequence of random bytes
@@ -587,9 +583,10 @@ will be emitted.  If used with @option{--armor} the output will be
 base64 encoded.  PLEASE, don't use this command unless you know what
 you are doing; it may remove precious entropy from the system!
 
-@item --gen-prime @code{mode}  @code{bits}
+@item --gen-prime @var{mode}  @var{bits}
 @opindex gen-prime
-Use the source, Luke :-). The output format is still subject to change.
+Use the source, Luke :-). The output format is subject to change
+with ant release.
 
 
 @item --enarmor
@@ -599,11 +596,11 @@ Use the source, Luke :-). The output format is still subject to change.
 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-policy @code{auto|good|unknown|bad|ask}  @code{key...}
+@item --tofu-policy @{auto|good|unknown|bad|ask@}  @var{keys}
 @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
+@var{keys}.  For more information about the meaning of the policies,
+@pxref{trust-model-tofu}.  The @var{keys} may be specified either by their
 fingerprint (preferred) or their keyid.
 
 @c @item --server
@@ -624,8 +621,10 @@ This section explains the main commands for key management.
 
 @table @gnupgtabopt
 
-@item --quick-generate-key @code{user-id} [@code{algo} [@code{usage} [@code{expire}]]]
+@item --quick-generate-key @var{user-id} [@var{algo} [@var{usage} [@var{expire}]]]
+@itemx --quick-gen-key
 @opindex quick-generate-key
+@opindex quick-gen-key
 This is a simple command to generate a standard key with one user id.
 In contrast to @option{--generate-key} the key is generated directly
 without the need to answer a bunch of prompts.  Unless the option
@@ -637,16 +636,16 @@ answer to a ``Continue?'' style confirmation prompt is required.  In
 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
+If @var{algo} or @var{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}.
+``future-default'' for @var{algo} and ``default'' for @var{usage}.
 For a description of these optional arguments see the command
-@code{--quick-add-key}.  The @code{usage} accepts also the value
+@code{--quick-add-key}.  The @var{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
+The @var{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
@@ -663,20 +662,26 @@ 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 --quick-set-expire @code{fpr} @code{expire}
+@item --quick-set-expire @var{fpr} @var{expire} [*|@var{subfprs}]
 @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.
+With two arguments given, directly set the expiration time of the
+primary key identified by @var{fpr} to @var{expire}.  To remove the
+expiration time @code{0} can be used.  With three arguments and the
+third given as an asterisk, the expiration time of all non-revoked and
+not yet expired subkeys are set to @var{expire}.  With more than two
+arguments and a list of fingerprints given for @var{subfprs}, all
+non-revoked subkeys matching these fingerprints are set to
+@var{expire}.
 
 
-@item --quick-add-key @code{fpr} [@code{algo} [@code{usage} [@code{expire}]]]
+@item --quick-add-key @var{fpr} [@var{algo} [@var{usage} [@var{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
+@var{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
+@var{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'',
@@ -686,9 +691,9 @@ 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
+Depending on the given @var{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}
+signing and encryption and such a subkey is desired, a @var{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
@@ -696,7 +701,7 @@ 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
+The @var{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
@@ -726,9 +731,9 @@ mode. See the manual section ``Unattended key generation'' on how
 to use this.
 
 
-@item --generate-revocation @code{name}
+@item --generate-revocation @var{name}
 @opindex generate-revocation
-@itemx --gen-revoke @code{name}
+@itemx --gen-revoke @var{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.
@@ -743,9 +748,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 --generate-designated-revocation @code{name}
+@item --generate-designated-revocation @var{name}
 @opindex generate-designated-revocation
-@itemx --desig-revoke @code{name}
+@itemx --desig-revoke @var{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
@@ -761,14 +766,14 @@ line.
 @c ******** Begin Edit-key Options **********
 @table @asis
 
-  @item uid @code{n}
+  @item uid @var{n}
   @opindex keyedit:uid
-  Toggle selection of user ID or photographic user ID with index @code{n}.
+  Toggle selection of user ID or photographic user ID with index @var{n}.
   Use @code{*} to select all and @code{0} to deselect all.
 
-  @item key @code{n}
+  @item key @var{n}
   @opindex keyedit:key
-  Toggle selection of subkey with index @code{n} or key ID @code{n}.
+  Toggle selection of subkey with index @var{n} or key ID @var{n}.
   Use @code{*} to select all and @code{0} to deselect all.
 
   @item sign
@@ -893,9 +898,9 @@ signing.
   not already included in the preference list. In addition, the
   preferred keyserver and signature notations (if any) are shown.
 
-  @item setpref @code{string}
+  @item setpref @var{string}
   @opindex keyedit:setpref
-  Set the list of user ID preferences to @code{string} for all (or just
+  Set the list of user ID preferences to @var{string} for all (or just
   the selected) user IDs. Calling setpref with no arguments sets the
   preference list to the default (either built-in or set via
   @option{--default-preference-list}), and calling setpref with "none"
@@ -935,9 +940,9 @@ signing.
   from the card - if the card gets broken your secret key will be lost
   unless you have a backup somewhere.
 
-  @item bkuptocard @code{file}
+  @item bkuptocard @var{file}
   @opindex keyedit:bkuptocard
-  Restore the given file to a card. This command may be used to restore a
+  Restore the given @var{file} to a card. This command may be used to restore a
   backup key (as generated during card initialization) to a new card. In
   almost all cases this will be the encryption key. You should use this
   command only with the corresponding public key and make sure that the
@@ -1057,25 +1062,25 @@ the values:
 @end table
 @c ******** End Edit-key Options **********
 
-@item --sign-key @code{name}
+@item --sign-key @var{name}
 @opindex sign-key
 Signs a public key with your secret key. This is a shortcut version of
 the subcommand "sign" from @option{--edit}.
 
-@item --lsign-key @code{name}
+@item --lsign-key @var{name}
 @opindex lsign-key
 Signs a public key with your secret key but marks it as
 non-exportable. This is a shortcut version of the subcommand "lsign"
 from @option{--edit-key}.
 
-@item --quick-sign-key @code{fpr} [@code{names}]
-@itemx --quick-lsign-key @code{fpr} [@code{names}]
+@item --quick-sign-key @var{fpr} [@var{names}]
+@itemx --quick-lsign-key @var{fpr} [@var{names}]
 @opindex quick-sign-key
 @opindex quick-lsign-key
 Directly sign a key from the passphrase without any further user
-interaction.  The @code{fpr} must be the verified primary fingerprint
-of a key in the local keyring. If no @code{names} are given, all
-useful user ids are signed; with given [@code{names}] only useful user
+interaction.  The @var{fpr} must be the verified primary fingerprint
+of a key in the local keyring. If no @var{names} are given, all
+useful user ids are signed; with given [@var{names}] only useful user
 ids matching one of theses names are signed.  By default, or if a name
 is prefixed with a '*', a case insensitive substring match is used.
 If a name is prefixed with a '=' a case sensitive exact match is done.
@@ -1121,7 +1126,9 @@ all affected self-signatures is set one second ahead.
 @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
-@code{passwd} of the edit key menu.
+@code{passwd} of the edit key menu.  When using together with the
+option @option{--dry-run} this will not actually change the passphrase
+but check that the current passphrase is correct.
 
 @end table
 
@@ -1242,11 +1249,11 @@ Assume "yes" on most questions.
 Assume "no" on most questions.
 
 
-@item --list-options @code{parameters}
+@item --list-options @var{parameters}
 @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-signatures}, @option{--list-public-keys},
+@option{--check-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:
@@ -1255,7 +1262,7 @@ give the opposite meaning.  The options are:
 
   @item show-photos
   @opindex list-options:show-photos
-  Causes @option{--list-keys}, @option{--list-signatures},
+  Causes @option{--list-keys}, @option{--check-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}:
@@ -1271,7 +1278,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-signatures} or @option{--check-signatures}
+  Show policy URLs in the  @option{--check-signatures}
   listings.  Defaults to no.
 
   @item show-notations
@@ -1281,11 +1288,11 @@ 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-signatures} or @option{--check-signatures} listings. Defaults to no.
+  @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-signatures} or
+  Show any preferred keyserver URL in the
   @option{--check-signatures} listings. Defaults to no.
 
   @item show-uid-validity
@@ -1308,7 +1315,7 @@ 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-signatures} or
+  Show signature expiration dates (if any) during
   @option{--check-signatures} listings. Defaults to no.
 
   @item show-sig-subpackets
@@ -1317,11 +1324,11 @@ 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-signatures} or @option{--check-signatures}.
+  @option{--check-signatures}.
 
 @end table
 
-@item --verify-options @code{parameters}
+@item --verify-options @var{parameters}
 @opindex verify-options
 This is a space or comma delimited string that gives options used when
 verifying signatures. Options can be prepended with a `no-' to give
@@ -1402,7 +1409,7 @@ Enable hash truncation for all DSA keys even for old DSA Keys up to
 that older versions of GnuPG also required this flag to allow the
 generation of DSA larger than 1024 bit.
 
-@item --photo-viewer @code{string}
+@item --photo-viewer @var{string}
 @opindex photo-viewer
 This is the command line that should be run to view a photo ID. "%i"
 will be expanded to a filename containing the photo. "%I" does the
@@ -1420,7 +1427,7 @@ The default viewer is "xloadimage -fork -quiet -title 'KeyID 0x%k'
 STDIN". Note that if your image viewer program is not secure, then
 executing it from GnuPG does not make it secure.
 
-@item --exec-path @code{string}
+@item --exec-path @var{string}
 @opindex exec-path
 @efindex PATH
 Sets a list of directories to search for photo viewers and keyserver
@@ -1430,9 +1437,9 @@ variable.
 Note, that on W32 system this value is ignored when searching for
 keyserver helpers.
 
-@item --keyring @code{file}
+@item --keyring @var{file}
 @opindex keyring
-Add @code{file} to the current list of keyrings. If @code{file} begins
+Add @var{file} to the current list of keyrings. If @var{file} begins
 with a tilde and a slash, these are replaced by the $HOME directory. If
 the filename does not contain a slash, it is assumed to be in the GnuPG
 home directory ("~/.gnupg" if @option{--homedir} or $GNUPGHOME is not
@@ -1446,20 +1453,20 @@ If the option @option{--no-keyring} has been used no keyrings will
 be used at all.
 
 
-@item --secret-keyring @code{file}
+@item --secret-keyring @var{file}
 @opindex secret-keyring
 This is an obsolete option and ignored.  All secret keys are stored in
 the @file{private-keys-v1.d} directory below the GnuPG home directory.
 
-@item --primary-keyring @code{file}
+@item --primary-keyring @var{file}
 @opindex primary-keyring
-Designate @code{file} as the primary public keyring. This means that
+Designate @var{file} as the primary public keyring. This means that
 newly imported keys (via @option{--import} or keyserver
 @option{--recv-from}) will go to this keyring.
 
-@item --trustdb-name @code{file}
+@item --trustdb-name @var{file}
 @opindex trustdb-name
-Use @code{file} instead of the default trustdb. If @code{file} begins
+Use @var{file} instead of the default trustdb. If @var{file} begins
 with a tilde and a slash, these are replaced by the $HOME directory. If
 the filename does not contain a slash, it is assumed to be in the GnuPG
 home directory (@file{~/.gnupg} if @option{--homedir} or $GNUPGHOME is
@@ -1468,7 +1475,7 @@ not used).
 @include opt-homedir.texi
 
 
-@item --display-charset @code{name}
+@item --display-charset @var{name}
 @opindex display-charset
 Set the name of the native character set. This is used to convert
 some informational strings like user IDs to the proper UTF-8 encoding.
@@ -1476,7 +1483,7 @@ Note that this has nothing to do with the character set of data to be
 encrypted or signed; GnuPG does not recode user-supplied data. If
 this option is not used, the default character set is determined from
 the current locale. A verbosity level of 3 shows the chosen set.
-Valid values for @code{name} are:
+Valid values for @var{name} are:
 
 @table @asis
 
@@ -1513,9 +1520,9 @@ encoded in the character set as specified by
 arguments. Both options may be used multiple times.
 
 @anchor{gpg-option --options}
-@item --options @code{file}
+@item --options @var{file}
 @opindex options
-Read options from @code{file} and do not try to read them from the
+Read options from @var{file} and do not try to read them from the
 default options file in the homedir (see @option{--homedir}). This
 option is ignored if used in an options file.
 
@@ -1525,18 +1532,18 @@ Shortcut for @option{--options /dev/null}. This option is detected
 before an attempt to open an option file.  Using this option will also
 prevent the creation of a @file{~/.gnupg} homedir.
 
-@item -z @code{n}
-@itemx --compress-level @code{n}
-@itemx --bzip2-compress-level @code{n}
+@item -z @var{n}
+@itemx --compress-level @var{n}
+@itemx --bzip2-compress-level @var{n}
 @opindex compress-level
 @opindex bzip2-compress-level
-Set compression level to @code{n} for the ZIP and ZLIB compression
+Set compression level to @var{n} for the ZIP and ZLIB compression
 algorithms. The default is to use the default compression level of zlib
 (normally 6). @option{--bzip2-compress-level} sets the compression level
 for the BZIP2 compression algorithm (defaulting to 6 as well). This is a
 different option from @option{--compress-level} since BZIP2 uses a
 significant amount of memory for each additional compression level.
-@option{-z} sets both. A value of 0 for @code{n} disables compression.
+@option{-z} sets both. A value of 0 for @var{n} disables compression.
 
 @item --bzip2-decompress-lowmem
 @opindex bzip2-decompress-lowmem
@@ -1567,7 +1574,7 @@ information on the specific levels and how they are
 used. @option{--no-ask-cert-level} disables this option. This option
 defaults to no.
 
-@item --default-cert-level @code{n}
+@item --default-cert-level @var{n}
 @opindex default-cert-level
 The default to use for the check level when signing a key.
 
@@ -1604,7 +1611,7 @@ certification level below this as invalid. Defaults to 2, which
 disregards level 1 signatures. Note that level 0 "no particular
 claim" signatures are always accepted.
 
-@item --trusted-key @code{long key ID}
+@item --trusted-key @var{long key ID}
 @opindex trusted-key
 Assume that the specified key (which must be given
 as a full 8 byte key ID) is as trustworthy as one of
@@ -1613,7 +1620,7 @@ don't want to keep your secret keys (or one of them)
 online but still want to be able to check the validity of a given
 recipient's or signator's key.
 
-@item --trust-model @code{pgp|classic|tofu|tofu+pgp|direct|always|auto}
+@item --trust-model @{pgp|classic|tofu|tofu+pgp|direct|always|auto@}
 @opindex trust-model
 Set what trust model GnuPG should follow. The models are:
 
@@ -1633,10 +1640,14 @@ Set what trust model GnuPG should follow. The models are:
   @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
-  with a user id with the same email address, a warning is displayed
-  indicating that there is a conflict and that the key might be a
-  forgery and an attempt at a man-in-the-middle attack.
+  time a key is seen, it is memorized.  If later another key with a
+  user id with the same email address is seen, both keys are marked as
+  suspect.  In that case, the next time either is used, a warning is
+  displayed describing the conflict, why it might have occurred
+  (either the user generated a new key and failed to cross sign the
+  old and new keys, the key is forgery, or a man-in-the-middle attack
+  is being attempted), and the user is prompted to manually confirm
+  the validity of the key in question.
 
   Because a potential attacker is able to control the email address
   and thereby circumvent the conflict detection algorithm by using an
@@ -1714,14 +1725,18 @@ Set what trust model GnuPG should follow. The models are:
   exists.
 @end table
 
-@item --auto-key-locate @code{parameters}
+@item --auto-key-locate @var{mechanisms}
 @itemx --no-auto-key-locate
 @opindex auto-key-locate
 GnuPG can automatically locate and retrieve keys as needed using this
-option. This happens when encrypting to an email address (in the
-"user@@example.com" form), and there are no user@@example.com keys on
-the local keyring.  This option takes any number of the following
-mechanisms, in the order they are to be tried:
+option.  This happens when encrypting to an email address (in the
+"user@@example.com" form), and there are no "user@@example.com" keys
+on the local keyring.  This option takes any number of the mechanisms
+listed below, in the order they are to be tried.  Instead of listing
+the mechanisms as comma delimited arguments, the option may also be
+given several times to add more mechanism.  The option
+@option{--no-auto-key-locate} or the mechanism "clear" resets the
+list.  The default is "local,wkd".
 
 @table @asis
 
@@ -1737,7 +1752,6 @@ mechanisms, in the order they are to be tried:
 
   @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
@@ -1770,13 +1784,14 @@ mechanisms, in the order they are to be tried:
 
 @end table
 
+
 @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.
+These options enable or disable the automatic retrieving of keys from
+a keyserver when verifying signatures made by keys that are not on the
+local keyring.  The default is @option{--no-auto-key-retrieve}.
 
 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
@@ -1790,7 +1805,7 @@ 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}
+@item --keyid-format @{none|short|0xshort|long|0xlong@}
 @opindex keyid-format
 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
@@ -1799,15 +1814,15 @@ 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}
+@item --keyserver @var{name}
 @opindex keyserver
 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
+Use @var{name} as your keyserver. This is the server that
 @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:
+keys on. The format of the @var{name} is a URI:
 `scheme:[//]keyservername[:port]' The scheme is the type of keyserver:
 "hkp" for the HTTP (or compatible) keyservers, "ldap" for the LDAP
 keyservers, or "mailto" for the Graff email keyserver. Note that your
@@ -1822,7 +1837,7 @@ need to send keys to more than one server. The keyserver
 @code{hkp://keys.gnupg.net} uses round robin DNS to give a different
 keyserver each time you use it.
 
-@item --keyserver-options @code{name=value}
+@item --keyserver-options @{@var{name}=@var{value}@}
 @opindex keyserver-options
 This is a space or comma delimited string that gives options for the
 keyserver. Options can be prefixed with a `no-' to give the opposite
@@ -1878,7 +1893,7 @@ are available for all keyserver types, some common options are:
   timeout applies separately to each key retrieval, and not to the
   @option{--receive-keys} command as a whole. Defaults to 30 seconds.
 
-  @item http-proxy=@code{value}
+  @item http-proxy=@var{value}
   This option is deprecated.
   Set the proxy to use for HTTP and HKP keyservers.
   This overrides any proxy defined in @file{dirmngr.conf}.
@@ -1901,22 +1916,22 @@ are available for all keyserver types, some common options are:
 
 @end table
 
-@item --completes-needed @code{n}
+@item --completes-needed @var{n}
 @opindex compliant-needed
 Number of completely trusted users to introduce a new
 key signer (defaults to 1).
 
-@item --marginals-needed @code{n}
+@item --marginals-needed @var{n}
 @opindex marginals-needed
 Number of marginally trusted users to introduce a new
 key signer (defaults to 3)
 
-@item --tofu-default-policy @code{auto|good|unknown|bad|ask}
+@item --tofu-default-policy @{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, @pxref{trust-model-tofu}.
 
-@item --max-cert-depth @code{n}
+@item --max-cert-depth @var{n}
 @opindex max-cert-depth
 Maximum depth of a certification chain (default is 5).
 
@@ -1960,6 +1975,9 @@ file name.
 Specify a dirmngr program to be used for keyserver access.  The
 default value is @file{@value{BINDIR}/dirmngr}.
 
+@item --disable-dirmngr
+Entirely disable the use of the Dirmngr.
+
 @item --no-autostart
 @opindex no-autostart
 Do not start the gpg-agent or the dirmngr if it has not yet been
@@ -1998,9 +2016,9 @@ connected pipe too early. Using this option along with
 @option{--enable-progress-filter} may be used to cleanly cancel long
 running gpg operations.
 
-@item --limit-card-insert-tries @code{n}
+@item --limit-card-insert-tries @var{n}
 @opindex limit-card-insert-tries
-With @code{n} greater than 0 the number of prompts asking to insert a
+With @var{n} greater than 0 the number of prompts asking to insert a
 smartcard gets limited to N-1. Thus with a value of 1 gpg won't at
 all ask to insert a card if none has been inserted at startup. This
 option is useful in the configuration file in case an application does
@@ -2110,7 +2128,7 @@ 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}
+@item --encrypt-to @var{name}
 @opindex encrypt-to
 Same as @option{--recipient} but this one is intended for use in the
 options file and may be used with your own user-id as an
@@ -2119,7 +2137,7 @@ 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 --hidden-encrypt-to @code{name}
+@item --hidden-encrypt-to @var{name}
 @opindex hidden-encrypt-to
 Same as @option{--hidden-recipient} but this one is intended for use in the
 options file and may be used with your own user-id as a hidden
@@ -2133,7 +2151,7 @@ keys can be used.
 Disable the use of all @option{--encrypt-to} and
 @option{--hidden-encrypt-to} keys.
 
-@item --group @code{name=value}
+@item --group @{@var{name}=@var{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
@@ -2149,7 +2167,7 @@ from the command line, it may be necessary to quote the argument to
 this option to prevent the shell from treating it as multiple
 arguments.
 
-@item --ungroup @code{name}
+@item --ungroup @var{name}
 @opindex ungroup
 Remove a given entry from the @option{--group} list.
 
@@ -2197,8 +2215,8 @@ handy in case where an encrypted message contains a bogus key ID.
 @opindex skip-hidden-recipients
 @opindex no-skip-hidden-recipients
 During decryption skip all anonymous recipients.  This option helps in
-the case that people use the hidden recipients feature to hide there
-own encrypt-to key from others.  If oneself has many secret keys this
+the case that people use the hidden recipients feature to hide their
+own encrypt-to key from others.  If one has many secret keys this
 may lead to a major annoyance because all keys are tried in turn to
 decrypt something which was not really intended for it.  The drawback
 of this option is that it is currently not possible to decrypt a
@@ -2231,7 +2249,7 @@ Assume the input data is not in ASCII armored format.
 Write output to @var{file}.  To write to stdout use @code{-} as the
 filename.
 
-@item --max-output @code{n}
+@item --max-output @var{n}
 @opindex max-output
 This option sets a limit on the number of bytes that will be generated
 when processing a file. Since OpenPGP supports various levels of
@@ -2250,7 +2268,16 @@ 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}
+@item --key-origin @var{string}[,@var{url}]
+@opindex key-origin
+gpg can track the origin of a key. Certain origins are implicitly
+known (e.g. keyserver, web key directory) and set.  For a standard
+import the origin of the keys imported can be set with this option.
+To list the possible values use "help" for @var{string}.  Some origins
+can store an optional @var{url} argument.  That URL can appended to
+@var{string} after a comma.
+
+@item --import-options @var{parameters}
 @opindex import-options
 This is a space or comma delimited string that gives options for
 importing keys. Options can be prepended with a `no-' to give the
@@ -2281,9 +2308,12 @@ opposite meaning. The options are:
   keyserver @option{--receive-keys}.
 
   @item import-show
+  @itemx show-only
   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.
+  at keys; the option @option{show-only} is a shortcut for this
+  combination.  Note that suffixes like '#' for "sec" and "sbb" lines
+  may or may not be printed.
 
   @item import-export
   Run the entire import code but instead of storing the key to the
@@ -2321,8 +2351,8 @@ opposite meaning. The options are:
   contradicting options are overridden.
 @end table
 
-@item --import-filter @code{@var{name}=@var{expr}}
-@itemx --export-filter @code{@var{name}=@var{expr}}
+@item --import-filter @{@var{name}=@var{expr}@}
+@itemx --export-filter @{@var{name}=@var{expr}@}
 @opindex import-filter
 @opindex export-filter
 These options define an import/export filter which are applied to the
@@ -2408,7 +2438,7 @@ The available properties are:
 
 @end table
 
-@item --export-options @code{parameters}
+@item --export-options @var{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
@@ -2422,9 +2452,10 @@ opposite meaning.  The options are:
   Defaults to no.
 
   @item export-attributes
-  Include attribute user IDs (photo IDs) while exporting. This is
-  useful to export keys if they are going to be used by an OpenPGP
-  program that does not accept attribute user IDs. Defaults to yes.
+  Include attribute user IDs (photo IDs) while exporting. Not
+  including attribute user IDs is useful to export keys that are going
+  to be used by an OpenPGP program that does not accept attribute user
+  IDs.  Defaults to yes.
 
   @item export-sensitive-revkeys
   Include designated revoker information that was marked as
@@ -2520,6 +2551,13 @@ Print the ICAO spelling of the fingerprint in addition to the hex digits.
 Include the keygrip in the key listings.  In @code{--with-colons} mode
 this is implicitly enable for secret keys.
 
+@item --with-key-origin
+@opindex with-key-origin
+Include the locally held information on the origin and last update of
+a key in a key listing.  In @code{--with-colons} mode this is always
+printed.  This data is currently experimental and shall not be
+considered part of the stable API.
+
 @item --with-wkd-hash
 @opindex with-wkd-hash
 Print a Web Key Directory identifier along with each user ID in key
@@ -2579,9 +2617,9 @@ 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}
+@item --personal-cipher-preferences @var{string}
 @opindex personal-cipher-preferences
-Set the list of personal cipher preferences to @code{string}.  Use
+Set the list of personal cipher preferences to @var{string}.  Use
 @command{@gpgname --version} to get a list of available algorithms,
 and use @code{none} to set no preference at all.  This allows the user
 to safely override the algorithm chosen by the recipient key
@@ -2589,9 +2627,9 @@ preferences, as GPG will only select an algorithm that is usable by
 all recipients.  The most highly ranked cipher in this list is also
 used for the @option{--symmetric} encryption command.
 
-@item --personal-digest-preferences @code{string}
+@item --personal-digest-preferences @var{string}
 @opindex personal-digest-preferences
-Set the list of personal digest preferences to @code{string}.  Use
+Set the list of personal digest preferences to @var{string}.  Use
 @command{@gpgname --version} to get a list of available algorithms,
 and use @code{none} to set no preference at all.  This allows the user
 to safely override the algorithm chosen by the recipient key
@@ -2600,9 +2638,9 @@ all recipients.  The most highly ranked digest algorithm in this list
 is also used when signing without encryption
 (e.g. @option{--clear-sign} or @option{--sign}).
 
-@item --personal-compress-preferences @code{string}
+@item --personal-compress-preferences @var{string}
 @opindex personal-compress-preferences
-Set the list of personal compression preferences to @code{string}.
+Set the list of personal compression preferences to @var{string}.
 Use @command{@gpgname --version} to get a list of available
 algorithms, and use @code{none} to set no preference at all.  This
 allows the user to safely override the algorithm chosen by the
@@ -2611,26 +2649,26 @@ is usable by all recipients.  The most highly ranked compression
 algorithm in this list is also used when there are no recipient keys
 to consider (e.g. @option{--symmetric}).
 
-@item --s2k-cipher-algo @code{name}
+@item --s2k-cipher-algo @var{name}
 @opindex s2k-cipher-algo
-Use @code{name} as the cipher algorithm for symmetric encryption with
+Use @var{name} as the cipher algorithm for symmetric encryption with
 a passphrase if @option{--personal-cipher-preferences} and
 @option{--cipher-algo} are not given.  The default is @value{GPGSYMENCALGO}.
 
-@item --s2k-digest-algo @code{name}
+@item --s2k-digest-algo @var{name}
 @opindex s2k-digest-algo
-Use @code{name} as the digest algorithm used to mangle the passphrases
+Use @var{name} as the digest algorithm used to mangle the passphrases
 for symmetric encryption.  The default is SHA-1.
 
-@item --s2k-mode @code{n}
+@item --s2k-mode @var{n}
 @opindex s2k-mode
 Selects how passphrases for symmetric encryption are mangled. If
-@code{n} is 0 a plain passphrase (which is in general not recommended)
+@var{n} is 0 a plain passphrase (which is in general not recommended)
 will be used, a 1 adds a salt (which should not be used) to the
 passphrase and a 3 (the default) iterates the whole process a number
 of times (see @option{--s2k-count}).
 
-@item --s2k-count @code{n}
+@item --s2k-count @var{n}
 @opindex s2k-count
 Specify how many times the passphrases mangling for symmetric
 encryption is repeated.  This value may range between 1024 and
@@ -2811,42 +2849,42 @@ Enable certain PROGRESS status outputs. This option allows frontends
 to display a progress indicator while gpg is processing larger files.
 There is a slight performance overhead using it.
 
-@item --status-fd @code{n}
+@item --status-fd @var{n}
 @opindex status-fd
-Write special status strings to the file descriptor @code{n}.
+Write special status strings to the file descriptor @var{n}.
 See the file DETAILS in the documentation for a listing of them.
 
-@item --status-file @code{file}
+@item --status-file @var{file}
 @opindex status-file
 Same as @option{--status-fd}, except the status data is written to file
-@code{file}.
+@var{file}.
 
-@item --logger-fd @code{n}
+@item --logger-fd @var{n}
 @opindex logger-fd
-Write log output to file descriptor @code{n} and not to STDERR.
+Write log output to file descriptor @var{n} and not to STDERR.
 
-@item --log-file @code{file}
-@itemx --logger-file @code{file}
+@item --log-file @var{file}
+@itemx --logger-file @var{file}
 @opindex log-file
 Same as @option{--logger-fd}, except the logger data is written to
-file @code{file}.  Use @file{socket://} to log to socket.
+file @var{file}.  Use @file{socket://} to log to s socket.
 
-@item --attribute-fd @code{n}
+@item --attribute-fd @var{n}
 @opindex attribute-fd
-Write attribute subpackets to the file descriptor @code{n}. This is most
+Write attribute subpackets to the file descriptor @var{n}. This is most
 useful for use with @option{--status-fd}, since the status messages are
 needed to separate out the various subpackets from the stream delivered
 to the file descriptor.
 
-@item --attribute-file @code{file}
+@item --attribute-file @var{file}
 @opindex attribute-file
 Same as @option{--attribute-fd}, except the attribute data is written to
-file @code{file}.
+file @var{file}.
 
-@item --comment @code{string}
+@item --comment @var{string}
 @itemx --no-comments
 @opindex comment
-Use @code{string} as a comment string in cleartext signatures and ASCII
+Use @var{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
@@ -2865,21 +2903,21 @@ 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}
-@itemx --cert-notation @code{name=value}
-@itemx -N, --set-notation @code{name=value}
+@item --sig-notation @{@var{name}=@var{value}@}
+@itemx --cert-notation @{@var{name}=@var{value}@}
+@itemx -N, --set-notation @{@var{name}=@var{value}@}
 @opindex sig-notation
 @opindex cert-notation
 @opindex set-notation
 Put the name value pair into the signature as notation data.
-@code{name} must consist only of printable characters or spaces, and
+@var{name} must consist only of printable characters or spaces, and
 must contain a '@@' character in the form keyname@@domain.example.com
 (substituting the appropriate keyname and domain name, of course).  This
 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
+check. @var{value} may be any printable string; it will be encoded in
 UTF-8, so you should check that your @option{--display-charset} is set
-correctly. If you prefix @code{name} with an exclamation mark (!), the
+correctly. If you prefix @var{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
 signatures. @option{--cert-notation} sets a notation for key signatures
@@ -2897,13 +2935,13 @@ smartcard, and "%%" results in a single "%". %k, %K, and %f are only
 meaningful when making a key signature (certification), and %c is only
 meaningful when using the OpenPGP smartcard.
 
-@item --sig-policy-url @code{string}
-@itemx --cert-policy-url @code{string}
-@itemx --set-policy-url @code{string}
+@item --sig-policy-url @var{string}
+@itemx --cert-policy-url @var{string}
+@itemx --set-policy-url @var{string}
 @opindex sig-policy-url
 @opindex cert-policy-url
 @opindex set-policy-url
-Use @code{string} as a Policy URL for signatures (rfc4880:5.2.3.20).  If
+Use @var{string} as a Policy URL for signatures (rfc4880:5.2.3.20).  If
 you prefix it with an exclamation mark (!), the policy URL packet will
 be flagged as critical. @option{--sig-policy-url} sets a policy url for
 data signatures. @option{--cert-policy-url} sets a policy url for key
@@ -2911,19 +2949,19 @@ signatures (certifications). @option{--set-policy-url} sets both.
 
 The same %-expandos used for notation data are available here as well.
 
-@item --sig-keyserver-url @code{string}
+@item --sig-keyserver-url @var{string}
 @opindex sig-keyserver-url
-Use @code{string} as a preferred keyserver URL for data signatures. If
+Use @var{string} as a preferred keyserver URL for data signatures. If
 you prefix it with an exclamation mark (!), the keyserver URL packet
 will be flagged as critical.
 
 The same %-expandos used for notation data are available here as well.
 
-@item --set-filename @code{string}
+@item --set-filename @var{string}
 @opindex set-filename
-Use @code{string} as the filename which is stored inside messages.
+Use @var{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 @code{string}
+file being encrypted.  Using the empty string for @var{string}
 effectively removes the filename from the output.
 
 @item --for-your-eyes-only
@@ -2941,9 +2979,9 @@ to display the message. This option overrides @option{--set-filename}.
 Try to create a file with a name as embedded in the data. This can be
 a dangerous option as it enables overwriting files. Defaults to no.
 
-@item --cipher-algo @code{name}
+@item --cipher-algo @var{name}
 @opindex cipher-algo
-Use @code{name} as cipher algorithm. Running the program with the
+Use @var{name} as cipher algorithm. Running the program with the
 command @option{--version} yields a list of supported algorithms. If
 this is not used the cipher algorithm is selected from the preferences
 stored with the key. In general, you do not want to use this option as
@@ -2951,17 +2989,17 @@ it allows you to violate the OpenPGP standard.
 @option{--personal-cipher-preferences} is the safe way to accomplish the
 same thing.
 
-@item --digest-algo @code{name}
+@item --digest-algo @var{name}
 @opindex digest-algo
-Use @code{name} as the message digest algorithm. Running the program
+Use @var{name} as the message digest algorithm. Running the program
 with the command @option{--version} yields a list of supported algorithms. In
 general, you do not want to use this option as it allows you to
 violate the OpenPGP standard. @option{--personal-digest-preferences} is the
 safe way to accomplish the same thing.
 
-@item --compress-algo @code{name}
+@item --compress-algo @var{name}
 @opindex compress-algo
-Use compression algorithm @code{name}. "zlib" is RFC-1950 ZLIB
+Use compression algorithm @var{name}. "zlib" is RFC-1950 ZLIB
 compression. "zip" is RFC-1951 ZIP compression which is used by PGP.
 "bzip2" is a more modern compression scheme that can compress some
 things better than zip or zlib, but at the cost of more memory used
@@ -2982,24 +3020,24 @@ general, you do not want to use this option as it allows you to
 violate the OpenPGP standard. @option{--personal-compress-preferences} is the
 safe way to accomplish the same thing.
 
-@item --cert-digest-algo @code{name}
+@item --cert-digest-algo @var{name}
 @opindex cert-digest-algo
-Use @code{name} as the message digest algorithm used when signing a
+Use @var{name} as the message digest algorithm used when signing a
 key. Running the program with the command @option{--version} yields a
 list of supported algorithms. Be aware that if you choose an algorithm
 that GnuPG supports but other OpenPGP implementations do not, then some
 users will not be able to use the key signatures you make, or quite
 possibly your entire key.
 
-@item --disable-cipher-algo @code{name}
+@item --disable-cipher-algo @var{name}
 @opindex disable-cipher-algo
-Never allow the use of @code{name} as cipher algorithm.
+Never allow the use of @var{name} as cipher algorithm.
 The given name will not be checked so that a later loaded algorithm
 will still get disabled.
 
-@item --disable-pubkey-algo @code{name}
+@item --disable-pubkey-algo @var{name}
 @opindex disable-pubkey-algo
-Never allow the use of @code{name} as public key algorithm.
+Never allow the use of @var{name} as public key algorithm.
 The given name will not be checked so that a later loaded algorithm
 will still get disabled.
 
@@ -3035,44 +3073,49 @@ signatures to prevent the mail system from breaking the signature. Note
 that all other PGP versions do it this way too.  Enabled by
 default. @option{--no-escape-from-lines} disables this option.
 
-@item --passphrase-repeat @code{n}
+@item --passphrase-repeat @var{n}
 @opindex passphrase-repeat
 Specify how many times @command{@gpgname} will request a new
 passphrase be repeated.  This is useful for helping memorize a
 passphrase.  Defaults to 1 repetition.
 
-@item --passphrase-fd @code{n}
+@item --passphrase-fd @var{n}
 @opindex passphrase-fd
-Read the passphrase from file descriptor @code{n}. Only the first line
-will be read from file descriptor @code{n}. If you use 0 for @code{n},
+Read the passphrase from file descriptor @var{n}. Only the first line
+will be read from file descriptor @var{n}. If you use 0 for @var{n},
 the passphrase will be read from STDIN. This can only be used if only
 one passphrase is supplied.
 
-Note that this passphrase is only used if the option @option{--batch}
-has also been given.  This is different from GnuPG version 1.x.
+Note that since Version 2.0 this passphrase is only used if the
+option @option{--batch} has also been given. Since Version 2.1
+the @option{--pinentry-mode} also needs to be set to @code{loopback}.
 
-@item --passphrase-file @code{file}
+@item --passphrase-file @var{file}
 @opindex passphrase-file
-Read the passphrase from file @code{file}. Only the first line will
-be read from file @code{file}. This can only be used if only one
+Read the passphrase from file @var{file}. Only the first line will
+be read from file @var{file}. This can only be used if only one
 passphrase is supplied. Obviously, a passphrase stored in a file is
 of questionable security if other users can read this file. Don't use
 this option if you can avoid it.
-Note that this passphrase is only used if the option @option{--batch}
-has also been given.  This is different from GnuPG version 1.x.
 
-@item --passphrase @code{string}
+Note that since Version 2.0 this passphrase is only used if the
+option @option{--batch} has also been given. Since Version 2.1
+the @option{--pinentry-mode} also needs to be set to @code{loopback}.
+
+@item --passphrase @var{string}
 @opindex passphrase
-Use @code{string} as the passphrase. This can only be used if only one
+Use @var{string} as the passphrase. This can only be used if only one
 passphrase is supplied. Obviously, this is of very questionable
 security on a multi-user system. Don't use this option if you can
 avoid it.
-Note that this passphrase is only used if the option @option{--batch}
-has also been given.  This is different from GnuPG version 1.x.
 
-@item --pinentry-mode @code{mode}
+Note that since Version 2.0 this passphrase is only used if the
+option @option{--batch} has also been given. Since Version 2.1
+the @option{--pinentry-mode} also needs to be set to @code{loopback}.
+
+@item --pinentry-mode @var{mode}
 @opindex pinentry-mode
-Set the pinentry mode to @code{mode}.  Allowed values for @code{mode}
+Set the pinentry mode to @var{mode}.  Allowed values for @var{mode}
 are:
 @table @asis
   @item default
@@ -3088,7 +3131,16 @@ are:
   Pinentry the user is not prompted again if he enters a bad password.
 @end table
 
-@item --command-fd @code{n}
+@item --request-origin @var{origin}
+@opindex request-origin
+Tell gpg to assume that the operation ultimately originated at
+@var{origin}.  Depending on the origin certain restrictions are applied
+and the Pinentry may include an extra note on the origin.  Supported
+values for @var{origin} are: @code{local} which is the default,
+@code{remote} to indicate a remote origin or @code{browser} for an
+operation requested by a web browser.
+
+@item --command-fd @var{n}
 @opindex command-fd
 This is a replacement for the deprecated shared-memory IPC mode.
 If this option is enabled, user input on questions is not expected
@@ -3096,10 +3148,10 @@ from the TTY but from the given file descriptor. It should be used
 together with @option{--status-fd}. See the file doc/DETAILS in the source
 distribution for details on how to use it.
 
-@item --command-file @code{file}
+@item --command-file @var{file}
 @opindex command-file
 Same as @option{--command-fd}, except the commands are read out of file
-@code{file}
+@var{file}
 
 @item --allow-non-selfsigned-uid
 @itemx --no-allow-non-selfsigned-uid
@@ -3154,7 +3206,7 @@ allows the verification of signatures made with such weak algorithms.
 MD5 is the only digest algorithm considered weak by default.  See also
 @option{--weak-digest} to reject other digest algorithms.
 
-@item --weak-digest @code{name}
+@item --weak-digest @var{name}
 @opindex weak-digest
 Treat the specified digest algorithm as weak.  Signatures made over
 weak digests algorithms are normally rejected. This option can be
@@ -3186,6 +3238,16 @@ verification is not needed.
 Print key listings delimited by colons (like @option{--with-colons}) and
 print the public key data.
 
+@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 using @option{--list-keys} with
+@option{--with-sig-list}.  Note that in contrast to
+@option{--check-signatures} the key signatures are not verified.
+
+
 @item --fast-list-mode
 @opindex fast-list-mode
 Changes the output of the list commands to work faster; this is achieved
@@ -3219,12 +3281,12 @@ messaging system that the ciphertext transmitted corresponds to an
 inappropriate plaintext so they can take action against the offending
 user.
 
-@item --override-session-key @code{string}
-@itemx --override-session-key-fd @code{fd}
+@item --override-session-key @var{string}
+@itemx --override-session-key-fd @var{fd}
 @opindex override-session-key
-Don't use the public key but the session key @code{string} respective
+Don't use the public key but the session key @var{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
+@var{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
@@ -3303,15 +3365,15 @@ Experimental use only.
 Don't change the permissions of a secret keyring back to user
 read/write only. Use this option only if you really know what you are doing.
 
-@item --default-preference-list @code{string}
+@item --default-preference-list @var{string}
 @opindex default-preference-list
-Set the list of default preferences to @code{string}. This preference
+Set the list of default preferences to @var{string}. This preference
 list is used for new keys and becomes the default for "setpref" in the
 edit menu.
 
-@item --default-keyserver-url @code{name}
+@item --default-keyserver-url @var{name}
 @opindex default-keyserver-url
-Set the default keyserver URL to @code{name}. This keyserver will be
+Set the default keyserver URL to @var{name}. This keyserver will be
 used as the keyserver URL when writing a new self-signature on a key,
 which includes key generation and changing preferences.
 
@@ -3730,6 +3792,19 @@ If you are going to verify detached signatures, make sure that the
 program knows about it; either give both filenames on the command line
 or use @samp{-} to specify STDIN.
 
+For scripted or other unattended use of @command{gpg} make sure to use
+the machine-parseable interface and not the default interface which is
+intended for direct use by humans.  The machine-parseable interface
+provides a stable and well documented API independent of the locale or
+future changes of @command{gpg}.  To enable this interface use the
+options @option{--with-colons} and @option{--status-fd}.  For certain
+operations the option @option{--command-fd} may come handy too.  See
+this man page and the file @file{DETAILS} for the specification of the
+interface.  Note that the GnuPG ``info'' pages as well as the PDF
+version of the GnuPG manual features a chapter on unattended use of
+GnuPG.  As an alternative the library @command{GPGME} can be used as a
+high-level abstraction on top of that interface.
+
 @mansect interoperability
 @chapheading INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS
 
@@ -3781,7 +3856,7 @@ may be recoverable from it later.
 
 Before you report a bug you should first search the mailing list
 archives for similar problems and second check whether such a bug has
-already been reported to our bug tracker at https://dev.gnupg.org .
+already been reported to our bug tracker at @url{https://bugs.gnupg.org}.
 
 @c *******************************************
 @c ***************              **************