Updated texinfo files

doc/gpg.texi

@@ -101,8 +101,13 @@ decrypted. The syntax or the filenames is the same.
 
 @item ---list-keys @code{names}
 @itemx ---list-public-keys @code{names}
-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.
+
+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.
 
 @item ---list-secret-keys @code{names}
 List all keys from the secret keyrings, or just the ones given on the
@@ -113,6 +118,18 @@ is not usable (for example, if it was created via
 @item ---list-sigs @code{names}
 Same as ---list-keys, but the signatures are listed too.
 
+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").
+
 @item ---check-sigs @code{names}
 Same as ---list-sigs, but the signatures are verified.
 
@@ -191,7 +208,8 @@ Create an alternate user id.
 
 @item addphoto
 Create a photographic user id. This will prompt for a JPEG file that
-will be embedded into the user ID.
+will be embedded into the user ID. A very large JPEG will make for a
+very large key.
 
 @item deluid
 Delete a user id.
@@ -492,12 +510,10 @@ Write output to @code{file}.
 
 @item ---mangle-dos-filenames
 @itemx ---no-mangle-dos-filenames
-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.
+Older version of Windows cannot handle filenames with more than one
+dot. ---mangle-dos-filenames causes GnuPG to replace (rather than add
+to) the extension of an output filename to avoid this problem. This
+option is off by default and has no effect on non-Windows platforms.
 
 @item -u, ---local-user @code{name}
 Use @code{name} as the user ID to sign.
@@ -725,6 +741,12 @@ This option enables the automatic retrieving of keys from a keyserver
 when verifying signatures made by keys that are not on the local
 keyring.
 
+Note that this option makes a "web bug" like behavior possible.
+Keyserver operators can see which keys you request, so by sending you
+a message signed by a brand new key (which you naturally will not have
+on your local keyring), the operator can tell both your IP address and
+the time when you verified the signature.
+
 @end table
 
 @item ---import-options @code{parameters}
@@ -773,12 +795,95 @@ Include designated revoker information that was marked as
 
 @end table
 
+@item ---list-options @code{parameters}
+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, --list-secret-keys, and the --edit-key functions).
+Options can be prepended with a `no-' to give the opposite meaning.
+The options are:
+
+@table @asis
+@item show-photos
+Causes ---list-keys, --list-sigs, --list-public-keys, and
+---list-secret-keys to display any photo IDs attached to the key.
+Defaults to no. See also ---photo-viewer.
+
+@item show-policy-url
+Show policy URLs in the ---list-sigs or --check-sigs listings.
+Defaults to no.
+
+@item show-notation
+Show signature notations in the ---list-sigs or --check-sigs listings.
+Defaults to no.
+
+@item show-keyserver-url
+Show any preferred keyserver URL in the ---list-sigs or --check-sigs
+listings. Defaults to no.
+
+@item show-validity
+Display the calculated validity of keys and user IDs during key
+listings. Defaults to no.
+
+@item show-long-keyid
+Display all 64 bits (16 digits) of key IDs during key listings, rather
+than the more common 32 bit (8 digit) IDs. Defaults to no.
+
+@item show-unusable-uids
+Show revoked and expired user IDs in key listings. Defaults to no.
+
+@item show-keyring
+Display the keyring name at the head of key listings to show which
+keyring a given key resides on. Defaults to no.
+
+@item show-sig-expire
+Show signature expiration dates (if any) during ---list-sigs or
+---check-sigs listings. Defaults to no.
+
+@end table
+
+@item ---verify-options @code{parameters}
+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:
+
+@table @asis
+@item show-photos
+Display any photo IDs present on the key that issued the signature.
+Defaults to no. See also ---photo-viewer.
+
+@item show-policy-url
+Show policy URLs in the signature being verified. Defaults to no.
+
+@item show-notation
+Show signature notations in the signature being verified. Defaults to
+no.
+
+@item show-keyserver-url
+Show any preferred keyserver URL in the signature being verified.
+Defaults to no.
+
+@item show-validity
+Display the calculated validity of the user IDs on the key that issued
+the signature. Defaults to no.
+
+@item show-long-keyid
+Display all 64 bits (16 digits) of key IDs during signature
+verification, rather than the more common 32 bit (8 digit) IDs.
+Defaults to no.
+
+@item show-unusable-uids
+Show revoked and expired user IDs during signature verification.
+Defaults to no.
+
+@end table
+
 @item ---show-photos
 @itemx ---no-show-photos
 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.
----no-show-photos disables this option.
+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.
 
 @item ---photo-viewer @code{string}
 This is the command line that should be run to view a photo ID. "%i"
@@ -791,7 +896,8 @@ 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.
 
 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.
 
 @item ---exec-path @code{string}
 Sets a list of directories to search for photo viewers and keyserver
@@ -800,10 +906,9 @@ default directory, and photo viewers use the $PATH environment
 variable.
 
 @item ---show-keyring
-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.
 
 @item ---keyring @code{file}
 Add @code{file} to the list of keyrings. If @code{file} begins with a
@@ -921,19 +1026,12 @@ Please note that this has nothing to do with the comments in clear
 text signatures or armor headers. ---no-sk-comments disables this
 option.
 
-@item ---no-comment
-See ---no-sk-comments. This option is deprecated and may be removed
-soon.
-
 @item ---comment @code{string}
-Use @code{string} as the comment string in clear text signatures. The
-default behavior is not to use a comment string.
-
-@item ---default-comment
-Force to write the standard comment string in clear
-text signatures. Use this to overwrite a ---comment
-from a config file. This option is now obsolete because there is no
-default comment string anymore.
+@itemx ---no-comments
+Use @code{string} as a comment string in clear text signatures and
+ASCII armored messages or keys (see ---armor). The default behavior is
+not to use a comment string. ---comment may be repeated multiple times
+to get multiple comment strings. ---no-comments removes all comments.
 
 @item ---emit-version
 @itemx ---no-emit-version
@@ -942,7 +1040,7 @@ Force inclusion of the version string in ASCII armored output.
 
 @item ---sig-notation @code{name=value}
 @itemx ---cert-notation @code{name=value}
-@itemx -N, ---notation-data @code{name=value}
+@itemx -N, ---set-notation @code{name=value}
 Put the name value pair into the signature as notation data.
 @code{name} must consist only of printable characters or spaces, and
 must contain a '@@' character. This is to help prevent pollution of
@@ -952,29 +1050,32 @@ encoded in UTF8, so you should check that your ---charset is set
 correctly. If you prefix @code{name} 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). ---notation-data
+sets a notation for key signatures (certifications). ---set-notation
 sets both.
 
 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" for the long
-key ID of the key being signed, "%f" for the key fingerprint of the
-key being signed, "%s" for the key ID of the key making the signature,
-"%S" for the long key ID of the key making the signature, and "%%"
-results in a single "%". %k, %K, and %f are only meaningful when
-making a key signature (certification).
+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).
 
 @item ---show-notation
 @itemx ---no-show-notation
 Show signature notations in the ---list-sigs or --check-sigs listings
-as well as when verifying a signature with a notation in it.
----no-show-notation disables this option.
+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.
 
 @item ---sig-policy-url @code{string}
 @itemx ---cert-policy-url @code{string}
 @itemx ---set-policy-url @code{string}
-Use @code{string} 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
+Use @code{string} as a 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.
 
@@ -983,8 +1084,16 @@ The same %-expandos used for notation data are available here as well.
 @item ---show-policy-url
 @itemx ---no-show-policy-url
 Show policy URLs in the ---list-sigs or --check-sigs listings as well
-as when verifying a signature with a policy URL in it.
----no-show-policy-url disables this option.
+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.
+
+@item ---sig-keyserver-url @code{string}
+Use @code{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}
 Use @code{string} as the filename which is stored inside messages.
@@ -1175,6 +1284,10 @@ behavior. Use this option to reset all previous options like
 ---compress-algo to OpenPGP compliant values. All PGP workarounds are
 disabled.
 
+@item ---rfc2440
+Reset all packet, cipher and digest options to strict RFC-2440
+behavior. Note that this is currently the same thing as ---openpgp.
+
 @item ---rfc1991
 Try to be more RFC-1991 (PGP 2.x) compliant.
 
@@ -1256,15 +1369,17 @@ it does not ensure the de-facto standard format of user IDs.
 
 @item ---ignore-time-conflict
 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.
 
 @item ---ignore-valid-from
-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.
 
 @item ---ignore-crc-error
 The ASCII armor used by OpenPGP is protected by a CRC checksum against
@@ -1313,11 +1428,17 @@ Suppress the initial copyright message.
 Suppress the warning about "using insecure memory".
 
 @item ---no-permission-warning
-Suppress the warning about unsafe file permissions. Note that the
-file permission checks that GnuPG performs are not intended to be
-authoritative, rather they simply warn about certain common permission
-problems. Do not assume that the lack of a warning means that your
-system is secure.
+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.
+
+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.
 
 @item ---no-mdc-warning
 Suppress the warning about missing MDC integrity protection.
@@ -1335,8 +1456,12 @@ used to make the decryption faster if the signature
 verification is not needed.
 
 @item ---with-colons
-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.
 
 @item ---with-key-data
 Print key listings delimited by colons (like ---with-colons) and print the public key data.
@@ -1445,6 +1570,9 @@ 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 ---no-groups
+Clear the ---group list.
+
 @item ---preserve-permissions
 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.
@@ -1463,7 +1591,8 @@ 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).
+signing without encryption (e.g. ---clearsign or --sign). The default
+value is SHA-1.
 
 @item ---personal-compress-preferences @code{string}
 Set the list of personal compression preferences to @code{string}, this