* gpg.sgml: Document --list-options (show-photos, show-policy-url,
[gnupg.git] / doc / gpg.sgml
index 1989c57..cd5de63 100644 (file)
 </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>
@@ -125,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>
@@ -214,8 +216,13 @@ 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>
 
 
@@ -233,6 +240,18 @@ is not usable (for example, if it was created via
 <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>
 
 
@@ -628,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>
@@ -726,12 +746,10 @@ 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>
 
@@ -744,7 +762,8 @@ Long options can be put in an options file (default
 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.
+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:
@@ -899,9 +918,9 @@ compression level of zlib (normally 6).
 <listitem><para>
 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 PGP
-compatibility; normally you would use --sign or --clearsign to
-selected the type of the signature.
+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>
 
 
@@ -996,14 +1015,14 @@ recipient's or signator's key.
 </para></listitem></varlistentry>
 
 <varlistentry>
-<term>--trust-model <parameter>openpgp|classic|always</parameter></term>
+<term>--trust-model <parameter>pgp|classic|always</parameter></term>
 <listitem><para>
 
 Set what trust model GnuPG should follow.  The models are:
 
 <variablelist>
 
-<varlistentry><term>openpgp</term><listitem><para>
+<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>
@@ -1200,13 +1219,86 @@ Include designated revoker information that was marked as
 </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 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>
 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.
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -1222,7 +1314,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.
 </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>
@@ -1237,21 +1330,19 @@ variable.
 <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>
@@ -1265,13 +1356,25 @@ Same as --keyring but for the secret keyrings.
 
 <varlistentry>
 <term>--primary-keyring &ParmFile;</term>
-<listitem<para>
+<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>
 <listitem><para>
 Set the name of the home directory to &ParmDir; If this
@@ -1416,15 +1519,16 @@ option.
 <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>
 
 
@@ -1450,7 +1554,7 @@ Force inclusion of the version string in ASCII armored output.
 <varlistentry>
 <term>--sig-notation &ParmNameValue;</term>
 <term>--cert-notation &ParmNameValue;</term>
-<term>-N, --notation-data &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 printable characters or spaces, and
@@ -1461,18 +1565,20 @@ 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).  --notation-data
+sets a notation for key signatures (certifications).  --set-notation
 sets both.
 </para>
 
 <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" 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).
 </para>
 
 </listitem></varlistentry>
@@ -1482,8 +1588,9 @@ making a key signature (certification).
 <term>--no-show-notation</term>
 <listitem><para>
 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.
 </para></listitem></varlistentry>
 
 
@@ -1496,10 +1603,8 @@ 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>
+(certifications).  --set-policy-url sets both.
+</para><para>
 The same %-expandos used for notation data are available here as well.
 </para></listitem></varlistentry>
 
@@ -1508,15 +1613,17 @@ The same %-expandos used for notation data are available here as well.
 <term>--no-show-policy-url</term>
 <listitem><para>
 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.
 </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>
@@ -1727,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>
 
 
@@ -1770,19 +1878,47 @@ option.
 <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>
 <term>--pgp2</term>
-<term>--no-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
@@ -1790,16 +1926,15 @@ 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'.  It also disables --textmode
-when encrypting.  --no-pgp2 disables this option.
+when encrypting.
 </para></listitem></varlistentry>
 
 <varlistentry>
 <term>--pgp6</term>
-<term>--no-pgp6</term>
 <listitem><para>
 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),
@@ -1808,42 +1943,30 @@ 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' --no-pgp6
-disables this 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>
-<term>--no-pgp7</term>
 <listitem><para>
 Set up all options to be as PGP 7 compliant as possible.  This is
 identical to --pgp6 except that MDCs are not disabled, and the list of
 allowable ciphers is expanded to add AES128, AES192, AES256, and
-TWOFISH.  --no-pgp7 disables this option.
+TWOFISH.
 </para></listitem></varlistentry>
 
 <varlistentry>
 <term>--pgp8</term>
-<term>--no-pgp8</term>
 <listitem><para>
 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 and
---compress-algo 1.  The allowed algorithms list is the same as --pgp7
-with the addition of the SHA-256 digest algorithm.  --no-pgp8 disables
-this option.
+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>
 
-<varlistentry>
-<term>--openpgp</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 and
---pgpX modes are also disabled.
-</para></listitem></varlistentry>
+</variablelist></para></listitem></varlistentry>
 
 <varlistentry>
 <term>--force-v3-sigs</term>
@@ -1904,18 +2027,20 @@ it does not ensure the de-facto standard format of user IDs.
 <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>
@@ -1994,11 +2119,18 @@ Suppress the warning about "using insecure memory".
 <varlistentry>
 <term>--no-permission-warning</term>
 <listitem><para>
-Suppress the warning about unsafe file permissions.  Note that the
-file permission checks that GnuPG does 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.
+</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>
@@ -2035,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>
 
 
@@ -2179,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>
 
@@ -2231,7 +2367,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.
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -2262,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>