* gpg.sgml: Document --list-options (show-photos, show-policy-url,
[gnupg.git] / doc / gpg.sgml
index 99c0421..cd5de63 100644 (file)
@@ -1,5 +1,6 @@
 <!-- gpg.sgml - the man page for GnuPG
-    Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
+    Copyright (C) 1998, 1999, 2000, 2001, 2002,
+                  2003 Free Software Foundation, Inc.
 
     This file is part of GnuPG.
 
 </refnamediv>
 <refsynopsisdiv>
   <synopsis>
-<command>gpg</>
+<command>gpg</command>
  <optional>--homedir <parameter/name/</optional>
  <optional>--options <parameter/file/</optional>
  <optional><parameter/options/</optional>
- <parameter>command</>
+ <parameter>command</parameter>
  <optional><parameter/args/</optional>
   </synopsis>
 </refsynopsisdiv>
@@ -124,10 +125,12 @@ Encrypt data. This option may be combined with --sign.
 <varlistentry>
 <term>-c, --symmetric</term>
 <listitem><para>
-Encrypt with symmetric cipher only.
-This command asks for a passphrase.
+Encrypt with a symmetric cipher using a passphrase.  The default
+symmetric cipher used is CAST5, but may be chosen with the
+--cipher-algo option.
 </para></listitem></varlistentry>
 
+
 <varlistentry>
 <term>--store</term>
 <listitem><para>
@@ -213,16 +216,23 @@ B<-k> [I<username>] [I<keyring>]
 <term>--list-keys &OptParmNames;</term>
 <term>--list-public-keys &OptParmNames;</term>
 <listitem><para>
-List all keys from the public keyrings, or just the
-ones given on the command line.
+List all keys from the public keyrings, or just the ones given on the
+command line.
+</para><para>
+Avoid using the output of this command in scripts or other programs as
+it is likely to change as GnuPG changes.  See --with-colons for a
+machine-parseable key listing command that is appropriate for use in
+scripts and other programs.
 </para></listitem></varlistentry>
 
 
 <varlistentry>
 <term>--list-secret-keys &OptParmNames;</term>
 <listitem><para>
-List all keys from the secret keyrings, or just the
-ones given on the command line.
+List all keys from the secret keyrings, or just the ones given on the
+command line.  A '#' after the letters 'sec' means that the secret key
+is not usable (for example, if it was created via
+--export-secret-subkeys).
 </para></listitem></varlistentry>
 
 
@@ -230,6 +240,18 @@ ones given on the command line.
 <term>--list-sigs &OptParmNames;</term>
 <listitem><para>
 Same as --list-keys, but the signatures are listed too.
+</para><para>
+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 --default-cert-check-level), "L" for a
+local or non-exportable signature (see --lsign-key), "R" for a
+nonRevocable signature (see --nrsign-key), "P" for a signature that
+contains a policy URL (see --cert-policy-url), "N" for a signature
+that contains a notation (see --cert-notation), "X" for an eXpired
+signature (see --ask-cert-expire), and the numbers 1-9 or "T" for 10
+and above to indicate trust signature levels (see the --edit-key
+command "tsign").
 </para></listitem></varlistentry>
 
 
@@ -309,12 +331,20 @@ Combines the functionality of nrsign and lsign to make a signature
 that is both non-revocable and
 non-exportable.</para></listitem></varlistentry>
     <varlistentry>
+    <term>tsign</term>
+    <listitem><para>
+Make a trust signature.  This is a signature that combines the notions
+of certification (like a regular signature), and trust (like the
+"trust" command).  It is generally only useful in distinct communities
+or groups.
+</para></listitem></varlistentry>
+    <varlistentry>
     <term>revsig</term>
     <listitem><para>
-Revoke a signature.  GnuPG asks for every
-signature which has been done by one of
-the secret keys, whether a revocation
-certificate should be generated.</para></listitem></varlistentry>
+Revoke a signature.  For every signature which has been generated by
+one of the secret keys, GnuPG asks whether a revocation certificate
+should be generated.
+</para></listitem></varlistentry>
     <varlistentry>
     <term>trust</term>
     <listitem><para>
@@ -324,8 +354,8 @@ trust-db immediately and no save is required.</para></listitem></varlistentry>
     <term>disable</term>
     <term>enable</term>
     <listitem><para>
-Disable or enable an entire key. A disabled key can normally not be used
-for encryption.</para></listitem></varlistentry>
+Disable or enable an entire key. A disabled key can not normally be
+used for encryption.</para></listitem></varlistentry>
     <varlistentry>
     <term>adduid</term>
     <listitem><para>
@@ -333,12 +363,17 @@ Create an alternate user id.</para></listitem></varlistentry>
     <varlistentry>
     <term>addphoto</term>
     <listitem><para>
-Create a photographic user id.</para></listitem></varlistentry>
+Create a photographic user id.  This will prompt for a JPEG file that
+will be embedded into the user ID.</para></listitem></varlistentry>
     <varlistentry>
     <term>deluid</term>
     <listitem><para>
 Delete a user id.</para></listitem></varlistentry>
     <varlistentry>
+    <term>revuid</term>
+    <listitem><para>
+Revoke a user id.</para></listitem></varlistentry>
+    <varlistentry>
     <term>addkey</term>
     <listitem><para>
 Add a subkey to this key.</para></listitem></varlistentry>
@@ -349,7 +384,10 @@ Remove a subkey.</para></listitem></varlistentry>
     <varlistentry>
     <term>addrevoker</term>
     <listitem><para>
-Add a designated revoker.</para></listitem></varlistentry>
+Add a designated revoker.  This takes one optional argument:
+"sensitive".  If a designated revoker is marked as sensitive, it will
+not be exported by default (see
+export-options).</para></listitem></varlistentry>
     <varlistentry>
     <term>revkey</term>
     <listitem><para>
@@ -357,10 +395,10 @@ Revoke a subkey.</para></listitem></varlistentry>
     <varlistentry>
     <term>expire</term>
     <listitem><para>
-Change the key expiration time.  If a key is
-selected, the time of this key will be changed.
-With no selection the key expiration of the
-primary key is changed.</para></listitem></varlistentry>
+Change the key expiration time.  If a subkey is selected, the
+expiration time of this subkey will be changed.  With no selection,
+the key expiration of the primary key is changed.
+</para></listitem></varlistentry>
     <varlistentry>
     <term>passwd</term>
     <listitem><para>
@@ -397,27 +435,37 @@ id.</para></listitem></varlistentry>
     <varlistentry>
     <term>pref</term>
     <listitem><para>
-List preferences.</para></listitem></varlistentry>
+List preferences from the selected user ID.  This shows the actual
+preferences, without including any implied preferences.
+</para></listitem></varlistentry>
     <varlistentry>
     <term>showpref</term>
     <listitem><para>
-More verbose preferences listing.</para></listitem></varlistentry>
+More verbose preferences listing for the selected user ID.  This shows
+the preferences in effect by including the implied preferences of
+3DES (cipher), SHA-1 (digest), and Uncompressed (compression) if they
+are not already included in the preference list.
+</para></listitem></varlistentry>
     <varlistentry>
     <term>setpref &ParmString;</term>
     <listitem><para>
