Provide default strings for the pinentry.
[gnupg.git] / doc / gpg.texi
index 1f59e40..5aec7a8 100644 (file)
@@ -1,5 +1,5 @@
-@c Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
-@c               2007 Free Software Foundation, Inc.
+@c Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
+@c               2008, 2009 Free Software Foundation, Inc.
 @c This is part of the GnuPG manual.
 @c For copying conditions, see the file gnupg.texi.
 
@@ -149,7 +149,7 @@ cannot abbreviate this command.
 @itemx -h
 @opindex help
 Print a usage message summarizing the most useful command line options.
-Not that you cannot abbreviate this command.
+Note that you cannot abbreviate this command.
 
 @item --warranty
 @opindex warranty
@@ -226,8 +226,8 @@ Store only (make a simple RFC1991 literal data packet).
 @item --decrypt
 @itemx -d
 @opindex decrypt
-Decrypt the file given on the command line (or @code{stdin} if no file
-is specified) and write it to stdout (or the file specified with
+Decrypt the file given on the command line (or STDIN if no file
+is specified) and write it to STDOUT (or the file specified with
 @option{--output}). If the decrypted file is signed, the signature is also
 verified. This command differs from the default operation, as it never
 writes to the filename which is included in the file and it rejects
@@ -237,19 +237,19 @@ files which don't begin with an encrypted message.
 @opindex verify
 Assume that the first argument is a signed file or a detached signature
 and verify it without generating any output. With no arguments, the
-signature packet is read from stdin. If only a sigfile is given, it may
+signature packet is read from STDIN. If only a sigfile is given, it may
 be a complete signature or a detached signature, in which case the
 signed stuff is expected in a file without the ".sig" or ".asc"
 extension.  With more than 1 argument, the first should be a detached
 signature and the remaining files are the signed stuff. To read the
-signed stuff from stdin, use @samp{-} as the second filename.  For
+signed stuff from STDIN, use @samp{-} as the second filename.  For
 security reasons a detached signature cannot read the signed material
-from stdin without denoting it in the above way.
+from STDIN without denoting it in the above way.
 
 @item --multifile
 @opindex multifile
 This modifies certain other commands to accept multiple files for
-processing on the command line or read from stdin with each filename on
+processing on the command line or read from STDIN with each filename on
 a separate line. This allows for many files to be processed at
 once. @option{--multifile} may currently be used along with
 @option{--verify}, @option{--encrypt}, and @option{--decrypt}. Note that
@@ -328,7 +328,7 @@ The status of the verification is indicated by a flag directly following
 the "sig" tag (and thus before the flags described above for
 @option{--list-sigs}).  A "!" indicates that the signature has been
 successfully verified, a "-" denotes a bad signature and a "%" is used
-if an error occured while checking the signature (e.g. a non supported
+if an error occurred while checking the signature (e.g. a non supported
 algorithm).
 
 @ifclear gpgone
@@ -394,7 +394,7 @@ removed first. In batch mode the key must be specified by fingerprint.
 @opindex export
 Either export all keys from all keyrings (default keyrings and those
 registered via option @option{--keyring}), or if at least one name is given,
-those of the given name. The new keyring is written to stdout or to the
+those of the given name. The new keyring is written to STDOUT or to the
 file given with option @option{--output}. Use together with
 @option{--armor} to mail those keys.
 
@@ -404,7 +404,7 @@ Similar to @option{--export} but sends the keys to a keyserver.
 Fingerprints may be used instead of key IDs. Option @option{--keyserver}
 must be used to give the name of this keyserver. Don't send your
 complete keyring to a keyserver --- select only those keys which are new
-or changed by you.
+or changed by you.  If no key IDs are given, @command{gpg} does nothing.
 
 @item --export-secret-keys
 @itemx --export-secret-subkeys
@@ -425,7 +425,7 @@ Import/merge keys. This adds the given keys to the
 keyring. The fast version is currently just a synonym.
 
 There are a few other options which control how this command works.
-Most notable here is the @option{--keyserver-options merge-only} option
+Most notable here is the @option{--import-options merge-only} option
 which does not insert new keys but does only the merging of new
 signatures, user-IDs and subkeys.
 
@@ -485,16 +485,34 @@ For use with cron jobs, this command can be used together with
 a check is needed. To force a run even in batch mode add the option
 @option{--yes}.
 
+@anchor{option --export-ownertrust}
 @item --export-ownertrust
 @opindex export-ownertrust
-Send the ownertrust values to stdout. This is useful for backup purposes
+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.
+corrupted trustdb.  Example:
+@c man:.RS
+@example
+  @gpgname{} --export-ownertrust > otrust.txt
+@end example
+@c man:.RE
+
 
 @item --import-ownertrust
 @opindex import-ownertrust
 Update the trustdb with the ownertrust values stored in @code{files} (or
-stdin if not given); existing values will be overwritten.
+STDIN if not given); existing values will be overwritten.  In case of a
+severely damaged trustdb and if you have a recent backup of the
+ownertrust values (e.g. in the file @file{otrust.txt}, you may re-create
+the trustdb using these commands:
+@c man:.RS
+@example
+  cd ~/.gnupg
+  rm trustdb.gpg
+  @gpgname{} --import-ownertrust < otrust.txt
+@end example
+@c man:.RE
+
 
 @item --rebuild-keydb-caches
 @opindex rebuild-keydb-caches
@@ -505,7 +523,7 @@ situations too.
 @item --print-md @code{algo}
 @itemx --print-mds
 @opindex print-md
-Print message digest of algorithm ALGO for all given files or stdin.
+Print message digest of algorithm ALGO for all given files or STDIN.
 With the second form (or a deprecated "*" as algo) digests for all
 available algorithms are printed.
 
@@ -571,6 +589,16 @@ line.
 @c ******** Begin Edit-key Options **********
 @table @asis
 
+@item uid @code{n}
+@opindex keyedit:uid
+Toggle selection of user ID or photographic user ID with index @code{n}.
+Use @code{*} to select all and @code{0} to deselect all.
+
+@item key @code{n}
+@opindex keyedit:key
+Toggle selection of subkey with index @code{n}.
+Use @code{*} to select all and @code{0} to deselect all.
+
 @item sign
 @opindex keyedit:sign
 Make a signature on key of user @code{name} If the key is not yet
@@ -607,51 +635,108 @@ create a signature of any type desired.
 
 @table @asis
 
+@item delsig
+@opindex keyedit:delsig
+Delete a signature. Note that it is not possible to retract a signature,
+once it has been send to the public (i.e. to a keyserver).  In that case
+you better use @code{revsig}.
+
 @item revsig
 @opindex keyedit:revsig
 Revoke a signature. For every signature which has been generated by
 one of the secret keys, GnuPG asks whether a revocation certificate
 should be generated.
 
-@item trust
-@opindex keyedit:trust
-Change the owner trust value. This updates the
-trust-db immediately and no save is required.
-
-@item disable
-@itemx enable
-@opindex keyedit:disable
-@opindex keyedit:enable
-Disable or enable an entire key. A disabled key can not normally be
-used for encryption.
+@item check
+@opindex keyedit:check
+Check the signatures on all selected user IDs.
 
 @item adduid
 @opindex keyedit:adduid
-Create an alternate user id.
+Create an additional user ID.
 
 @item addphoto
 @opindex keyedit:addphoto
-Create a photographic user id. This will prompt for a JPEG file that
+Create a photographic user ID. This will prompt for a JPEG file that
 will be embedded into the user ID. Note that a very large JPEG will make
 for a very large key. Also note that some programs will display your
 JPEG unchanged (GnuPG), and some programs will scale it to fit in a
 dialog box (PGP).
 
+@item showphoto
+@opindex keyedit:showphoto
+Display the selected photographic user ID.
+
 @item deluid
 @opindex keyedit:deluid
-Delete a user id.  Note that it is not possible to retract a user id,
-once it has been send to the public (i.e. to a keyserver).  In that case
-you better use @code{revuid}.
-
-@item delsig
-@opindex keyedit:delsig
-Delete a signature. Note that it is not possible to retract a signature,
-once it has been send to the public (i.e. to a keyserver).  In that case
-you better use @code{revsig}.
+Delete a user ID or photographic user ID.  Note that it is not
+possible to retract a user id, once it has been send to the public
+(i.e. to a keyserver).  In that case you better use @code{revuid}.
 
 @item revuid
 @opindex keyedit:revuid
-Revoke a user id.
+Revoke a user ID or photographic user ID.
+
+@item primary
+@opindex keyedit:primary
+Flag the current user id as the primary one, removes the primary user
+id flag from all other user ids and sets the timestamp of all affected
+self-signatures one second ahead. Note that setting a photo user ID
+as primary makes it primary over other photo user IDs, and setting a
+regular user ID as primary makes it primary over other regular user
+IDs.
+
+@item keyserver
+@opindex keyedit:keyserver
+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
+@option{--keyserver-options honor-keyserver-url} for more on how this
+works.  Setting a value of "none" removes an existing preferred
+keyserver.
+
+@item notation
+@opindex keyedit:notation
+Set a name=value notation for the specified user ID(s). See
+@option{--cert-notation} for more on how this works. Setting a value of
+"none" removes all notations, setting a notation prefixed with a minus
+sign (-) removes that notation, and setting a notation name (without the
+=value) prefixed with a minus sign removes all notations with that name.
+
+@item pref
+@opindex keyedit:pref
+List preferences from the selected user ID. This shows the actual
+preferences, without including any implied preferences.
+
+@item showpref
+@opindex keyedit:showpref
+More verbose preferences listing for the selected user ID. This shows
+the preferences in effect by including the implied preferences of 3DES
+(cipher), SHA-1 (digest), and Uncompressed (compression) if they are
+not already included in the preference list. In addition, the
+preferred keyserver and signature notations (if any) are shown.
+
+@item setpref @code{string}
+@opindex keyedit:setpref
+Set the list of user ID preferences to @code{string} for all (or just
+the selected) user IDs. Calling setpref with no arguments sets the
+preference list to the default (either built-in or set via
+@option{--default-preference-list}), and calling setpref with "none"
+as the argument sets an empty preference list. Use @command{@gpgname
+--version} to get a list of available algorithms. Note that while you
+can change the preferences on an attribute user ID (aka "photo ID"),
+GnuPG does not select keys via attribute user IDs so these preferences
+will not be used by GnuPG.
+
+When setting preferences, you should list the algorithms in the order
+which you'd like to see them used by someone else when encrypting a
+message to your key.  If you don't include 3DES, it will be
+automatically added at the end.  Note that there are many factors that
+go into choosing an algorithm (for example, your key may not be the
+only recipient), and so the remote OpenPGP application being used to
+send to you may or may not follow your exact chosen order for a given
+message.  It will, however, only choose an algorithm that is present
+on the preference list of every recipient key.  See also the
+INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS section below.
 
 @item addkey
 @opindex keyedit:addkey
@@ -659,18 +744,18 @@ Add a subkey to this key.
 
 @item addcardkey
 @opindex keyedit:addcardkey
-Generate a key on a card and add it to this key.
+Generate a subkey on a card and add it to this key.
 
 @item keytocard
 @opindex keyedit:keytocard
-Transfer the selected secret key (or the primary key if no key has been
-selected) to a smartcard. The secret key in the keyring will be replaced
-by a stub if the key could be stored successfully on the card and you
-use the save command later. Only certain key types may be transferred to
-the card. A sub menu allows you to select on what card to store the
-key. Note that it is not possible to get that key back from the card -
-if the card gets broken your secret key will be lost unless you have a
-backup somewhere.
+Transfer the selected secret subkey (or the primary key if no subkey
+has been selected) to a smartcard. The secret key in the keyring will
+be replaced by a stub if the key could be stored successfully on the
+card and you use the save command later. Only certain key types may be
+transferred to the card. A sub menu allows you to select on what card
+to store the key. Note that it is not possible to get that key back
+from the card - if the card gets broken your secret key will be lost
+unless you have a backup somewhere.
 
 @item bkuptocard @code{file}
 @opindex keyedit:bkuptocard
@@ -688,94 +773,37 @@ Remove a subkey (secondart key). Note that it is not possible to retract
 a subkey, once it has been send to the public (i.e. to a keyserver).  In
 that case you better use @code{revkey}.
 
-@item addrevoker
-@opindex keyedit:addrevoker
-Add a designated revoker. This takes one optional argument:
-"sensitive". If a designated revoker is marked as sensitive, it will not
-be exported by default (see export-options).
-
 @item revkey
 @opindex keyedit:revkey
 Revoke a subkey.
 
 @item expire
 @opindex keyedit:expire
-Change the key expiration time. If a subkey is selected, the
-expiration time of this subkey will be changed. With no selection,
-the key expiration of the primary key is changed.
-
-@item passwd
-@opindex keyedit:passwd
-Change the passphrase of the secret key.
+Change the key or subkey expiration time. If a subkey is selected, the
+expiration time of this subkey will be changed. With no selection, the
+key expiration of the primary key is changed.
 
-@item primary
-@opindex keyedit:primary
-Flag the current user id as the primary one, removes the primary user
-id flag from all other user ids and sets the timestamp of all affected
-self-signatures one second ahead. Note that setting a photo user ID
-as primary makes it primary over other photo user IDs, and setting a
-regular user ID as primary makes it primary over other regular user
-IDs.
-
-@item uid @code{n}
-@opindex keyedit:uid
-Toggle selection of user id with index @code{n}.
-Use 0 to deselect all.
-
-@item key @code{n}
-@opindex keyedit:key
-Toggle selection of subkey with index @code{n}.
-Use 0 to deselect all.
-
-@item check
-@opindex keyedit:check
-Check all selected user ids.
-
-@item showphoto
-@opindex keyedit:showphoto
-Display the selected photographic user
-id.
-
-@item pref
-@opindex keyedit:pref
-List preferences from the selected user ID. This shows the actual
-preferences, without including any implied preferences.
-
-@item showpref
-@opindex keyedit:showpref
-More verbose preferences listing for the selected user ID. This shows
-the preferences in effect by including the implied preferences of 3DES
-(cipher), SHA-1 (digest), and Uncompressed (compression) if they are
-not already included in the preference list. In addition, the
-preferred keyserver and signature notations (if any) are shown.
+@item trust
+@opindex keyedit:trust
+Change the owner trust value for the key. This updates the trust-db
+immediately and no save is required.
 
-@item setpref @code{string}
-@opindex keyedit:setpref
-Set the list of user ID preferences to @code{string} for all (or just
-the selected) user IDs. Calling setpref with no arguments sets the
-preference list to the default (either built-in or set via
-@option{--default-preference-list}), and calling setpref with "none" as
-the argument sets an empty preference list. Use @command{@gpgname
---version} to get a list of available algorithms. Note that while you
-can change the preferences on an attribute user ID (aka "photo ID"),
-GnuPG does not select keys via attribute user IDs so these preferences
-will not be used by GnuPG.
+@item disable
+@itemx enable
+@opindex keyedit:disable
+@opindex keyedit:enable
+Disable or enable an entire key. A disabled key can not normally be
+used for encryption.
 
-@item keyserver
-@opindex keyedit:keyserver
-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
-@option{--keyserver-options honor-keyserver-url} for more on how this
-works.  Setting a value of "none" removes an existing preferred
-keyserver.
+@item addrevoker
+@opindex keyedit:addrevoker
+Add a designated revoker to the key. This takes one optional argument:
+"sensitive". If a designated revoker is marked as sensitive, it will
+not be exported by default (see export-options).
 
-@item notation
-@opindex keyedit:notation
-Set a name=value notation for the specified user ID(s). See
-@option{--cert-notation} for more on how this works. Setting a value of
-"none" removes all notations, setting a notation prefixed with a minus
-sign (-) removes that notation, and setting a notation name (without the
-=value) prefixed with a minus sign removes all notations with that name.
+@item passwd
+@opindex keyedit:passwd
+Change the passphrase of the secret key.
 
 @item toggle
 @opindex keyedit:toggle
@@ -800,7 +828,9 @@ each user ID except for the most recent self-signature.
 Add cross-certification signatures to signing subkeys that may not
 currently have them. Cross-certification signatures protect against a
 subtle attack against signing subkeys. See
-@option{--require-cross-certification}.
+@option{--require-cross-certification}.  All new keys generated have
+this signature by default, so this option is only useful to bring
+older keys up to date.
 
 @item save
 @opindex keyedit:save
@@ -858,6 +888,13 @@ Signs a public key with your secret key but marks it as
 non-exportable. This is a shortcut version of the subcommand "lsign"
 from @option{--edit-key}.
 
+@ifclear gpgone
+@item --passwd @var{user_id}
+@opindex passwd
+Change the passphrase of the secret key belonging to the certificate
+specified as @var{user_id}.  This is a shortcut for the sub-command
+@code{passwd} of the edit key menu.
+@end ifclear
 
 @end table
 
@@ -871,7 +908,7 @@ from @option{--edit-key}.
 @node GPG Options
 @section Option Summary
 
-@command{@gpgname} comes features a bunch of options to control the exact
+@command{@gpgname} features a bunch of options to control the exact
 behaviour and to change the default configuration.
 
 @menu
@@ -946,7 +983,12 @@ Try to be as quiet as possible.
 @opindex batch
 @opindex no-batch
 Use batch mode.  Never ask, do not allow interactive commands.
-@option{--no-batch} disables this option.
+@option{--no-batch} disables this option.  Note that even with a
+filename given on the command line, gpg might still need to read from
+STDIN (in particular if gpg figures that the input is a
+detached signature and no data file has been specified).  Thus if you
+do not want to feed data via STDIN, you should connect STDIN to
+@file{/dev/null}.
 
 @item --no-tty
 @opindex no-tty
@@ -1077,10 +1119,10 @@ validation. This option is only meaningful if pka-lookups is set.
 
 @item --enable-dsa2
 @itemx --disable-dsa2
-Enables new-style DSA keys which (unlike the old style) may be larger
-than 1024 bit and use hashes other than SHA-1 and RIPEMD/160. Note
-that very few programs currently support these keys and signatures
-from them.
+Enable hash truncation for all DSA keys even for old DSA Keys up to
+1024 bit.  This is also the default with @option{--openpgp}.  Note
+that older versions of GnuPG also required this flag to allow the
+generation of DSA larger than 1024 bit.
 
 @item --photo-viewer @code{string}
 This is the command line that should be run to view a photo ID. "%i"
@@ -1093,7 +1135,7 @@ 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". Note that if your image viewer program is not secure, then
+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}
@@ -1342,8 +1384,9 @@ Locate a key using DNS CERT, as specified in rfc4398.
 Locate a key using DNS PKA.
 
 @item ldap
-Locate a key using the PGP Universal method of checking
-@samp{ldap://keys.(thedomain)}.
+Using DNS Service Discovery, check the domain in question for any LDAP
+keyservers to use.  If this fails, attempt to locate the key using the
+PGP Universal method of checking @samp{ldap://keys.(thedomain)}.
 
 @item keyserver
 Locate a key using whatever keyserver is defined using the
@@ -1394,11 +1437,11 @@ keyserver each time you use it.
 
 @item --keyserver-options @code{name=value1 }
 This is a space or comma delimited string that gives options for the
-keyserver. Options can be prepended with a `no-' to give the opposite
-meaning. Valid import-options or export-options may be used here as well
-to apply to importing (@option{--recv-key}) or exporting
-(@option{--send-key}) a key from a keyserver. While not all options are
-available for all keyserver types, some common options are:
+keyserver. Options can be prefixed with a `no-' to give the opposite
+meaning. Valid import-options or export-options may be used here as
+well to apply to importing (@option{--recv-key}) or exporting
+(@option{--send-key}) a key from a keyserver. While not all options
+are available for all keyserver types, some common options are:
 
 @table @asis
 
@@ -1474,6 +1517,24 @@ Set the proxy to use for HTTP and HKP keyservers.  This overrides the
 @item max-cert-size
 When retrieving a key via DNS CERT, only accept keys up to this size.
 Defaults to 16384 bytes.
+
+@item debug
+Turn on debug output in the keyserver helper program.  Note that the
+details of debug output depends on which keyserver helper program is
+being used, and in turn, on any libraries that the keyserver helper
+program uses internally (libcurl, openldap, etc).
+
+@item check-cert
+Enable certificate checking if the keyserver presents one (for hkps or
+ldaps).  Defaults to on.
+
+@item ca-cert-file
+Provide a certificate store to override the system default.  Only
+necessary if check-cert is enabled, and the keyserver is using a
+certificate that is not present in a system default certificate list.
+
+Note that depending on the SSL library that the keyserver helper is
+built with, this may actually be a directory or a file.
 @end table
 
 @item --completes-needed @code{n}
@@ -1707,14 +1768,24 @@ Use @var{name} as the key to sign with. Note that this option overrides
 @option{--default-key}.
 
 @item --try-all-secrets
+@opindex try-all-secrets
 Don't look at the key ID as stored in the message but try all secret
 keys in turn to find the right decryption key. This option forces the
 behaviour as used by anonymous recipients (created by using
 @option{--throw-keyids}) and might come handy in case where an encrypted
 message contains a bogus key ID.
 
-
-
+@item --skip-hidden-recipients
+@itemx --no-skip-hidden-recipients
+@opindex skip-hidden-recipients
+@opindex no-skip-hidden-recipients
+During decryption skip all anonymous recipients.  This option helps in
+the case that people use the hidden recipients feature to hide there
+own encrypt-to key from others.  If oneself has many secret keys this
+may lead to a major annoyance because all keys are tried in turn to
+decrypt soemthing which was not really intended for it.  The drawback
+of this option is that it is currently not possible to decrypt a
+message which includes real anonymous recipients.
 
 
 @end table
@@ -1917,17 +1988,19 @@ message modification attack.
 Set the list of personal cipher preferences to @code{string}.  Use
 @command{@gpgname --version} to get a list of available algorithms,
 and use @code{none} to set no preference at all.  This allows the user
-to factor in their own preferred algorithms when algorithms are chosen
-via recipient key preferences.  The most highly ranked cipher in this
-list is also used for the @option{--symmetric} encryption command.
+to safely override the algorithm chosen by the recipient key
+preferences, as GPG will only select an algorithm that is usable by
+all recipients.  The most highly ranked cipher in this list is also
+used for the @option{--symmetric} encryption command.
 
 @item --personal-digest-preferences @code{string}
 Set the list of personal digest preferences to @code{string}.  Use
 @command{@gpgname --version} to get a list of available algorithms,
 and use @code{none} to set no preference at all.  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
+to safely override the algorithm chosen by the recipient key
+preferences, as GPG will only select an algorithm that is usable by
+all recipients.  The most highly ranked digest algorithm in this list
+is also used when signing without encryption
 (e.g. @option{--clearsign} or @option{--sign}). The default value is
 SHA-1.
 
@@ -1935,10 +2008,11 @@ SHA-1.
 Set the list of personal compression preferences to @code{string}.
 Use @command{@gpgname --version} to get a list of available
 algorithms, and use @code{none} to set no preference at all.  This
-allows the user to factor in their own preferred algorithms when
-algorithms are chosen via recipient key preferences.  The most highly
-ranked compression algorithm in this list is algo used when there are
-no recipient keys to consider (e.g. @option{--symmetric}).
+allows the user to safely override the algorithm chosen by the
+recipient key preferences, as GPG will only select an algorithm that
+is usable by all recipients.  The most highly ranked compression
+algorithm in this list is also used when there are no recipient keys
+to consider (e.g. @option{--symmetric}).
 
 @item --s2k-cipher-algo @code{name}
 Use @code{name} as the cipher algorithm used to protect secret keys.
@@ -2021,9 +2095,9 @@ a message that PGP 2.x will not be able to handle. Note that `PGP
 available, but the MIT release is a good common baseline.
 
 This option implies @option{--rfc1991 --disable-mdc
---no-force-v4-certs --no-sk-comment --escape-from-lines
---force-v3-sigs --cipher-algo IDEA --digest-algo MD5 --compress-algo
-ZIP}. It also disables @option{--textmode} when encrypting.
+--no-force-v4-certs --escape-from-lines --force-v3-sigs --cipher-algo
+IDEA --digest-algo MD5 --compress-algo ZIP}. It also disables
+@option{--textmode} when encrypting.
 
 @item --pgp6
 @opindex pgp6
@@ -2034,8 +2108,8 @@ compression algorithms none and ZIP. This also disables
 --throw-keyids, and making signatures with signing subkeys as PGP 6
 does not understand signatures made by signing subkeys.
 
-This option implies @option{--disable-mdc --no-sk-comment
---escape-from-lines --force-v3-sigs}.
+This option implies @option{--disable-mdc --escape-from-lines
+--force-v3-sigs}.
 
 @item --pgp7
 @opindex pgp7
@@ -2079,6 +2153,34 @@ therefore enables a fast listing of the encryption keys.
 @opindex interactive
 Prompt before overwriting any files.
 
+@item --debug-level @var{level}
+@opindex debug-level
+Select the debug level for investigating problems. @var{level} may be
+a numeric value or by a keyword:
+
+@table @code
+@item none
+No debugging at all.  A value of less than 1 may be used instead of
+the keyword.
+@item basic  
+Some basic debug messages.  A value between 1 and 2 may be used
+instead of the keyword.
+@item advanced
+More verbose debug messages.  A value between 3 and 5 may be used
+instead of the keyword.
+@item expert
+Even more detailed messages.  A value between 6 and 8 may be used
+instead of the keyword.
+@item guru
+All of the debug messages you can get. A value greater than 8 may be
+used instead of the keyword.  The creation of hash tracing files is
+only enabled if the keyword is used.
+@end table
+
+How these messages are mapped to the actual debugging flags is not
+specified and may change with newer releases of this program. They are
+however carefully selected to best aid in debugging.
+
 @item --debug @var{flags}
 @opindex debug
 Set debugging flags. All flags are or-ed and @var{flags} may
@@ -2093,6 +2195,13 @@ Enable debug output from the included CCID driver for smartcards.
 Note that this option is only available on some system.
 @end ifset
 
+@item --faked-system-time @var{epoch}
+@opindex faked-system-time
+This option is only useful for testing; it sets the system time back or
+forth to @var{epoch} which is the number of seconds elapsed since the year
+1970.  Alternatively @var{epoch} may be given as a full ISO time string
+(e.g. "20070924T154812").
+
 @item --enable-progress-filter
 Enable certain PROGRESS status outputs. This option allows frontends
 to display a progress indicator while gpg is processing larger files.
@@ -2107,7 +2216,7 @@ Same as @option{--status-fd}, except the status data is written to file
 @code{file}.
 
 @item --logger-fd @code{n}
-Write log output to file descriptor @code{n} and not to stderr.
+Write log output to file descriptor @code{n} and not to STDERR.
 
 @item --log-file @code{file}
 @itemx --logger-file @code{file}
@@ -2264,12 +2373,15 @@ will still get disabled.
 
 @item --throw-keyids
 @itemx --no-throw-keyids
-Do not put the recipient key IDs into encrypted messages. This helps
-to hide the receivers of the message and is a limited countermeasure
-against traffic analysis. On the receiving side, it may slow down the
-decryption process because all available secret keys must be tried.
-@option{--no-throw-keyids} disables this option. This option is essentially
-the same as using @option{--hidden-recipient} for all recipients.
+Do not put the recipient key IDs into encrypted messages. This helps to
+hide the receivers of the message and is a limited countermeasure
+against traffic analysis.@footnote{Using a little social engineering
+anyone who is able to decrypt the message can check whether one of the
+other recipients is the one he suspects.}  On the receiving side, it may
+slow down the decryption process because all available secret keys must
+be tried.  @option{--no-throw-keyids} disables this option. This option
+is essentially the same as using @option{--hidden-recipient} for all
+recipients.
 
 @item --not-dash-escaped
 This option changes the behavior of cleartext signatures
@@ -2296,7 +2408,7 @@ passphrase.  Defaults to 1 repetition.
 @item --passphrase-fd @code{n}
 Read the passphrase from file descriptor @code{n}. Only the first line
 will be read from file descriptor @code{n}. If you use 0 for @code{n},
-the passphrase will be read from stdin. This can only be used if only
+the passphrase will be read from STDIN. This can only be used if only
 one passphrase is supplied.
 @ifclear gpgone
 Note that this passphrase is only used if the option @option{--batch}
@@ -2589,12 +2701,12 @@ current home directory (@pxref{option --homedir}).
 @table @file
 
 @item gpg.conf
-@cindex gpgsm.conf
+@cindex gpg.conf
 This is the standard configuration file read by @command{@gpgname} on
 startup.  It may contain any valid long option; the leading two dashes
 may not be entered and the option may not be abbreviated.  This default
-name may be changed on the command line (@pxref{option
-  --options}).
+name may be changed on the command line (@pxref{option --options}).
+You should backup this file.
 
 @end table
 
@@ -2614,31 +2726,32 @@ files; They all live in in the current home directory (@pxref{option
 
 @table @file
 @item ~/.gnupg/secring.gpg
-The secret keyring.
+The secret keyring.  You should backup this file.
 
 @item ~/.gnupg/secring.gpg.lock
-and the lock file
+The lock file for the secret keyring.
 
 @item ~/.gnupg/pubring.gpg
-The public keyring
+The public keyring.  You should backup this file.
 
 @item ~/.gnupg/pubring.gpg.lock
-and the lock file
+The lock file for the public keyring.
 
 @item ~/.gnupg/trustdb.gpg
-The trust database
+The trust database.  There is no need to backup this file; it is better
+to backup the ownertrust values (@pxref{option --export-ownertrust}).
 
 @item ~/.gnupg/trustdb.gpg.lock
-and the lock file
+The lock file for the trust database.
 
 @item ~/.gnupg/random_seed
-used to preserve the internal random pool
+A file used to preserve the state of the internal random pool.
 
 @item /usr[/local]/share/gnupg/options.skel
-Skeleton options file
+The skeleton options file.
 
 @item /usr[/local]/lib/gnupg/
-Default location for extensions
+Default location for extensions.
 
 @end table
 
@@ -2666,7 +2779,7 @@ value. The option @option{--gpg-agent-info} can be used to override it.
 
 @item PINENTRY_USER_DATA
 This value is passed via gpg-agent to pinentry.  It is useful to convey
-extra information to a custom pinentry
+extra information to a custom pinentry.
 
 @item COLUMNS
 @itemx LINES
@@ -2675,11 +2788,11 @@ Used to size some displays to the full size of the screen.
 
 @item LANGUAGE
 Apart from its use by GNU, it is used in the W32 version to override the
-language selection done through the Registry.  If used and set to a a
+language selection done through the Registry.  If used and set to a
 valid and available language name (@var{langid}), the file with the
 translation is loaded from
 @code{@var{gpgdir}/gnupg.nls/@var{langid}.mo}.  Here @var{gpgdir} is the
-directory out of which the gpg binary has been laoded.  If it can't be
+directory out of which the gpg binary has been loaded.  If it can't be
 loaded the Registry is tried and as last resort the native Windows
 locale system is used.  
 
@@ -2706,6 +2819,9 @@ make a clear text signature
 @item gpg -sb @code{file}
 make a detached signature
 
+@item gpg -u 0x12345678 -sb @code{file}
+make a detached signature with the key 0x12345678
+
 @item gpg --list-keys @code{user_ID}
 show keys
 
@@ -2754,7 +2870,7 @@ is *very* easy to spy out your passphrase!
 
 If you are going to verify detached signatures, make sure that the
 program knows about it; either give both filenames on the command line
-or use @samp{-} to specify stdin.
+or use @samp{-} to specify STDIN.
 
 @mansect interoperability
 @chapheading INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS
@@ -2790,7 +2906,7 @@ violation of OpenPGP, but rather reduce the available algorithms to a
 @mansect bugs
 @chapheading BUGS
 
-On many systems this program should be installed as setuid(root). This
+On older 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 (which may contain
 passphrases or other sensitive material) to disk. If you get no
@@ -2805,6 +2921,10 @@ powered off mode.  Unless measures are taken in the operating system
 to protect the saved memory, passphrases or other sensitive material
 may be recoverable from it later.
 
+Before you report a bug you should first search the mailing list
+archives for similar problems and second check whether such a bug has
+already been reported to our bug tracker at http://bugs.gnupg.org .
+
 @mansect see also
 @ifset isman
 @command{gpgv}(1),