* DETAILS: Document PLAINTEXT and PLAINTEXT_LENGTH.

* gpg.sgml: Clarify that --min-cert-level disregards level 1 certs by
default.  Clarify include-revoked a bit to note that keyservers might not
be accurate.  Note that --charset is --display-charset. Some language
tweaks for --simple-sk-checksum (Debian 251795). Note the PGP silliness
with preferred keyserver subpackets causing PGP/MIME.

doc/ChangeLog

@@ -1,3 +1,14 @@
+2004-06-28  David Shaw  <dshaw@jabberwocky.com>
+
+	* DETAILS: Document PLAINTEXT and PLAINTEXT_LENGTH.
+
+	* gpg.sgml: Clarify that --min-cert-level disregards level 1 certs
+	by default.  Clarify include-revoked a bit to note that keyservers
+	might not be accurate.  Note that --charset is --display-charset.
+	Some language tweaks for --simple-sk-checksum (Debian 251795).
+	Note the PGP silliness with preferred keyserver subpackets causing
+	PGP/MIME.
+
 2004-05-21  David Shaw  <dshaw@jabberwocky.com>
 
 	* gpg.sgml: Document --edit-key "keyserver" command,

doc/DETAILS

@@ -518,6 +518,20 @@ more arguments in future versions.
            2 = Request removal of a card.
            3 = Card with serialnumber detected
 
+    PLAINTEXT <format> <timestamp>
+        This indicates the format of the plaintext that is about to be
+        written.  The format is a 1 byte hex code that shows the
+        format of the plaintext: 62 ('b') is binary data, 74 ('t') is
+        text data with no character set specified, and 75 ('u') is
+        text data encoded in the UTF-8 character set.  The timestamp
+        is in seconds since the epoch.
+
+    PLAINTEXT_LENGTH <length>
+        This indicates the length of the plaintext that is about to be
+        written.  Note that if the plaintext packet has partial length
+        encoding it is not possible to know the length ahead of time.
+        In that case, this status tag does not appear.
+
 
 Format of the "--attribute-fd" output
 =====================================

doc/gpg.sgml

@@ -502,7 +502,9 @@ will not be used by GnuPG.
     <listitem><para>
 Set a preferred keyserver for the specified user ID(s).  This allows
 other users to know where you prefer they get your key from.  See
---keyserver-option honor-keyserver-url.
+--keyserver-option honor-keyserver-url.  Note that some versions of
+PGP interpret the presence of a keyserver URL as an instruction to
+enable PGP/MIME mail encoding.
 </para></listitem></varlistentry>
     <varlistentry>
     <term>toggle</term>
@@ -1052,8 +1054,8 @@ this option.  This option defaults to yes.
 <term>--min-cert-level</term>
 <listitem><para>
 When building the trust database, disregard any signatures with a
-certification level below this.  Defaults to 1, which accepts all
+certification level below this.  Defaults to 2, which disregards level
-signatures.
+1 signatures.
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -1178,9 +1180,12 @@ keyserver types, some common options are:
 <term>include-revoked</term>
 <listitem><para>
 When searching for a key with --search-keys, include keys that are
-marked on the keyserver as revoked.  Note that this option is always
+marked on the keyserver as revoked.  Note that not all keyservers
-set when using the NAI HKP keyserver, as this keyserver does not
+differentiate between revoked and unrevoked keys, and for such
-differentiate between revoked and unrevoked keys.
+keyservers this option is meaningless.  Note also that most keyservers
+do not have cryptographic verification of key revocations, and so
+turning this option off may result in skipping keys that are
+incorrectly marked as revoked.  Defaults to on.
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -1570,13 +1575,13 @@ $GNUPGHOME.
 
 
 <varlistentry>
-<term>--charset &ParmName;</term>
+<term>--display-charset &ParmName;</term>
 <listitem><para>
 Set the name of the native character set.  This is used to convert
 some informational strings like user IDs to the proper UTF-8
 encoding. 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>
+chosen set.  Valid values for &ParmName; are:</para>
 <variablelist>
 <varlistentry>
 <term>iso-8859-1</term><listitem><para>This is the Latin 1 set.</para></listitem>
@@ -1603,11 +1608,11 @@ that the OS uses native UTF-8 encoding.</para></listitem>
 <term>--utf8-strings</term>
 <term>--no-utf8-strings</term>
 <listitem><para>
-Assume that the arguments are already given as UTF8 strings.  The default
+Assume that command line arguments are given as UTF8 strings.  The
-(--no-utf8-strings)
+default (--no-utf8-strings) is to assume that arguments are encoded in
-is to assume that arguments are encoded in the character set as specified
+the character set as specified by --display-charset. These options
-by --charset. These options affect all following arguments.  Both options may
+affect all following arguments.  Both options may be used multiple
-be used multiple times.
+times.
 </para></listitem></varlistentry>
 
 
@@ -1732,9 +1737,9 @@ Put the name value pair into the signature as notation data.
 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
+encoded in UTF8, so you should check that your --display-charset is
-correctly.  If you prefix &ParmName; with an exclamation mark (!), the
+set correctly.  If you prefix &ParmName; with an exclamation mark (!),
-notation data will be flagged as critical (rfc2440:5.2.3.15).
+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.
@@ -1936,14 +1941,14 @@ conventional encryption.
 <term>--simple-sk-checksum</term>
 <listitem><para>
 Secret keys are integrity protected by using a SHA-1 checksum.  This
-method will be part of an enhanced OpenPGP specification but GnuPG
+method is part of the upcoming enhanced OpenPGP specification but
-already uses it as a countermeasure against certain attacks.  Old
+GnuPG already uses it as a countermeasure against certain attacks.
-applications don't understand this new format, so this option may be
+Old applications don't understand this new format, so this option may
-used to switch back to the old behaviour.  Using this this option
+be used to switch back to the old behaviour.  Using this option bears
-bears a security risk.  Note that using this option only takes effect
+a security risk.  Note that using this option only takes effect when
-when the secret key is encrypted - the simplest way to make this
+the secret key is encrypted - the simplest way to make this happen is
-happen is to change the passphrase on the key (even changing it to the
+to change the passphrase on the key (even changing it to the same
-same value is acceptable).
+value is acceptable).
 </para></listitem></varlistentry>
 
 
@@ -2368,11 +2373,11 @@ verification is not needed.
 <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.  This format is
+encoded in UTF-8 regardless of any --display-charset setting.  This
-useful when GnuPG is called from scripts and other programs as it is
+format is useful when GnuPG is called from scripts and other programs
-easily machine parsed.  The details of this format are documented in
+as it is easily machine parsed.  The details of this format are
-the file doc/DETAILS, which is included in the GnuPG source
+documented in the file doc/DETAILS, which is included in the GnuPG
-distribution.
+source distribution.
 </para></listitem></varlistentry>