-Set the list of user ID preferences to &ParmString;, this should be 
-a string similar to the one printed by "pref".  Using an empty string
-will set the default preference string, using "none" will set the 
-preferences to nil.  Only available algorithms are allowed.  This
-command just initializes an internal list and does not change anything
-unless another command which changes the self-signatures is used.
+Set the list of user ID preferences to &ParmString;, this should be a
+string similar to the one printed by "pref".  Using an empty string
+will set the default preference string, using "none" will set the
+preferences to nil.  Use "gpg --version" to get a list of available
+algorithms.  This command just initializes an internal list and does
+not change anything unless another command (such as "updpref") which
+changes the self-signatures is used.
 </para></listitem></varlistentry>
     <varlistentry>
     <term>updpref</term>
     <listitem><para>
 Change the preferences of all user IDs (or just of the selected ones
 to the current list of preferences.  The timestamp of all affected
-self-signatures fill be advanced by one second.
+self-signatures will be advanced by one second.  Note that while you
+can change the preferences on an attribute user ID (aka "photo ID"),
+GnuPG does not select keys via attribute user IDs so these preferences
+will not be used by GnuPG.
 </para></listitem></varlistentry>
     <varlistentry>
     <term>toggle</term>
@@ -477,19 +525,23 @@ This is a shortcut version of the subcommand "nrsign" from --edit.
 <varlistentry>
 <term>--delete-key &ParmName;</term>
 <listitem><para>
-Remove key from the public keyring
+Remove key from the public keyring.  In batch mode either --yes is
+required or the key must be specified by fingerprint.  This is a
+safeguard against accidental deletion of multiple keys.
 </para></listitem></varlistentry>
 
 <varlistentry>
 <term>--delete-secret-key  &ParmName;</term>
 <listitem><para>
-Remove key from the secret and public keyring
+Remove key from the secret and public keyring. In batch mode the key
+must be specified by fingerprint.
 </para></listitem></varlistentry>
 
 <varlistentry>
 <term>--delete-secret-and-public-key  &ParmName;</term>
 <listitem><para>
-Same as --delete-key, but if a secret key exists, it will be removed first.
+Same as --delete-key, but if a secret key exists, it will be removed 
+first. In batch mode the key must be specified by fingerprint.
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -503,7 +555,7 @@ a subkey or a signature, use the --edit command.
 <term>--desig-revoke</term>
 <listitem><para>
 Generate a designated revocation certificate for a key.  This allows a
-user (with the permission of the keyholder) to revoke someone elses
+user (with the permission of the keyholder) to revoke someone else's
 key.
 </para></listitem></varlistentry>
 
@@ -576,6 +628,15 @@ Import the keys with the given key IDs from a keyserver. Option
 </para></listitem></varlistentry>
 
 <varlistentry>
+<term>--refresh-keys &ParmKeyIDs;</term>
+<listitem><para>
+Request updates from a keyserver for keys that already exist on the
+local keyring.  This is useful for updating a key with the latest
+signatures, user IDs, etc.  Option --keyserver must be used to give
+the name of this keyserver.
+</para></listitem></varlistentry>
+
+<varlistentry>
 <term>--search-keys &OptParmNames;</term>
 <listitem><para>
 Search the keyserver for the given names.  Multiple names given here
@@ -586,37 +647,38 @@ Option --keyserver must be used to give the name of this keyserver.
 <varlistentry>
 <term>--update-trustdb</term>
 <listitem><para>
-Do trust DB maintenance.  This command goes over all keys and builds
-the Web-of-Trust. This is an interactive command because it may has to
-ask for the "ownertrust" values of keys.  The user has to give an
-estimation in how far she trusts the owner of the displayed key to
-correctly certify (sign) other keys.  It does only ask for that value
-if it has not yet been assigned to a key.  Using the edit menu, that
-value can be changed at any time later.
+Do trust database maintenance.  This command iterates over all keys
+and builds the Web-of-Trust. This is an interactive command because it
+may have to ask for the "ownertrust" values for keys.  The user has to
+give an estimation of how far she trusts the owner of the displayed
+key to correctly certify (sign) other keys.  GnuPG only asks for the
+ownertrust value if it has not yet been assigned to a key.  Using the
+--edit-key menu, the assigned value can be changed at any time.
 </para></listitem></varlistentry>
 
 <varlistentry>
 <term>--check-trustdb</term>
 <listitem><para>
-Do trust DB maintenance without user interaction.  Form time to time
-the trust database must be updated so that expired keys and resulting
-changes in the Web-of-Trust can be tracked.  GnuPG tries to figure
-when this is required and then does it implicitly; this command can be
-used to force such a check.  The processing is identically to that of
---update-trustdb but it skips keys with a not yet defined "ownertrust".
+Do trust database maintenance without user interaction.  From time to
+time the trust database must be updated so that expired keys or
+signatures and the resulting changes in the Web-of-Trust can be
+tracked.  Normally, GnuPG will calculate when this is required and do
+it automatically unless --no-auto-check-trustdb is set.  This command
+can be used to force a trust database check at any time.  The
+processing is identical to that of --update-trustdb but it skips keys
+with a not yet defined "ownertrust".
 </para>
 <para>
 For use with cron jobs, this command can be used together with --batch
-in which case the check is only done when it is due.  To force a run
-even in batch mode add the option --yes.
+in which case the trust database check is done only if a check is
+needed.  To force a run even in batch mode add the option --yes.
 </para></listitem></varlistentry>
 
 
 <varlistentry>
-<term>--export-ownertrust &OptParmFile;</term>
+<term>--export-ownertrust</term>
 <listitem><para>
-Store the ownertrust values into
-&ParmFile; (or stdin if not given).  This is useful for backup
+Send the ownertrust values to stdout.  This is useful for backup
 purposes as these values are the only ones which can't be re-created
 from a corrupted trust DB.
 </para></listitem></varlistentry>
@@ -629,6 +691,13 @@ in &ParmFiles; (or stdin if not given); existing
 values will be overwritten.
 </para></listitem></varlistentry>
 
+<varlistentry>
+<term>--rebuild-keydb-caches</term>
+<listitem><para>
+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.
+</para></listitem></varlistentry>
 
 <varlistentry>
 <term>--print-md <parameter>algo</parameter> &OptParmFiles;</term>
@@ -677,23 +746,24 @@ Print warranty information.
 <varlistentry>
 <term>-h, --help</term>
 <listitem><para>
-Print usage information.  This is a really long list even though it doesn't list
-all options.
+Print usage information.  This is a really long list even though it
+doesn't list all options.  For every option, consult this manual.
 </para></listitem></varlistentry>
 
-
-
 </variablelist>
 </refsect1>
 
 <refsect1>
 <title>OPTIONS</title>
 <para>
-Long options can be put in an options file (default "~/.gnupg/options").
-Do not write the 2 dashes, but simply the name of the option and any
-required arguments. Lines with a hash as the first non-white-space
-character are ignored. Commands may be put in this file too, but that
-does not make sense.
+Long options can be put in an options file (default
+"~/.gnupg/gpg.conf").  Short option names will not work - for example,
+"armor" is a valid option for the options file, while "a" is not.  Do
+not write the 2 dashes, but simply the name of the option and any
+required arguments.  Lines with a hash ('#') as the first
+non-white-space character are ignored.  Commands may be put in this
+file too, but that is not generally useful as the command will execute
+automatically with every execution of gpg.
 </para>
 <para>
 <command/gpg/ recognizes these options:
@@ -715,6 +785,18 @@ Create ASCII armored output.
 Write output to &ParmFile;.
 </para></listitem></varlistentry>
 
+<varlistentry>
+<term>--mangle-dos-filenames</term>
+<term>--no-mangle-dos-filenames</term>
+<listitem><para>
+The Windows version of GnuPG replaces the extension of an output
+filename to avoid problems with filenames containing more than one
+dot.  This is not necessary for newer Windows versions and so
+--no-mangle-dos-filenames can be used to switch this feature off and
+have GnuPG append the new extension.  This option has no effect on
+non-Windows platforms.
+</para></listitem></varlistentry>
+
 
 <varlistentry>
 <term>-u, --local-user &ParmName;</term>
@@ -738,8 +820,20 @@ found in the secret keyring.
 <term>-r, --recipient &ParmName;</term>
 <term></term>
 <listitem><para>
-Encrypt for user id &ParmName;. If this option is not
-specified, GnuPG asks for the user-id unless --default-recipient is given
+Encrypt for user id &ParmName;. If this option or --hidden-recipient
+is not specified, GnuPG asks for the user-id unless
+--default-recipient is given.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>-R, --hidden-recipient &ParmName;</term>
+<term></term>
+<listitem><para>
+Encrypt for user id &ParmName;, but hide the keyid of the key.  This
+option hides the receiver of the message and is a countermeasure
+against traffic analysis.  If this option or --recipient is not
+specified, GnuPG asks for the user-id unless --default-recipient is
+given.
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -776,11 +870,21 @@ No trust checking is performed for these user ids and
 even disabled keys can be used.
 </para></listitem></varlistentry>
 
+<varlistentry>
+<term>--hidden-encrypt-to &ParmName;</term>
+<listitem><para>
+Same as --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
+"encrypt-to-self".  These keys are only used when there are other
+recipients given either by use of --recipient or by the asked user id.
+No trust checking is performed for these user ids and even disabled
+keys can be used.
+</para></listitem></varlistentry>
 
 <varlistentry>
 <term>--no-encrypt-to</term>
 <listitem><para>
-Disable the use of all --encrypt-to keys.
+Disable the use of all --encrypt-to and --hidden-encrypt-to keys.
 </para></listitem></varlistentry>
 
 
@@ -810,13 +914,13 @@ compression level of zlib (normally 6).
 
 <varlistentry>
 <term>-t, --textmode</term>
+<term>--no-textmode</term>
 <listitem><para>
-Use canonical text mode.  If -t (but not
---textmode) is used together with armoring
-and signing, this enables clearsigned messages.
-This kludge is needed for PGP compatibility;
-normally you would use --sign or --clearsign
-to selected the type of the signature.
+Use canonical text mode.  --no-textmode disables this option.  If -t
+(but not --textmode) is used together with armoring and signing, this
+enables clearsigned messages.  This kludge is needed for command-line
+compatibility with command-line versions of PGP; normally you would
+use --sign or --clearsign to select the type of the signature.
 </para></listitem></varlistentry>
 
 
@@ -836,11 +940,13 @@ Prompt before overwriting any files.
 
 <varlistentry>
 <term>--batch</term>
+<term>--no-batch</term>
 <listitem><para>
-Use batch mode.  Never ask, do not allow interactive
-commands.
+Use batch mode.  Never ask, do not allow interactive commands.
+--no-batch disables this option.
 </para></listitem></varlistentry>
 
+
 <varlistentry>
 <term>--no-tty</term>
 <listitem><para>
@@ -851,14 +957,6 @@ warnings to the TTY if --batch is used.
 
 
 <varlistentry>
-<term>--no-batch</term>
-<listitem><para>
-Disable batch mode.  This may be of use if --batch
-is enabled from an options file.
-</para></listitem></varlistentry>
-
-
-<varlistentry>
 <term>--yes</term>
 <listitem><para>
 Assume "yes" on most questions.
@@ -917,13 +1015,36 @@ recipient's or signator's key.
 </para></listitem></varlistentry>
 
 <varlistentry>
+<term>--trust-model <parameter>pgp|classic|always</parameter></term>
+<listitem><para>
+
+Set what trust model GnuPG should follow.  The models are:
+
+<variablelist>
+
+<varlistentry><term>pgp</term><listitem><para>
+This is the web-of-trust combined with trust signatures as used in PGP
+5.x and later.  This is the default trust model.
+</para></listitem></varlistentry>
+
+<varlistentry><term>classic</term><listitem><para>
+This is the standard web-of-trust as used in PGP 2.x and earlier.
+</para></listitem></varlistentry>
+
+<varlistentry><term>always</term><listitem><para>
+Skip key validation and assume that used keys are always fully
+trusted.  You won't use this unless you have installed some external
+validation scheme.  This option also suppresses the "[uncertain]" tag
+printed with signature checks when there is no evidence that the user
+ID is bound to the key.
+</para></listitem></varlistentry>
+
+</variablelist></para></listitem></varlistentry>
+
+<varlistentry>
 <term>--always-trust</term>
 <listitem><para>
-Skip key validation and assume that used keys are always fully trusted.
-You won't use this unless you have installed some external validation
-scheme.  This option also suppresses the "[uncertain]" tag printed
-with signature checks when there is no evidence that the user ID
-is bound to the key.
+Identical to `--trust-model always'
 </para></listitem></varlistentry>
 
 
@@ -937,7 +1058,8 @@ from, send keys to, and search for keys on.  The format of the
 the type of keyserver: "hkp" for the Horowitz (or compatible)
 keyservers, "ldap" for the NAI LDAP keyserver, or "mailto" for the
 Horowitz email keyserver.  Note that your particular installation of
-GnuPG may have other keyserver types available as well.
+GnuPG may have other keyserver types available as well.  Keyserver
+schemes are case-insensitive.
 </para><para>
 Most keyservers synchronize with each other, so there is generally no
 need to send keys to more than one server.  Using the command "host -l
@@ -952,25 +1074,35 @@ each time.
 <listitem><para>
 This is a space or comma delimited string that gives options for the
 keyserver.  Options can be prepended with a `no-' to give the opposite
-meaning.  While not all options are available for all keyserver types,
-some common options are:
+meaning.  Valid import-options or export-options may be used here as
+well to apply to importing (--recv-key) or exporting (--send-key) a
+key from a keyserver.  While not all options are available for all
+keyserver types, some common options are:
 <variablelist>
 
 <varlistentry>
 <term>include-revoked</term>
 <listitem><para>
-When receiving or searching for a key, include keys that are marked on
-the keyserver as revoked.  Note that this option is always set when
-using the NAI HKP keyserver, as this keyserver does not differentiate
-between revoked and unrevoked keys.
+When searching for a key with --search-keys, include keys that are
+marked on the keyserver as revoked.  Note that this option is always
+set when using the NAI HKP keyserver, as this keyserver does not
+differentiate between revoked and unrevoked keys.
 </para></listitem></varlistentry>
 
 <varlistentry>
 <term>include-disabled</term>
 <listitem><para>
-When receiving or searching for a key, include keys that are marked on
-the keyserver as disabled.  Note that this option is not used with HKP
-keyservers, as they do not support disabling keys.
+When searching for a key with --search-keys, include keys that are
+marked on the keyserver as disabled.  Note that this option is not
+used with HKP keyservers.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>include-subkeys</term>
+<listitem><para>
+When receiving a key, include subkeys as potential targets.  Note that
+this option is not used with HKP keyservers, as they do not support
+retrieving keys by subkey id.
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -1017,18 +1149,156 @@ keyring.
 </para></listitem></varlistentry>
 
 <varlistentry>
-<term>--show-photos</term>
+<term>--import-options <parameter>parameters</parameter></term>
+<listitem><para>
+This is a space or comma delimited string that gives options for
+importing keys.  Options can be prepended with a `no-' to give the
+opposite meaning.  The options are:
+<variablelist>
+
+<varlistentry>
+<term>allow-local-sigs</term>
+<listitem><para>
+Allow importing key signatures marked as "local".  This is not
+generally useful unless a shared keyring scheme is being used.
+Defaults to no.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>repair-pks-subkey-bug</term>
+<listitem><para>
+During import, attempt to repair the damage caused by the PKS
+keyserver bug (pre version 0.9.6) that mangles keys with multiple
+subkeys.  Note 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 --import and to
+yes for keyserver --recv-keys.
+</para></listitem></varlistentry>
+
+</variablelist>
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>--export-options <parameter>parameters</parameter></term>
+<listitem><para>
+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:
+<variablelist>
+
+<varlistentry>
+<term>include-non-rfc</term>
+<listitem><para>
+Include non-RFC compliant keys in the export.  Defaults to yes.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>include-local-sigs</term>
+<listitem><para>
+Allow exporting key signatures marked as "local".  This is not
+generally useful unless a shared keyring scheme is being used.
+Defaults to no.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>include-attributes</term>
+<listitem><para>
+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.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>include-sensitive-revkeys</term>
+<listitem><para>
+Include designated revoker information that was marked as
+"sensitive".  Defaults to no.
+</para></listitem></varlistentry>
+
+</variablelist>
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>--list-options <parameter>parameters</parameter></term>
+<listitem><para>
+This is a space or comma delimited string that gives options used when
+listing keys and signatures (that is, --list-keys, --list-sigs,
+--list-public-keys, and --list-secret-keys).  Options can be prepended
+with a `no-' to give the opposite meaning.  The options are:
+<variablelist>
+
+<varlistentry>
+<term>show-photos</term>
 <listitem><para>
 Causes --list-keys, --list-sigs, --list-public-keys, and
---list-secret-keys to also display the photo ID attached to a key, if
-any.
-See also --photo-viewer.
+--list-secret-keys to display any photo IDs attached to the key.
+Defaults to no.  See also --photo-viewer.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>show-policy-url</term>
+<listitem><para>
+Show policy URLs in the --list-sigs or --check-sigs listings.
+Defaults to no.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>show-notation</term>
+<listitem><para>
+Show signature notations in the --list-sigs or --check-sigs listings.
+Defaults to no.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>show-keyring</term>
+<listitem><para>
+Display the keyring name at the head of key listings to show which
+keyring a given key resides on.  Defaults to no.
 </para></listitem></varlistentry>
 
+</variablelist>
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>--verify-options <parameter>parameters</parameter></term>
+<listitem><para>
+This is a space or comma delimited string that gives options used when
+verifying signatures.  Options can be prepended with a `no-' to give
+the opposite meaning.  The options are:
+<variablelist>
+
 <varlistentry>
+<term>show-photos</term>
+<listitem><para>
+Display any photo IDs present on the key that issued the signature.
+Defaults to no.  See also --photo-viewer.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>show-policy-url</term>
+<listitem><para>
+Show policy URLs in the signature being verified.  Defaults to no.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>show-notation</term>
+<listitem><para>
+Show signature notations in the signature being verified.  Defaults to
+no.
+</para></listitem></varlistentry>
+
+</variablelist>
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>--show-photos</term>
 <term>--no-show-photos</term>
 <listitem><para>
-Resets the --show-photos flag.
+Causes --list-keys, --list-sigs, --list-public-keys,
+--list-secret-keys, and verifying a signature to also display the
+photo ID attached to the key, if any.  See also --photo-viewer.  These
+options are deprecated.  Use `--list-options [no-]show-photos' and/or
+`--verify-options [no-]show-photos' instead.
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -1044,27 +1314,35 @@ and "%%" for an actual percent sign.  If neither %i or %I are present,
 then the photo will be supplied to the viewer on standard input.
 </para><para>
 The default viewer is "xloadimage -fork -quiet -title 'KeyID 0x%k'
-stdin"
+stdin".  Note that if your image viewer program is not secure, then
+executing it from GnuPG does not make it secure.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>--exec-path &ParmString;</term>
+<listitem><para>
+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
+variable.
 </para></listitem></varlistentry>
 
 <varlistentry>
 <term>--show-keyring</term>
 <listitem><para>
-Causes --list-keys, --list-public-keys, and --list-secret-keys to
-display the name of the keyring a given key resides on. This is only
-useful when you're listing a specific key or set of keys. It has no
-effect when listing all keys.
+Display the keyring name at the head of key listings to show which
+keyring a given key resides on.  This option is deprecated: use
+`--list-options [no-]show-keyring' instead.
 </para></listitem></varlistentry>
 
 <varlistentry>
 <term>--keyring &ParmFile;</term>
 <listitem><para>
-Add &ParmFile to the list of keyrings.
-If &ParmFile 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
-home-directory ("~/.gnupg" if --homedir is not used).
-The filename may be prefixed with a scheme:</para>
+Add &ParmFile; to the list of keyrings.  If &ParmFile; 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 --homedir is not used).  The filename
+may be prefixed with a scheme:</para>
 <para>"gnupg-ring:" is the default one.</para>
 <para>It might make sense to use it together with --no-default-keyring.
 </para></listitem></varlistentry>
