From d38c4b20a56e2ccefa9fa6f2c4a3a336f71340b5 Mon Sep 17 00:00:00 2001
From: David Shaw <dshaw@jabberwocky.com>
Date: Thu, 8 Jan 2004 05:49:39 +0000
Subject: * 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 |  16 +++++++
 doc/gpg.sgml  | 134 ++++++++++++++++++++++++++++++++--------------------------
 2 files changed, 90 insertions(+), 60 deletions(-)

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 55f313d5a..9af161b5d 100644
--- a/doc/ChangeLog
+++ b/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
diff --git a/doc/gpg.sgml b/doc/gpg.sgml
index 46cba27e0..82f4e0552 100644
--- a/doc/gpg.sgml
+++ b/doc/gpg.sgml
@@ -1,6 +1,6 @@
 <!-- gpg.sgml - the man page for GnuPG
-    Copyright (C) 1998, 1999, 2000, 2001, 2002,
-                  2003 Free Software Foundation, Inc.
+    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003,
+                  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.
-For more verbose documentation get the GNU Privacy Handbook (GPH) or
-one of the other documents at http://www.gnupg.org/docs.html .
+This man page only lists the commands and options available.  For more
+verbose documentation get the GNU Privacy Handbook (GPH) or one of the
+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
-(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.
+Treat input files as text and store them in the OpenPGP canonical text
+form with standard "CRLF" line endings.  This also sets the necessary
+flags to inform the recipient that the encrypted or signed data is
+text and may need its line endings converted back to whatever the
+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
-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.
+Add &ParmFile; to the current 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 or $GNUPGHOME
+is not used).
+</para><para>
+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
-the filename does not contain a slash, it is assumed to be in the
-GnuPG home directory ("~/.gnupg" if --homedir is not used).
-
+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 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
-option is not used it defaults to "~/.gnupg". It does
-not make sense to use this in a options file. This
-also overrides the environment variable "GNUPGHOME".
+Set the name of the home directory to &ParmDir; If this option is not
+used it defaults to "~/.gnupg". It does not make sense to use this in
+a options file. This also overrides the environment variable
+$GNUPGHOME.
 </para></listitem></varlistentry>
 
 
 <varlistentry>
 <term>--charset &ParmName;</term>
 <listitem><para>
-Set the name of the native character set.  This is used
-to convert some strings to 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>
+Set the name of the native character set.  This is used to convert
+some strings to 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>
 <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
-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.
+If you prefix it with an exclamation mark (!), the policy URL packet
+will be flagged as critical.  --sig-policy-url sets a policy url for
+data signatures.  --cert-policy-url sets a policy url for key
+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
-keyrings.
+Do not add the default keyrings to the list of keyrings.  Note that
+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.
-This options enables a workaround by checking faulty signatures again with
-the encoding used in old versions.  This may only happen for ElGamal signatures
-which are not widely used.
+GnuPG versions prior to 1.0.2 had a bug in the way a signature was
+encoded.  This options enables a workaround by checking faulty
+signatures again with the encoding used in old versions.  This may
+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
-fingerprints.  This flag tells GnuPG to use exactly the given primary
-or secondary key and not to try to figure out which secondary or
-primary key to use.
+Note that you can append an exclamation mark (!) to key IDs or
+fingerprints.  This flag tells GnuPG to use the specified primary or
+secondary key and not to try and calculate which primary or secondary
+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
-system that will always do the right thing and create messages that
-are usable by all recipients, regardless of which OpenPGP program they
-use.  Only override this safe default if you know what you are doing.
+compression algorithm.  By default, GnuPG uses the standard OpenPGP
+preferences system that will always do the right thing and create
+messages that are usable by all recipients, regardless of which
+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
-options are safe as they do not force any particular algorithms in
-violation of OpenPGP, but rather reduce the available algorithms to a
-"PGP-safe" list.
+better off using the --pgp6, --pgp7, or --pgp8 options.  These options
+are safe as they do not force any particular algorithms in violation
+of OpenPGP, but rather reduce the available algorithms to a "PGP-safe"
+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
-operating system from writing memory pages to disk. If you get no
+is necessary to lock memory pages.  Locking memory pages prevents the
+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>
-- 
cgit v1.2.3