* gpg.sgml: Fix a few minor typos. Clarify what --textmode is useful for.

* gpg.sgml: List proper documentation URL.  Note that addrevoker takes an
optional "sensitive" argument.  Remind that $GNUPGHOME can be used instead
of --homedir.  Clarify --no-default-keyring, and note why it may not take
effect if there are no other keyrings present.  Remove --pgp2 from the
list of --pgpXes that are just for bad preference lists.  Explain more why
locking memory pages is good.

* gpg.sgml: Add an example of what an exclamation mark is, as people seem
to miss it often.

doc/ChangeLog

@@ -1,3 +1,19 @@
+2004-01-07  David Shaw  <dshaw@jabberwocky.com>
+
+	* gpg.sgml: Fix a few minor typos.  Clarify what --textmode is
+	useful for.
+
+	* gpg.sgml: List proper documentation URL.  Note that addrevoker
+	takes an optional "sensitive" argument.  Remind that $GNUPGHOME
+	can be used instead of --homedir.  Clarify --no-default-keyring,
+	and note why it may not take effect if there are no other keyrings
+	present.  Remove --pgp2 from the list of --pgpXes that are just
+	for bad preference lists.  Explain more why locking memory pages
+	is good.
+
+	* gpg.sgml: Add an example of what an exclamation mark is, as
+	people seem to miss it often.
+
 2003-12-08  David Shaw  <dshaw@jabberwocky.com>
 
 	* gpg.sgml: Fix a few missing semicolons in & entities.  Noted by

doc/gpg.sgml

@@ -1,6 +1,6 @@
 <!-- gpg.sgml - the man page for GnuPG
-    Copyright (C) 1998, 1999, 2000, 2001, 2002,
+    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003,
-                  2003 Free Software Foundation, Inc.
+                  2004 Free Software Foundation, Inc.
 
     This file is part of GnuPG.
 
@@ -74,9 +74,9 @@
 <command/gpg/ is the main program for the GnuPG system.
     </para>
     <para>
-This man page only lists the commands and options available.
+This man page only lists the commands and options available.  For more
-For more verbose documentation get the GNU Privacy Handbook (GPH) or
+verbose documentation get the GNU Privacy Handbook (GPH) or one of the
-one of the other documents at http://www.gnupg.org/docs.html .
+other documents at http://www.gnupg.org/documentation/ .
 </para>
 <para>
 Please remember that option parsing stops as soon as a non option is
@@ -395,7 +395,7 @@ Add a subkey to this key.</para></listitem></varlistentry>
     <listitem><para>
 Remove a subkey.</para></listitem></varlistentry>
     <varlistentry>
-    <term>addrevoker</term>
+    <term>addrevoker <optional>sensitive</optional></term>
     <listitem><para>
 Add a designated revoker.  This takes one optional argument:
 "sensitive".  If a designated revoker is marked as sensitive, it will
@@ -934,11 +934,20 @@ circumstances when the file was originally compressed at a high
 <term>-t, --textmode</term>
 <term>--no-textmode</term>
 <listitem><para>
-Use canonical text mode.  --no-textmode disables this option.  If -t
+Treat input files as text and store them in the OpenPGP canonical text
-(but not --textmode) is used together with armoring and signing, this
+form with standard "CRLF" line endings.  This also sets the necessary
-enables clearsigned messages.  This kludge is needed for command-line
+flags to inform the recipient that the encrypted or signed data is
-compatibility with command-line versions of PGP; normally you would
+text and may need its line endings converted back to whatever the
-use --sign or --clearsign to select the type of the signature.
+local system uses.  This option is useful when communicating between
+two platforms that have different line ending conventions (UNIX-like
+to Mac, Mac to Windows, etc).  --no-textmode disables this option, and
+is the default.
+</para><para>
+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>
 
 
@@ -1424,13 +1433,15 @@ keyring a given key resides on.  This option is deprecated: use
 <varlistentry>
 <term>--keyring &ParmFile;</term>
 <listitem><para>
-Add &ParmFile; to the list of keyrings.  If &ParmFile; begins with a
+Add &ParmFile; to the current list of keyrings.  If &ParmFile; begins
-tilde and a slash, these are replaced by the HOME directory. If the
+with a tilde and a slash, these are replaced by the $HOME
-filename does not contain a slash, it is assumed to be in the GnuPG
+directory. If the filename does not contain a slash, it is assumed to
-home directory ("~/.gnupg" if --homedir is not used).  The filename
+be in the GnuPG home directory ("~/.gnupg" if --homedir or $GNUPGHOME
-may be prefixed with a scheme:</para>
+is not used).
-<para>"gnupg-ring:" is the default one.</para>
+</para><para>
-<para>It might make sense to use it together with --no-default-keyring.
+Note that this adds a keyring to the current list.  If the intent is
+to use the specified keyring alone, use --keyring along with
+--no-default-keyring.
 </para></listitem></varlistentry>
 
 
@@ -1451,32 +1462,32 @@ this keyring.
 <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
+with a tilde and a slash, these are replaced by the $HOME
-the filename does not contain a slash, it is assumed to be in the
+directory. If the filename does not contain a slash, it is assumed to
-GnuPG home directory ("~/.gnupg" if --homedir is not used).
+be in the GnuPG home directory ("~/.gnupg" if --homedir or $GNUPGHOME
-
+is not used).
 </para></listitem></varlistentry>
 
 
 <varlistentry>
 <term>--homedir &ParmDir;</term>
 <listitem><para>