@@ -1076,6 +1354,25 @@ The filename may be prefixed with a scheme:</para>
 Same as --keyring but for the secret keyrings.
 </para></listitem></varlistentry>
 
+<varlistentry>
+<term>--primary-keyring &ParmFile;</term>
+<listitem><para>
+Designate &ParmFile; as the primary public keyring.  This means that
+newly imported keys (via --import or keyserver --recv-from) will go to
+this keyring.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>--trustdb-name &ParmFile;</term>
+<listitem><para>
+
+Use &ParmFile; instead of the default trustdb.  If &ParmFile; 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 --homedir is not used).
+
+</para></listitem></varlistentry>
+
 
 <varlistentry>
 <term>--homedir &ParmDir;</term>
@@ -1091,16 +1388,21 @@ also overrides the environment variable "GNUPGHOME".
 <term>--charset &ParmName;</term>
 <listitem><para>
 Set the name of the native character set.  This is used
-to convert some strings to proper UTF-8 encoding.
+to convert some strings to proper UTF-8 encoding. If this option is not used, the default character set is determined
+from the current locale.  A verbosity level of 3 shows the used one.
 Valid values for &ParmName; are:</para>
 <variablelist>
 <varlistentry>
-<term>iso-8859-1</term><listitem><para>This is the default Latin 1 set.</para></listitem>
+<term>iso-8859-1</term><listitem><para>This is the Latin 1 set.</para></listitem>
 </varlistentry>
 <varlistentry>
 <term>iso-8859-2</term><listitem><para>The Latin 2 set.</para></listitem>
 </varlistentry>
 <varlistentry>
