Some typos, and explanations for --show-photos, --no-show-photos,

--photo-viewer, --nrsign-key, --default-check-level, --search-keys,
--keyserver-options, --show-notation, --no-show-notation,
--show-policy-url, --no-show-policy-url, --for-your-eyes-only,
--no-for-your-eyes-only, --pgp2, --no-pgp2, --no-permission-warning,
--expert, --no-expert.

doc/ChangeLog

@@ -1,3 +1,15 @@
+2001-12-22  David Shaw  <dshaw@jabberwocky.com>
+
+	* gpg.sgml: Fixed a few typos.
+
+	* gpg.sgml: Added documentation for --show-photos,
+	--no-show-photos, --photo-viewer, --nrsign-key,
+	--default-check-level, --search-keys, --keyserver-options,
+	--show-notation, --no-show-notation, --show-policy-url,
+	--no-show-policy-url, --for-your-eyes-only,
+	--no-for-your-eyes-only, --pgp2, --no-pgp2,
+	--no-permission-warning, --expert, --no-expert.
+
 2001-10-31  Werner Koch  <wk@gnupg.org>
 
 	* gpg.sgml: Add a remark on how to get the long key ID.  Suggested

doc/gpg.sgml

@@ -209,6 +209,35 @@ List all keys from the secret keyrings, or just the
 ones given on the command line.
 </para></listitem></varlistentry>
 
+<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.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>--no-show-photos</term>
+<listitem><para>
+Resets the --show-photos flag.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>--photo-viewer &ParmString;</term>
+<listitem><para>
+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
+same, except the file will not be deleted once the viewer exits.
+Other flags are "%k" for the key ID, "%K" for the long key ID, "%f"
+for the key fingerprint, 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"
+</para></listitem></varlistentry>
 
 <varlistentry>
 <term>--show-keyring</term>
@@ -216,7 +245,7 @@ ones given on the command line.
 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 listig all keys.
+effect when listing all keys.
 </para></listitem></varlistentry>
 
 
@@ -233,7 +262,6 @@ Same as --list-keys, but the signatures are listed too.
 Same as --list-sigs, but the signatures are verified.
 </para></listitem></varlistentry>
 
-
 <varlistentry>
 <term>--fingerprint &OptParmNames;</term>
 <listitem><para>
@@ -422,17 +450,47 @@ calculation has failed; probably due to an expired key.</para></listitem></varli
 <varlistentry>
 <term>--sign-key &ParmName;</term>
 <listitem><para>
-Sign a public key with your secret key.	This is a shortcut version
+Signs a public key with your secret key. This is a shortcut version of
-of the subcommand "sign" from --edit.
+the subcommand "sign" from --edit.
 </para></listitem></varlistentry>
 
 <varlistentry>
 <term>--lsign-key &ParmName;</term>
 <listitem><para>
-Sign a public key with your secret key but mark it as non-exportable.
+Signs a public key with your secret key but marks it as
-This is a shortcut version of the subcommand "lsign" from --edit.
+non-exportable.  This is a shortcut version of the subcommand "lsign"
+from --edit.
 </para></listitem></varlistentry>
 
+<varlistentry>
+<term>--nrsign-key &ParmName;</term>
+<listitem><para>
+Signs a public key with your secret key but marks it as non-revocable.
+This is a shortcut version of the subcommand "nrsign" from --edit.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>--default-check-level &ParmN;</term>
+<listitem><para>
+The default to use for the check level when signing a key.
+</para><para>
+0 means you make no particular claim as to how carefully you verified
+the key.  1 means you believe the key is owned by the person who
+claims to own it but you could not, or did not verify the key at all.
+This is useful for a "persona" verification, where you sign the key of
+a pseudonymous user.  2 means you did casual verification of the key.
+For example, this could mean that you verified that the key
+fingerprint and checked the user ID on the key against a photo ID.  3
+means you did extensive verification of the key.  For example, this
+could mean that you verified the key fingerprint and checked the user
+ID on the key against a photo ID, and also verified the email address
+on the key belongs to the key owner.
+</para><para>
+This option defaults to 0.
+</para></listitem></varlistentry>
+
+
+
 <varlistentry>
 <term>--trusted-key <parameter>long key ID</parameter></term>
 <listitem><para>
@@ -531,25 +589,23 @@ but does only the merging of new signatures, user-IDs and subkeys.
 <varlistentry>
 <term>--recv-keys &ParmKeyIDs;</term>
 <listitem><para>
-Import the keys with the given key IDs from a HKP
+Import the keys with the given key IDs from a keyserver. Option
-keyserver. Option --keyserver must be used to
+--keyserver must be used to give the name of this keyserver.
-give the name of this keyserver.
 </para></listitem></varlistentry>
 