-Set the name of the home directory to &ParmDir; If this
+Set the name of the home directory to &ParmDir; If this option is not
-option is not used it defaults to "~/.gnupg". It does
+used it defaults to "~/.gnupg". It does not make sense to use this in
-not make sense to use this in a options file. This
+a options file. This also overrides the environment variable
-also overrides the environment variable "GNUPGHOME".
+$GNUPGHOME.
 </para></listitem></varlistentry>
 
 
 <varlistentry>
 <term>--charset &ParmName;</term>
 <listitem><para>
-Set the name of the native character set.  This is used
+Set the name of the native character set.  This is used to convert
-to convert some strings to proper UTF-8 encoding. If this option is not used, the default character set is determined
+some strings to proper UTF-8 encoding. If this option is not used, the
-from the current locale.  A verbosity level of 3 shows the used one.
+default character set is determined from the current locale.  A
-Valid values for &ParmName; are:</para>
+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 Latin 1 set.</para></listitem>
@@ -1633,7 +1644,7 @@ 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
+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
@@ -1664,17 +1675,16 @@ 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 a Policy URL for signatures (rfc2440:5.2.3.19).
-If you prefix it with an exclamation mark, the policy URL packet will
+If you prefix it with an exclamation mark (!), the policy URL packet
-be flagged as critical.  --sig-policy-url sets a a policy url for data
+will be flagged as critical.  --sig-policy-url sets a policy url for
-signatures.  --cert-policy-url sets a policy url for key signatures
+data signatures.  --cert-policy-url sets a policy url for key
-(certifications).  --set-policy-url sets both.
+signatures (certifications).  --set-policy-url sets both.
 </para><para>
 The same %-expandos used for notation data are available here as well.
 </para></listitem></varlistentry>
@@ -2217,7 +2227,6 @@ Suppress the warning about "using insecure memory".
 <varlistentry>
 <term>--no-permission-warning</term>
 <listitem><para>
-
 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
@@ -2248,8 +2257,11 @@ Assume the input data is not in ASCII armored format.
 <varlistentry>
 <term>--no-default-keyring</term>
 <listitem><para>
-Do not add the default keyrings to the list of
+Do not add the default keyrings to the list of keyrings.  Note that
-keyrings.
+GnuPG will not operate without any keyrings, so if you use this option
+and do not provide alternate keyrings via --keyring or
+--secret-keyring, then GnuPG will still use the default public or
+secret keyrings.
 </para></listitem></varlistentry>
 
 
@@ -2328,10 +2340,10 @@ This is not for normal use.  Use the source to see for what it might be useful.
 <varlistentry>
 <term>--emulate-md-encode-bug</term>
 <listitem><para>
-GnuPG versions prior to 1.0.2 had a bug in the way a signature was encoded.
+GnuPG versions prior to 1.0.2 had a bug in the way a signature was
-This options enables a workaround by checking faulty signatures again with
+encoded.  This options enables a workaround by checking faulty
-the encoding used in old versions.  This may only happen for ElGamal signatures
+signatures again with the encoding used in old versions.  This may
-which are not widely used.
+only happen for Elgamal signatures which are not widely used.
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -2583,10 +2595,10 @@ in front.
     </variablelist>
 
     <para>
-Note that you can append an exclamation mark to key IDs or
+Note that you can append an exclamation mark (!) to key IDs or
-fingerprints.  This flag tells GnuPG to use exactly the given primary
+fingerprints.  This flag tells GnuPG to use the specified primary or
-or secondary key and not to try to figure out which secondary or
+secondary key and not to try and calculate which primary or secondary
-primary key to use.
+key to use.
     </para>
 
 </refsect1>
@@ -2777,22 +2789,23 @@ cannot be read by the intended recipient.
 </para>
 
 <para>
-For example, as of this writing, no version of official PGP supports
+For example, as of this writing, no (unhacked) version of 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
+compression algorithm.  By default, GnuPG uses the standard OpenPGP
-system that will always do the right thing and create messages that
+preferences system that will always do the right thing and create
-are usable by all recipients, regardless of which OpenPGP program they
+messages that are usable by all recipients, regardless of which
-use.  Only override this safe default if you know what you are doing.
+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
+better off using the --pgp6, --pgp7, or --pgp8 options.  These options
-options are safe as they do not force any particular algorithms in
+are safe as they do not force any particular algorithms in violation
-violation of OpenPGP, but rather reduce the available algorithms to a
+of OpenPGP, but rather reduce the available algorithms to a "PGP-safe"
-"PGP-safe" list.
+list.
 </para>
 
 </refsect1>
@@ -2802,10 +2815,11 @@ violation of OpenPGP, but rather reduce the available algorithms to a
     <title>BUGS</title>
     <para>
 On many systems this program should be installed as setuid(root). This
-is necessary to lock memory pages. Locking memory pages prevents the
+is necessary to lock memory pages.  Locking memory pages prevents the
-operating system from writing memory pages to disk. If you get no
+operating system from writing memory pages (which may contain
+passphrases or other sensitive material) to disk.  If you get no
 warning message about insecure memory your operating system supports
-locking without being root. The program drops root privileges as soon
+locking without being root.  The program drops root privileges as soon
 as locked memory is allocated.
 </para>
 </refsect1>