+<term>iso-8859-15</term><listitem><para>This is currently an alias for
+the Latin 1 set.</para></listitem>
+</varlistentry>
+<varlistentry>
 <term>koi8-r</term><listitem><para>The usual Russian set (rfc1489).</para></listitem>
 </varlistentry>
 <varlistentry>
@@ -1146,9 +1448,10 @@ Using this option will also prevent the creation of a
 <varlistentry>
 <term>--load-extension &ParmName;</term>
 <listitem><para>
-Load an extension module. If &ParmName; does not
-contain a slash it is searched in "/usr/local/lib/gnupg"
-See the manual for more information about extensions.
+Load an extension module. If &ParmName; does not contain a slash it is
+searched for in the directory configured when GnuPG was built
+(generally "/usr/local/lib/gnupg").  Extensions are not generally
+useful anymore, and the use of this option is deprecated.
 </para></listitem></varlistentry>
 
 
@@ -1168,6 +1471,15 @@ be given in C syntax (e.g. 0x0042).
 
 
 <varlistentry>
+<term>--enable-progress-filter</term>
+<listitem><para>
+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.
+</para></listitem></varlistentry>
+
+
+<varlistentry>
 <term>--status-fd &ParmN;</term>
 <listitem><para>
 Write special status strings to the file descriptor &ParmN;.
@@ -1194,31 +1506,29 @@ delivered to the file descriptor.
 
 <varlistentry>
 <term>--sk-comments</term>
+<term>--no-sk-comments</term>
 <listitem><para>
 Include secret key comment packets when exporting secret keys.  This
 is a GnuPG extension to the OpenPGP standard, and is off by default.
 Please note that this has nothing to do with the comments in clear
-text signatures or armor headers.
+text signatures or armor headers.  --no-sk-comments disables this
+option.
 </para></listitem></varlistentry>
 
-<varlistentry>
-<term>--no-sk-comments</term>
-<listitem><para>
-Resets the --sk-comments option.
-</para></listitem></varlistentry>
 
 <varlistentry>
 <term>--no-comment</term>
 <listitem><para>
-See --sk-comments.  This option is deprecated and may be removed soon.
+See --no-sk-comments.  This option is deprecated and may be removed
+soon.
 </para></listitem></varlistentry>
 
 
 <varlistentry>
 <term>--comment &ParmString;</term>
 <listitem><para>
-Use &ParmString; as comment string in clear text signatures.
-The default is not do write a comment string.
+Use &ParmString; as the comment string in clear text signatures.  The
+default behavior is not to use a comment string.
 </para></listitem></varlistentry>
 
 