-
 <varlistentry>
-<term>--recv-keys &ParmKeyIDs;</term>
+<term>--search-keys &OptParmNames;</term>
 <listitem><para>
-Import the keys with the given key IDs from a HKP
+Search the keyserver for the given names.  Multiple names given here
-keyserver. Option --keyserver must be used to
+will be joined together to create the search string for the keyserver.
-give the name of this keyserver.
+Option --keyserver must be used to give the name of this keyserver.
 </para></listitem></varlistentry>
 
 <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 intercative command because it may has to
+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
@@ -838,37 +894,97 @@ is bound to the key.
 <varlistentry>
 <term>--keyserver &ParmName;</term>
 <listitem><para>
-Use &ParmName to lookup keys which are not yet in
+Use &ParmName as your keyserver.  This is the server that --recv-keys,
-your keyring.  This is only done while verifying
+--send-keys, and --search-keys will communicate with to receive keys
-messages with signatures.  The option is also
+from, send keys to, and search for keys on.  The format of the
-required for the command --send-keys to
+&ParmName is a URI: `scheme:[//]keyservername[:port]' The scheme is
-specify the keyserver to where the keys should
+the type of keyserver: "hkp" for the Horowitz (or compatible)
-be send.  All keyservers synchronize with each
+keyservers, "ldap" for the NAI LDAP keyserver, or "mailto" for the
-other - so there is no need to send keys to more
+Horowitz email keyserver.  Note that your particular installation of
-than one server.  Using the command
+GnuPG may have other keyserver types available as well.
-"host -l pgp.net | grep wwwkeys" gives you a
+</para><para>
-list of keyservers.  Because there is load
+Most keyservers synchronize with each other, so there is generally no
-balancing using round-robin DNS you may notice
+need to send keys to more than one server.  Using the command "host -l
-that you get different key servers.
+pgp.net | grep wwwkeys" gives you a list of HKP keyservers.  When
+using one of the wwwkeys servers, due to load balancing using
+round-robin DNS you may notice that you get a different key server
+each time.
 </para></listitem></varlistentry>
 
+<varlistentry>
+<term>--keyserver-options <parameter>parameters</parameter></term>
+<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
+schemes, 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.
+</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.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>use-temp-files</term>
+<listitem><para>
+On most Unix-like platforms, GnuPG communicates with the keyserver
+helper program via pipes, which is the most efficient method.  This
+option forces GnuPG to use temporary files to communicate.  On some
+platforms (such as Win32 and RISC OS), this option is always enabled.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>keep-temp-files</term>
+<listitem><para>
+If using `use-temp-files', do not delete the temp files after using
+them.  This option is useful to learn the keyserver communication
+protocol by reading the temporary files.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>verbose</term>
+<listitem><para>
+Tell the keyserver helper program to be more verbose.  This option can
+be repeated multiple times to increase the verbosity level.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>honor-http-proxy</term>
+<listitem><para>
+For keyserver schemes that use HTTP (such as HKP), try to access the
+keyserver over the proxy set with the environment variable
+"http_proxy".
+</para></listitem></varlistentry>
+</variablelist>
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>--auto-key-retrieve</term>
+<listitem><para>
+This option enables the automatic retrieving of keys from a keyserver
+when verifying signatures made by keys that are not on the local
+keyring.
+</para></listitem></varlistentry>
 
 <varlistentry>
 <term>--no-auto-key-retrieve</term>
 <listitem><para>
 This option disables the automatic retrieving of keys from a keyserver
-while verifying signatures. This option allows you to keep a keyserver in
+while verifying signatures. This may be of use if --auto-key-retrieve
-the options file for the --send-keys and --recv-keys commands.
+is enabled from an options file.
 </para></listitem></varlistentry>
 
 
-<varlistentry>
-<term>--honor-http-proxy</term>
-<listitem><para>
-Try to access the keyserver over the proxy set with the variable
-"http_proxy".
-</para></listitem></varlistentry>
-
 <varlistentry>
 <term>--keyring &ParmFile;</term>
 <listitem><para>
@@ -1050,6 +1166,19 @@ If you prefix &ParmName; with an exclamation mark, the notation
 data will be flagged as critical (rfc2440:5.2.3.15).
 </para></listitem></varlistentry>
 
+<varlistentry>
+<term>--show-notation</term>
+<listitem><para>
+Show key signature notations in the --list-sigs or --check-sigs
+listings.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>--no-show-notation</term>
+<listitem><para>
+Do not show key signature notations in the --list-sigs or --check-sigs
+listings.
+</para></listitem></varlistentry>
 
 <varlistentry>
 <term>--set-policy-url &ParmString;</term>