@@ -1233,89 +1543,99 @@ default comment string anymore.
 
 
 <varlistentry>
-<term>--no-version</term>
-<listitem><para>
-Omit the version string in clear text signatures.
-</para></listitem></varlistentry>
-
-
-<varlistentry>
 <term>--emit-version</term>
+<term>--no-emit-version</term>
 <listitem><para>
-Force to write the version string in clear text
-signatures.  Use this to overwrite a previous
---no-version from a config file.
+Force inclusion of the version string in ASCII armored output.
+--no-emit-version disables this option.
 </para></listitem></varlistentry>
 
 
 <varlistentry>
-<term>-N, --notation-data &ParmNameValue;</term>
+<term>--sig-notation &ParmNameValue;</term>
+<term>--cert-notation &ParmNameValue;</term>
+<term>-N, --set-notation &ParmNameValue;</term>
 <listitem><para>
 Put the name value pair into the signature as notation data.
-&ParmName; must consist only of alphanumeric characters, digits
-or the underscore; the first character must not be a digit.
-&ParmValue; may be any printable string; it will be encoded in UTF8,
-so you should check that your --charset is set correctly.
-If you prefix &ParmName; with an exclamation mark, the notation
-data will be flagged as critical (rfc2440:5.2.3.15).
-</para></listitem></varlistentry>
+&ParmName; must consist only of printable characters or spaces, and
+must contain a '@' character.  This is to help prevent pollution of
+the IETF reserved notation namespace.  The --expert flag overrides the
+'@' check.  &ParmValue; may be any printable string; it will be
+encoded in UTF8, so you should check that your --charset is set
+correctly.  If you prefix &ParmName; with an exclamation mark, the
+notation data will be flagged as critical (rfc2440:5.2.3.15).
+--sig-notation sets a notation for data signatures.  --cert-notation
+sets a notation for key signatures (certifications).  --set-notation
+sets both.
+</para>
 
-<varlistentry>
-<term>--show-notation</term>
-<listitem><para>
-Show key signature notations in the --list-sigs or --check-sigs
-listings.
-</para></listitem></varlistentry>
+<para>
+There are special codes that may be used in notation names.  "%k" will
+be expanded into the key ID of the key being signed, "%K" into the
+long key ID of the key being signed, "%f" into the fingerprint of the
+key being signed, "%s" into the key ID of the key making the
+signature, "%S" into the long key ID of the key making the signature,
+"%g" into the fingerprint of the key making the signature (which might
+be a subkey), "%p" into the fingerprint of the primary key of the key
+making the signature, and "%%" results in a single "%".  %k, %K, and
+%f are only meaningful when making a key signature (certification).
+</para>
+
+</listitem></varlistentry>
 
 <varlistentry>
+<term>--show-notation</term>
 <term>--no-show-notation</term>
 <listitem><para>
-Do not show key signature notations in the --list-sigs or --check-sigs
-listings.
+Show signature notations in the --list-sigs or --check-sigs listings
+as well as when verifying a signature with a notation in it.  These
+options are deprecated.  Use `--list-options [no-]show-notation'
+and/or `--verify-options [no-]show-notation' instead.
 </para></listitem></varlistentry>
 
+
 <varlistentry>
+<term>--sig-policy-url &ParmString;</term>
+<term>--cert-policy-url &ParmString;</term>
 <term>--set-policy-url &ParmString;</term>
 <listitem><para>
-Use &ParmString; as Policy URL for signatures (rfc2440:5.2.3.19).
-If you prefix it with an exclamation mark, the policy URL
-packet will be flagged as critical.
+Use &ParmString; as Policy URL for signatures (rfc2440:5.2.3.19).  If
+you prefix it with an exclamation mark, the policy URL packet will be
+flagged as critical.  --sig-policy-url sets a a policy url for data
+signatures.  --cert-policy-url sets a policy url for key signatures
+(certifications).  --set-policy-url sets both.
+</para><para>
+The same %-expandos used for notation data are available here as well.
 </para></listitem></varlistentry>
 
 <varlistentry>
 <term>--show-policy-url</term>
-<listitem><para>
-Show any policy URLs set in the --list-sigs or --check-sigs listings.
-</para></listitem></varlistentry>
-
-<varlistentry>
 <term>--no-show-policy-url</term>
 <listitem><para>
-Do not show any policy URLs set in the --list-sigs or --check-sigs
-listings.
+Show policy URLs in the --list-sigs or --check-sigs listings as well
+as when verifying a signature with a policy URL in it.  These options
+are deprecated.  Use `--list-options [no-]show-policy-url' and/or
+`--verify-options [no-]show-policy-url' instead.
 </para></listitem></varlistentry>
 
 <varlistentry>
 <term>--set-filename &ParmString;</term>
 <listitem><para>
-Use &ParmString; as the name of file which is stored in
-messages.
+Use &ParmString; as the filename which is stored inside messages.
+This overrides the default, which is to use the actual filename of the
+file being encrypted.
 </para></listitem></varlistentry>
 
 <varlistentry>
 <term>--for-your-eyes-only</term>
+<term>--no-for-your-eyes-only</term>
 <listitem><para>
 Set the `for your eyes only' flag in the message.  This causes GnuPG
 to refuse to save the file unless the --output option is given, and
 PGP to use the "secure viewer" with a Tempest-resistant font to
 display the message.  This option overrides --set-filename.
-</para></listitem></varlistentry
-
-<varlistentry>
-<term>--no-for-your-eyes-only</term>
-<listitem><para>
-Resets the --for-your-eyes-only flag.
-</para></listitem></varlistentry
+--no-for-your-eyes-only disables this option.
+</para></listitem></varlistentry>
 
 <varlistentry>
 <term>--use-embedded-filename</term>
@@ -1367,6 +1687,20 @@ with the command --version yields a list of supported algorithms.
 
 
 <varlistentry>
+<term>--compress-algo &ParmName;</term>
+<listitem><para>
+Use compression algorithm &ParmName;.  "zlib" is RFC1950 ZLIB
+compression.  "zip" is RFC-1951 ZIP compression which is used by PGP.
+"uncompressed" or "none" disables compression.  If this option is not
+used, the default behavior is to examine the recipient key preferences
+to see which algorithms the recipient supports.  If all else fails,
+ZIP is used for maximum compatibility.  Note, however, that ZLIB may
+give better compression results if that is more important, as the
+compression window size is not limited to 8k.
+</para></listitem></varlistentry>
+
+
+<varlistentry>
 <term>--cert-digest-algo &ParmName;</term>
 <listitem><para>
 Use &ParmName; as the message digest algorithm used when signing a
@@ -1383,29 +1717,27 @@ possibly your entire key.
 <listitem><para>
 Use &ParmName; as the cipher algorithm used to protect secret keys.
 The default cipher is CAST5.  This cipher is also used for
-conventional encryption if --cipher-algo is not given.
+conventional encryption if --personal-cipher-preferences and
+--cipher-algo is not given.
 </para></listitem></varlistentry>
 
 
 <varlistentry>
 <term>--s2k-digest-algo &ParmName;</term>
 <listitem><para>
-Use  &ParmName; as the digest algorithm used to mangle the
-passphrases.  The default algorithm is RIPE-MD-160.
-This digest algorithm is also used for conventional
-encryption if --digest-algo is not given.
+Use &ParmName; as the digest algorithm used to mangle the passphrases.
+The default algorithm is SHA-1.
 </para></listitem></varlistentry>
 
 
 <varlistentry>
 <term>--s2k-mode &ParmN;</term>
 <listitem><para>
-Selects how passphrases are mangled. If &ParmN; is 0
-a plain passphrase (which is not recommended) will be used,
-a 1 (default) adds a salt to the passphrase and
-a 3 iterates the whole process a couple of times.
-Unless --rfc1991 is used, this mode is also used
-for conventional encryption.
+Selects how passphrases are mangled. If &ParmN; is 0 a plain
+passphrase (which is not recommended) will be used, a 1 adds a salt to
+the passphrase and a 3 (the default) iterates the whole process a
+couple of times.  Unless --rfc1991 is used, this mode is also used for
+conventional encryption.
 </para></listitem></varlistentry>
 
 
@@ -1417,20 +1749,10 @@ method will be part of an enhanced OpenPGP specification but GnuPG
 already uses it as a countermeasure against certain attacks.  Old
 applications don't understand this new format, so this option may be
 used to switch back to the old behaviour.  Using this this option
-bears a security risk.
-</para></listitem></varlistentry>
-
-
-<varlistentry>
-<term>--compress-algo &ParmN;</term>
-<listitem><para>
-Use compression algorithm &ParmN;. Default is 2 which is RFC1950
-compression. You may use 1 to use the old zlib version (RFC1951) which
-is used by PGP. 0 disables compression. The default algorithm may give
-better results because the window size is not limited to 8K. If this
-is not used the OpenPGP behavior is used, i.e. the compression
-algorithm is selected from the preferences; note, that this can't be
-done if you do not encrypt the data.
+bears a security risk.  Note that using this option only takes effect
+when the secret key is encrypted - the simplest way to make this
+happen is to change the passphrase on the key (even changing it to the
+same value is acceptable).
 </para></listitem></varlistentry>
 
 
@@ -1474,28 +1796,29 @@ interaction, this performance penalty does not matter in most settings.
 
 <varlistentry>
 <term>--auto-check-trustdb</term>
+<term>--no-auto-check-trustdb</term>
 <listitem><para>
 If GnuPG feels that its information about the Web-of-Trust has to be
-updated, it automatically runs the --check-trustdb command 
-internally.  This may be a time consuming process.
+updated, it automatically runs the --check-trustdb command internally.
+This may be a time consuming process.  --no-auto-check-trustdb
+disables this option.
 </para></listitem></varlistentry>
 
 <varlistentry>
-<term>--no-auto-check-trustdb</term>
+<term>--throw-keyid</term>
 <listitem><para>
-Resets the --auto-check-trustdb option.
+Do not put the keyids into encrypted packets.  This option hides the
+receiver of the message and is a countermeasure against traffic
+analysis.  It may slow down the decryption process because all
+available secret keys are tried.
 </para></listitem></varlistentry>
 
 <varlistentry>
-<term>--throw-keyid</term>
+<term>--no-throw-keyid</term>
 <listitem><para>
-Do not put the keyid into encrypted packets.  This option
-hides the receiver of the message and is a countermeasure
-against traffic analysis.  It may slow down the decryption
-process because all available secret keys are tried.
+Resets the --throw-keyid option.
 </para></listitem></varlistentry>
 
-
 <varlistentry>
 <term>--not-dash-escaped</term>
 <listitem><para>
@@ -1511,12 +1834,13 @@ line tells GnuPG about this cleartext signature option.
 
 <varlistentry>
 <term>--escape-from-lines</term>
+<term>--no-escape-from-lines</term>
 <listitem><para>
-Because some mailers change lines starting with "From "
-to "&#60;From " it is good to handle such lines in a special
-way when creating cleartext signatures. All other PGP
-versions do it this way too. This option is not enabled
-by default because it would violate rfc2440.
+Because some mailers change lines starting with "From " to "&#62;From
+" it is good to handle such lines in a special way when creating
+cleartext signatures to prevent the mail system from breaking the
+signature.  Note that all other PGP versions do it this way too.
+Enabled by default.  --no-escape-from-lines disables this option.
 </para></listitem></varlistentry>
 
 
@@ -1542,24 +1866,55 @@ distribution for details on how to use it.
 
 <varlistentry>
 <term>--use-agent</term>
+<term>--no-use-agent</term>
 <listitem><para>
 Try to use the GnuPG-Agent. Please note that this agent is still under
 development.  With this option, GnuPG first tries to connect to the
-agent before it asks for a passphrase.
+agent before it asks for a passphrase.  --no-use-agent disables this
+option.
 </para></listitem></varlistentry>
 
 <varlistentry>
 <term>--gpg-agent-info</term>
 <listitem><para>
 Override the value of the environment variable
-<literal>GPG_AGENT_INFO</>.  This is only used when --use-agent has been given
+<literal>GPG_AGENT_INFO</literal>.  This is only used when --use-agent has been given
 </para></listitem></varlistentry>
 
+<varlistentry>
+<term>Compliance options</term>
+<listitem><para>
+These options control what GnuPG is compliant to.  Only one of these
+options may be active at a time.  Note that the default setting of
+this is nearly always the correct one.  See the INTEROPERABILITY WITH
+OTHER OPENPGP PROGRAMS section below before using one of these
+options.
+<variablelist>
+
+<varlistentry>
+<term>--gnupg</term>
+<listitem><para>
+Use standard GnuPG behavior.  This is essentially OpenPGP behavior
+(see --openpgp), but with some additional workarounds for common
+compatibility problems in different versions of PGP.  This is the
+default option, so it is not generally needed, but it may be useful to
+override a different compliance option in the gpg.conf file.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>--openpgp</term>
+<listitem><para>
+Reset all packet, cipher and digest options to strict OpenPGP
+behavior.  Use this option to reset all previous options like
+--rfc1991, --force-v3-sigs, --s2k-*, --cipher-algo, --digest-algo and
+--compress-algo to OpenPGP compliant values.  All PGP workarounds are
+disabled.
+</para></listitem></varlistentry>
 
 <varlistentry>
 <term>--rfc1991</term>
 <listitem><para>
-Try to be more RFC1991 (PGP 2.x) compliant.
+Try to be more RFC-1991 (PGP 2.x) compliant.
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -1571,16 +1926,11 @@ a message that PGP 2.x will not be able to handle.  Note that `PGP
 2.x' here means `MIT PGP 2.6.2'.  There are other versions of PGP 2.x
 available, but the MIT release is a good common baseline.
 </para><para>
-This option implies `--rfc1991 --no-openpgp --disable-mdc
---no-force-v4-certs --no-comment --escape-from-lines --force-v3-sigs
+This option implies `--rfc1991 --disable-mdc --no-force-v4-certs
+--no-sk-comment --escape-from-lines --force-v3-sigs
 --no-ask-sig-expire --no-ask-cert-expire --cipher-algo IDEA
---digest-algo MD5 --compress-algo 1'
-</para></listitem></varlistentry>
-
-<varlistentry>
-<term>--no-pgp2</term>
-<listitem><para>
-Resets the --pgp2 option.
+--digest-algo MD5 --compress-algo 1'.  It also disables --textmode
+when encrypting.
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -1589,95 +1939,80 @@ Resets the --pgp2 option.
 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 making
-signatures with signing subkeys as PGP 6 does not understand
-signatures made by signing subkeys.
+compression algorithms none and ZIP.  This also disables
+--throw-keyid, and making signatures with signing subkeys as PGP 6
+does not understand signatures made by signing subkeys.
 </para><para>
-This option implies `--disable-mdc --no-comment --escape-from-lines
---force-v3-sigs --no-ask-sig-expire --compress-algo 1'
-</para></listitem></varlistentry>
-
-<varlistentry>
-<term>--no-pgp6</term>
-<listitem><para>
-Resets the --pgp6 option.
+This option implies `--disable-mdc --no-sk-comment --escape-from-lines
+--force-v3-sigs --no-ask-sig-expire'
 </para></listitem></varlistentry>
 
 <varlistentry>
 <term>--pgp7</term>
 <listitem><para>
 Set up all options to be as PGP 7 compliant as possible.  This is
-identical to --pgp6 except that the list of allowable ciphers is
-expanded to add AES128, AES192, AES256, and TWOFISH.
-</para></listitem></varlistentry>
-
-<varlistentry>
-<term>--no-pgp7</term>
-<listitem><para>
-Resets the --pgp7 option.
+identical to --pgp6 except that MDCs are not disabled, and the list of
+allowable ciphers is expanded to add AES128, AES192, AES256, and
+TWOFISH.
 </para></listitem></varlistentry>
 
 <varlistentry>