@@ -1059,6 +1188,18 @@ If you prefix it with an exclamation mark, the policy URL
 packet will be flagged as critical.
 </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.
+</para></listitem></varlistentry>
 
 <varlistentry>
 <term>--set-filename &ParmString;</term>
@@ -1067,6 +1208,21 @@ Use &ParmString; as the name of file which is stored in
 messages.
 </para></listitem></varlistentry>
 
+<varlistentry>
+<term>--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
+
 <varlistentry>
 <term>--use-embedded-filename</term>
 <listitem><para>
@@ -1155,14 +1311,13 @@ for conventional encryption.
 <varlistentry>
 <term>--compress-algo &ParmN;</term>
 <listitem><para>
-Use compress algorithm	&ParmN;. Default is 2 which is
+Use compression algorithm &ParmN;. Default is 2 which is RFC1950
-RFC1950 compression. You may use 1 to use the old zlib 
+compression. You may use 1 to use the old zlib version (RFC1951) which
-version (RFC1951) which is used by PGP. The default algorithm may
+is used by PGP. 0 disables compression. The default algorithm may give
-give better results because the window size is not limited
+better results because the window size is not limited to 8K. If this
-to 8K. If this is not used the OpenPGP behavior is used,
+is not used the OpenPGP behavior is used, i.e. the compression
-i.e. the compression algorithm is selected from the
+algorithm is selected from the preferences; note, that this can't be
-preferences; note, that this can't be done if you do
+done if you do not encrypt the data.
-not encrypt the data.
 </para></listitem></varlistentry>
 
 
@@ -1282,6 +1437,23 @@ agent before it asks for a passphrase.
 Try to be more RFC1991 (PGP 2.x) compliant.
 </para></listitem></varlistentry>
 
+<varlistentry>
+<term>--pgp2</term>
+<listitem><para>
+Set up all options to be as PGP 2.x compliant as possible, and warn if
+an action is taken (e.g. encrypting to a non-RSA key) that will create
+a message that PGP 2.x will not be able to handle.
+</para><para>
+This option implies `--rfc1991 --no-openpgp --no-force-v4-certs
+--no-comment --escape-from --no-force-v3-sigs --cipher-algo IDEA
+--digest-algo MD5 --compress-algo 1'
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>--no-pgp2</term>
+<listitem><para>
+Resets the --pgp2 option.
+</para></listitem></varlistentry>
 
 <varlistentry>
 <term>--openpgp</term>
@@ -1313,12 +1485,12 @@ Reset the --force-v3-sigs option.
 <varlistentry>
 <term>--force-v4-certs</term>
 <listitem><para>
-Always use v4 key signatures even on v3 keys.  This option does also
+Always use v4 key signatures even on v3 keys.  This option also
-change the default hash algorithm for v3 RSA keys from MD5 to SHA-1.
+changes the default hash algorithm for v3 RSA keys from MD5 to SHA-1.
 </para></listitem></varlistentry>
 
 <varlistentry>
-<term>--no-force-v3-certs</term>
+<term>--no-force-v4-certs</term>
 <listitem><para>
 Reset the --force-v4-certs option.
 </para></listitem></varlistentry>
@@ -1339,7 +1511,7 @@ This option might not be implemented yet.
 Allow the import of keys with user IDs which are not self-signed, but
 have at least one signature.
 This only allows the import - key validation will fail and you
-have to check the validity of the key my other means.  This hack is
+have to check the validity of the key by other means.  This hack is
 needed for some German keys generated with pgp 2.6.3in. You should really
 avoid using it, because OpenPGP has better mechanics to do separate signing
 and encryption keys.
@@ -1441,6 +1613,12 @@ enter batch mode.
 Suppress the warning about "using insecure memory".
 </para></listitem></varlistentry>
 
+<varlistentry>
+<term>--no-permission-warning</term>
+<listitem><para>
+Suppress the warning about unsafe file permissions.
+</para></listitem></varlistentry>
+
 
 <varlistentry>
 <term>--no-armor</term>
@@ -1557,6 +1735,21 @@ content of an encrypted message; using this option you can do this without
 handing out the secret key.
 </para></listitem></varlistentry>
 
+<varlistentry>
+<term>--expert</term>
+<listitem><para>
+Enable certain options, such as prompting for a signature expiration
+date, that are not frequently used by regular users.  Also permits the
+user to do certain "silly" things like signing an expired or revoked
+key.
+</para></listitem></varlistentry
+
+<varlistentry>
+<term>--no-expert</term>
+<listitem><para>
+Resets the --expert option.
+</para></listitem></varlistentry
+
 <varlistentry>
 <term>--merge-only</term>
 <listitem><para>