-<term>--openpgp</term>
+<term>--pgp8</term>
 <listitem><para>
-Reset all packet, cipher and digest options to OpenPGP behavior. Use
-this option to reset all previous options like --rfc1991,
---force-v3-sigs, --s2k-*, --cipher-algo, --digest-algo and
---compress-algo to OpenPGP compliant values.  All PGP workarounds are
-also disabled.
+Set up all options to be as PGP 8 compliant as possible.  PGP 8 is a
+lot closer to the OpenPGP standard than previous versions of PGP, so
+all this does is disable --throw-keyid and set --escape-from-lines.
+The allowed algorithms list is the same as --pgp7 with the addition of
+the SHA-256 digest algorithm.
 </para></listitem></varlistentry>
 
+</variablelist></para></listitem></varlistentry>
 
 <varlistentry>
 <term>--force-v3-sigs</term>
+<term>--no-force-v3-sigs</term>
 <listitem><para>
 OpenPGP states that an implementation should generate v4 signatures
 but PGP versions 5 and higher only recognize v4 signatures on key
 material.  This option forces v3 signatures for signatures on data.
 Note that this option overrides --ask-sig-expire, as v3 signatures
-cannot have expiration dates.
-</para></listitem></varlistentry>
-
-<varlistentry>
-<term>--no-force-v3-sigs</term>
-<listitem><para>
-Reset the --force-v3-sigs option.
+cannot have expiration dates.  --no-force-v3-sigs disables this
+option.
 </para></listitem></varlistentry>
 
 <varlistentry>
 <term>--force-v4-certs</term>
+<term>--no-force-v4-certs</term>
 <listitem><para>
 Always use v4 key signatures even on v3 keys.  This option also
 changes the default hash algorithm for v3 RSA keys from MD5 to SHA-1.
+--no-force-v4-certs disables this option.
 </para></listitem></varlistentry>
 
 <varlistentry>
-<term>--no-force-v4-certs</term>
+<term>--force-mdc</term>
 <listitem><para>
-Reset the --force-v4-certs option.
+Force the use of encryption with a modification detection code.  This
+is always used with the newer ciphers (those with a blocksize greater
+than 64 bits), or if all of the recipient keys indicate MDC support in
+their feature flags.
 </para></listitem></varlistentry>
 
-
 <varlistentry>
-<term>--force-mdc</term>
+<term>--disable-mdc</term>
 <listitem><para>
-Force the use of encryption with appended manipulation code.  This is
-always used with the newer ciphers (those with a blocksize greater
-than 64 bit).
+Disable the use of the modification detection code.  Note that by
+using this option, the encrypted message becomes vulnerable to a
+message modification attack.
 </para></listitem></varlistentry>
 
 <varlistentry>
 <term>--allow-non-selfsigned-uid</term>
+<term>--no-allow-non-selfsigned-uid</term>
 <listitem><para>
 Allow the import and use of keys with user IDs which are not
 self-signed.  This is not recommended, as a non self-signed user ID is
-trivial to forge.
-</para></listitem></varlistentry>
-
-<varlistentry>
-<term>--no-allow-non-selfsigned-uid</term>
-<listitem><para>
-Reset the --allow-non-selfsigned-uid option.
+trivial to forge.  --no-allow-non-selfsigned-uid disables.
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -1688,36 +2023,45 @@ one.  This option should only be used in very special environments as
 it does not ensure the de-facto standard format of user IDs.
 </para></listitem></varlistentry>
 
-
 <varlistentry>
 <term>--ignore-time-conflict</term>
 <listitem><para>
 GnuPG normally checks that the timestamps associated with keys and
-signatures have plausible values.  However, sometimes a signature seems to
-be older than the key due to clock problems.  This option makes these
-checks just a warning.
+signatures have plausible values.  However, sometimes a signature
+seems to be older than the key due to clock problems.  This option
+makes these checks just a warning.  See also --ignore-valid-from for
+timestamp issues on subkeys.
 </para></listitem></varlistentry>
 
 <varlistentry>
 <term>--ignore-valid-from</term>
 <listitem><para>
-GnuPG normally does not select and use subkeys created in the future.  This
-option allows the use of such keys and thus exhibits the pre-1.0.7
-behaviour.  You should not use this option unless you there is some
-clock problem.
+GnuPG normally does not select and use subkeys created in the future.
+This option allows the use of such keys and thus exhibits the
+pre-1.0.7 behaviour.  You should not use this option unless you there
+is some clock problem.  See also --ignore-time-conflict for timestamp
+issues with signatures.
 </para></listitem></varlistentry>
 
 <varlistentry>
 <term>--ignore-crc-error</term>
 <listitem><para>
-The ASCII armor used by OpenPG is protected by a CRC checksum against
+The ASCII armor used by OpenPGP is protected by a CRC checksum against
 transmission errors.  Sometimes it happens that the CRC gets mangled
-somewhere on the transmission channel 
-but the actual content (which is anyway protected by
-the OpenPGP protocol) is still okay.  This option will let gpg ignore
-CRC errors.
+somewhere on the transmission channel but the actual content (which is
+protected by the OpenPGP protocol anyway) is still okay.  This option
+will let gpg ignore CRC errors.
 </para></listitem></varlistentry>
 
+<varlistentry>
+<term>--ignore-mdc-error</term>
+<listitem><para>
+This option changes a MDC integrity protection failure into a warning.
+This can be useful if a message is partially corrupt, but it is
+necessary to get as much data as possible out of the corrupt message.
+However, be aware that a MDC protection failure may also mean that the
+message was tampered with intentionally by an attacker.
+</para></listitem></varlistentry>
 
 <varlistentry>
 <term>--lock-once</term>
@@ -1727,7 +2071,6 @@ and do not release the lock until the process
 terminates.
 </para></listitem></varlistentry>
 
-
 <varlistentry>
 <term>--lock-multiple</term>
 <listitem><para>
@@ -1755,19 +2098,16 @@ are not desired.  This option can be used to achieve that with the cost of
 slower random generation.
 </para></listitem></varlistentry>
 
-
 <varlistentry>
 <term>--no-verbose</term>
 <listitem><para>
 Reset verbose level to 0.
 </para></listitem></varlistentry>
 
-
 <varlistentry>
 <term>--no-greeting</term>
 <listitem><para>
-Suppress the initial copyright message but do not
-enter batch mode.
+Suppress the initial copyright message.
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -1779,7 +2119,24 @@ Suppress the warning about "using insecure memory".
 <varlistentry>
 <term>--no-permission-warning</term>
 <listitem><para>
-Suppress the warning about unsafe file permissions.
+
+Suppress the warning about unsafe file and home directory (--homedir)
+permissions.  Note that the permission checks that GnuPG performs are
+not intended to be authoritative, but rather they simply warn about
+certain common permission problems.  Do not assume that the lack of a
+warning means that your system is secure.
+</para><para>
+Note that the warning for unsafe --homedir permissions cannot be
+supressed in the gpg.conf file, as this would allow an attacker to
+place an unsafe gpg.conf file in place, and use this file to supress
+warnings about itself.  The --homedir permissions warning may only be
+supressed on the command line.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>--no-mdc-warning</term>
+<listitem><para>
+Suppress the warning about missing MDC integrity protection.
 </para></listitem></varlistentry>
 
 
@@ -1810,8 +2167,12 @@ verification is not needed.
 <varlistentry>
 <term>--with-colons</term>
 <listitem><para>
-Print key listings delimited by colons.  Note, that the output will be
-encoded in UTF-8 regardless of any --charset setting.
+Print key listings delimited by colons.  Note that the output will be
+encoded in UTF-8 regardless of any --charset setting.  This format is
+useful when GnuPG is called from scripts and other programs as it is
+easily machine parsed.  The details of this format are documented in
+the file doc/DETAILS, which is included in the GnuPG source
+distribution.
 </para></listitem></varlistentry>
 
 
@@ -1841,8 +2202,8 @@ in future versions.
 <varlistentry>
 <term>--fixed-list-mode</term>
 <listitem><para>
-Do not merge user ID and primary key in --with-colon listing mode and
-print all timestamps as seconds since 1970-01-01.
+Do not merge primary user ID and primary key in --with-colon listing
+mode and print all timestamps as seconds since 1970-01-01.
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -1900,32 +2261,25 @@ handing out the secret key.
 
 <varlistentry>
 <term>--ask-sig-expire</term>
+<term>--no-ask-sig-expire</term>
 <listitem><para>
 When making a data signature, prompt for an expiration time.  If this
 option is not specified, the expiration time is "never".
-</para></listitem></varlistentry
-
-<varlistentry>
-<term>--no-ask-sig-expire</term>
-<listitem><para>
-Resets the --ask-sig-expire option.
-</para></listitem></varlistentry
+--no-ask-sig-expire disables this option.
+</para></listitem></varlistentry>
 
 <varlistentry>
 <term>--ask-cert-expire</term>
+<term>--no-ask-cert-expire</term>
 <listitem><para>
 When making a key signature, prompt for an expiration time.  If this
 option is not specified, the expiration time is "never".
-</para></listitem></varlistentry
-
-<varlistentry>
-<term>--no-ask-cert-expire</term>
-<listitem><para>
-Resets the --ask-cert-expire option.
-</para></listitem></varlistentry
+--no-ask-cert-expire disables this option.
+</para></listitem></varlistentry>
 
 <varlistentry>
 <term>--expert</term>
+<term>--no-expert</term>
 <listitem><para>
 Allow the user to do certain nonsensical or "silly" things like
 signing an expired or revoked key, or certain potentially incompatible
@@ -1933,14 +2287,8 @@ things like generating deprecated key types.  This also disables
 certain warning messages about potentially incompatible actions.  As
 the name implies, this option is for experts only.  If you don't fully
 understand the implications of what it allows you to do, leave this
-off.
-</para></listitem></varlistentry
-
-<varlistentry>
-<term>--no-expert</term>
-<listitem><para>
-Resets the --expert option.
-</para></listitem></varlistentry
+off.  --no-expert disables this option.
+</para></listitem></varlistentry>
 
 <varlistentry>
 <term>--merge-only</term>
@@ -1967,7 +2315,7 @@ handy in case where an encrypted message contains a bogus key ID.
 <term>--enable-special-filenames</term>
 <listitem><para>
 This options enables a mode in which filenames of the form
-<filename>-&#38;n</>, where n is a non-negative decimal number,
+<filename>-&#38;n</filename>, where n is a non-negative decimal number,
 refer to the file descriptor n and not to a file with that name.
 </para></listitem></varlistentry>
 
@@ -1981,13 +2329,16 @@ Experimental use only.
 <term>--group &ParmNameValues;</term>
 <listitem><para>
 Sets up a named group, which is similar to aliases in email programs.
-Any time the group name is a receipient (-r or --recipient), it will
+Any time the group name is a recipient (-r or --recipient), it will
 be expanded to the values specified.
-
+</para><para>
 The values are &ParmKeyIDs; or fingerprints, but any key description
 is accepted.  Note that a value with spaces in it will be treated as
 two different values.  Note also there is only one level of expansion
-- you cannot make an group that points to another group.
+- you cannot make an group that points to another group.  When used
+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.
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -2004,6 +2355,8 @@ Set the list of personal cipher preferences to &ParmString;, this list
 should be a string similar to the one printed by the command "pref" in
 the edit menu.  This allows the user to factor in their own preferred
 algorithms when algorithms are chosen via recipient key preferences.
+The most highly ranked cipher in this list is also used for the
+--symmetric encryption command.
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -2013,6 +2366,9 @@ Set the list of personal digest preferences to &ParmString;, this list
 should be a string similar to the one printed by the command "pref" in
 the edit menu.  This allows the user to factor in their own preferred
 algorithms when algorithms are chosen via recipient key preferences.
+The most highly ranked digest algorithm in this list is algo used when
+signing without encryption (e.g. --clearsign or --sign).  The default
+value is SHA-1.
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -2022,7 +2378,8 @@ Set the list of personal compression preferences to &ParmString;, this
 list should be a string similar to the one printed by the command
 "pref" in the edit menu.  This allows the user to factor in their own
 preferred algorithms when algorithms are chosen via recipient key
-preferences.
+preferences.  The most highly ranked algorithm in this list is also
+used when there are no recipient keys to consider (e.g. --symmetric).
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -2042,8 +2399,8 @@ menu.
 <refsect1>
     <title>How to specify a user ID</title>
     <para>
-There are different ways on how to specify a user ID to GnuPG;
-here are some examples:
+There are different ways to specify a user ID to GnuPG; here are some
+examples:
     </para>
 
     <variablelist>
@@ -2204,11 +2561,12 @@ The first is the path to the Unix Domain Socket, the second the PID of
 the gpg-agent and the protocol version which should be set to 1.  When
 starting the gpg-agent as described in its documentation, this
 variable is set to the correct value.  The option --gpg-agent-info can
-be used to overide it.</para></listitem>
+be used to override it.</para></listitem>
 </varlistentry>
 <varlistentry>
 <term>http_proxy</term>
-<listitem><para>Only honored when the option --honor-http-proxy is set.</para></listitem>
+<listitem><para>Only honored when the keyserver-option
+honor-http-proxy is set.</para></listitem>
 </varlistentry>
     </variablelist>
 
@@ -2254,8 +2612,14 @@ be used to overide it.</para></listitem>
 </varlistentry>
 
 <varlistentry>
+<term>~/.gnupg/gpg.conf</term>
+<listitem><para>Default configuration file</para></listitem>
+</varlistentry>
+
+<varlistentry>
 <term>~/.gnupg/options</term>
-<listitem><para>May contain options</para></listitem>
+<listitem><para>Old style configuration file; only used when gpg.conf
+is not found</para></listitem>
 </varlistentry>
 
 <varlistentry>
@@ -2289,8 +2653,43 @@ is *very* easy to spy out your passphrase!
 <para>
 If you are going to verify detached signatures, make sure that the
 program knows about it; either be giving both filenames on the
-commandline or using <literal>-</literal> to specify stdin.
+command line or using <literal>-</literal> to specify stdin.
+</para>
+</refsect1>
+
+<refsect1>
+    <title>INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS</title>
+<para>
+GnuPG tries to be a very flexible implementation of the OpenPGP
+standard.  In particular, GnuPG implements many of the "optional"
+parts of the standard, such as the RIPEMD/160 hash, and the ZLIB
+compression algorithms.  It is important to be aware that not all
+OpenPGP programs implement these optional algorithms and that by
+forcing their use via the --cipher-algo, --digest-algo,
+--cert-digest-algo, or --compress-algo options in GnuPG, it is
+possible to create a perfectly valid OpenPGP message, but one that
+cannot be read by the intended recipient.
 </para>
+
+<para>
+For example, as of this writing, no version of official PGP supports
+the BLOWFISH cipher algorithm.  If you use it, no PGP user will be
+able to decrypt your message.  The same thing applies to the ZLIB
+compression algorithm.  By default, GnuPG uses the OpenPGP preferences
+system that will always do the right thing and create messages that
+are usable by all recipients, regardless of which OpenPGP program they
+use.  Only override this safe default if you know what you are doing.
+</para>
+
+<para>
+If you absolutely must override the safe default, or if the
+preferences on a given key are invalid for some reason, you are far
+better off using the --pgp2, --pgp6, --pgp7, or --pgp8 options.  These
+options are safe as they do not force any particular algorithms in
+violation of OpenPGP, but rather reduce the available algorithms to a
+"PGP-safe" list.
+</para>
+
 </refsect1>
 
 
@@ -2307,4 +2706,3 @@ as locked memory is allocated.
 </refsect1>
 
 </refentry>
-