g10: Remove skeleton options files.
[gnupg.git] / doc / gpg.texi
index 5b4584d..aa55cb8 100644 (file)
@@ -117,11 +117,6 @@ perform a reasonable action depending on the type of file it is given
 as input (an encrypted message is decrypted, a signature is verified,
 a file containing keys is listed, etc.).
 
-Please remember that option and command parsing stops as soon as a
-non-option is encountered.  Thus, options must precede the command.
-You can explicitly stop parsing by using the special option
-@option{--}.
-
 
 @menu
 * General GPG Commands::        Commands not specific to the functionality.
@@ -146,7 +141,8 @@ cannot abbreviate this command.
 @itemx -h
 @opindex help
 Print a usage message summarizing the most useful command-line options.
-Note that you cannot abbreviate this command.
+Note that you cannot arbitrarily abbreviate this command
+(though you can use its short form @option{-h}).
 
 @item --warranty
 @opindex warranty
@@ -181,6 +177,8 @@ chosen by default or can be set explicitly using the
 
 @item --clear-sign
 @opindex clear-sign
+@itemx --clearsign
+@opindex clearsign
 Make a cleartext signature.  The content in a cleartext signature is
 readable without any special software. OpenPGP software is only needed
 to verify the signature.  cleartext signatures may modify end-of-line
@@ -258,6 +256,13 @@ out the actual signed data, but there are other pitfalls with this
 format as well.  It is suggested to avoid cleartext signatures in
 favor of detached signatures.
 
+Note: Sometimes the use of the @command{gpgv} tool is easier than
+using the full-fledged @command{gpg} with this option.  @command{gpgv}
+is designed to compare signed data against a list of trusted keys and
+returns with success only for a good signature.  It has its own manual
+page.
+
+
 @item --multifile
 @opindex multifile
 This modifies certain other commands to accept multiple files for
@@ -296,13 +301,18 @@ and other programs.
 @itemx -K
 @opindex list-secret-keys
 List the specified secret keys.  If no keys are specified, then all
-known secret keys are listed.  A @code{#} after the letters @code{sec}
-means that the secret key is not usable (for example, if it was
-exported using @option{--export-secret-subkeys}).  See also
-@option{--list-keys}.
+known secret keys are listed.  A @code{#} after the intial tags
+@code{sec} or @code{ssb} means that the secret key or subkey is
+currently not usable.  We also say that this key has been taken
+offline (for example, a primary key can be taken offline by exported
+the key using the command @option{--export-secret-subkeys}).  A
+@code{>} after these tags indicate that the key is stored on a
+smartcard.  See also @option{--list-keys}.
 
 @item --list-signatures
 @opindex list-signatures
+@itemx --list-sigs
+@opindex list-sigs
 Same as @option{--list-keys}, but the signatures are listed too.
 This command has the same effect as
 using @option{--list-keys} with @option{--with-sig-list}.
@@ -320,7 +330,9 @@ notation (see @option{--cert-notation}), "X" for an eXpired signature
 above to indicate trust signature levels (see the @option{--edit-key}
 command "tsign").
 
-@item --check-sigs
+@item --check-signatures
+@opindex check-signatures
+@itemx --check-sigs
 @opindex check-sigs
 Same as @option{--list-signatures}, but the signatures are verified.  Note
 that for performance reasons the revocation status of a signing key is
@@ -348,7 +360,7 @@ be used to locate a key.  Only public keys are listed.
 List all keys (or the specified ones) along with their
 fingerprints. This is the same output as @option{--list-keys} but with
 the additional output of a line with the fingerprint. May also be
-combined with @option{--list-signatures} or @option{--check-sigs}.  If this
+combined with @option{--list-signatures} or @option{--check-signatures}.  If this
 command is given twice, the fingerprints of all secondary keys are
 listed too.  This command also forces pretty printing of fingerprints
 if the keyid format has been set to "none".
@@ -361,7 +373,9 @@ values are dumped and not only their lengths.  Note that the output of
 this command may change with new releases.
 
 
-@item --card-edit
+@item --edit-card
+@opindex edit-card
+@itemx --card-edit
 @opindex card-edit
 Present a menu to work with a smartcard. The subcommand "help" provides
 an overview on available commands. For a detailed description, please
@@ -376,7 +390,7 @@ Show the content of the smart card.
 @opindex change-pin
 Present a menu to allow changing the PIN of a smartcard. This
 functionality is also available as the subcommand "passwd" with the
-@option{--card-edit} command.
+@option{--edit-card} command.
 
 @item --delete-keys @code{name}
 @itemx --delete-keys @code{name}
@@ -466,6 +480,8 @@ signatures, user-IDs and subkeys.
 
 @item --receive-keys @code{key IDs}
 @opindex receive-keys
+@itemx --recv-keys @code{key IDs}
+@opindex recv-keys
 Import the keys with the given key IDs from a keyserver. Option
 @option{--keyserver} must be used to give the name of this keyserver.
 
@@ -608,10 +624,10 @@ This section explains the main commands for key management.
 
 @table @gnupgtabopt
 
-@item --quick-gen-key @code{user-id} [@code{algo} [@code{usage} [@code{expire}]]]
-@opindex quick-gen-key
+@item --quick-generate-key @code{user-id} [@code{algo} [@code{usage} [@code{expire}]]]
+@opindex quick-generate-key
 This is a simple command to generate a standard key with one user id.
-In contrast to @option{--gen-key} the key is generated directly
+In contrast to @option{--generate-key} the key is generated directly
 without the need to answer a bunch of prompts.  Unless the option
 @option{--yes} is given, the key creation will be canceled if the
 given user id already exists in the keyring.
@@ -626,15 +642,18 @@ created and no prompts are shown.  To specify an expiration date but
 still create a primary and subkey use ``default'' or
 ``future-default'' for @code{algo} and ``default'' for @code{usage}.
 For a description of these optional arguments see the command
-@code{--quick-addkey}.  The @code{usage} accepts also the value
+@code{--quick-add-key}.  The @code{usage} accepts also the value
 ``cert'' which can be used to create a certification only primary key;
 the default is to a create certification and signing key.
 
 The @code{expire} argument can be used to specify an expiration date
-for the key.  Several formats are supported; commonly the ISO
-YYYY-MM-DD format is used.  The values ``never'', ``none'' can be used
-for no expiration date.  Not specifying a value, or using ``-''
-results in a key expiring in a reasonable default interval.
+for the key.  Several formats are supported; commonly the ISO formats
+``YYYY-MM-DD'' or ``YYYYMMDDThhmmss'' are used.  To make the key
+expire in N seconds, N days, N weeks, N months, or N years use
+``seconds=N'', ``Nd'', ``Nw'', ``Nm'', or ``Ny'' respectively.  Not
+specifying a value, or using ``-'' results in a key expiring in a
+reasonable default interval.  The values ``never'', ``none'' can be
+used for no expiration date.
 
 If this command is used with @option{--batch},
 @option{--pinentry-mode} has been set to @code{loopback}, and one of
@@ -650,8 +669,8 @@ Directly set the expiration time of the primary key to @code{expire}.
 To remove the expiration time @code{0} can be used.
 
 
-@item --quick-addkey @code{fpr} [@code{algo} [@code{usage} [@code{expire}]]]
-@opindex quick-addkey
+@item --quick-add-key @code{fpr} [@code{algo} [@code{usage} [@code{expire}]]]
+@opindex quick-add-key
 Directly add a subkey to the key identified by the fingerprint
 @code{fpr}.  Without the optional arguments an encryption subkey is
 added.  If any of the arguments are given a more specific subkey is
@@ -671,34 +690,45 @@ Depending on the given @code{algo} the subkey may either be an
 encryption subkey or a signing subkey.  If an algorithm is capable of
 signing and encryption and such a subkey is desired, a @code{usage}
 string must be given.  This string is either ``default'' or ``-'' to
-keep the default or a comma delimited list of keywords: ``sign'' for a
-signing subkey, ``auth'' for an authentication subkey, and ``encr''
-for an encryption subkey (``encrypt'' can be used as alias for
-``encr'').  The valid combinations depend on the algorithm.
+keep the default or a comma delimited list (or space delimited list)
+of keywords: ``sign'' for a signing subkey, ``auth'' for an
+authentication subkey, and ``encr'' for an encryption subkey
+(``encrypt'' can be used as alias for ``encr'').  The valid
+combinations depend on the algorithm.
 
 The @code{expire} argument can be used to specify an expiration date
-for the subkey.  Several formats are supported; commonly the ISO
-YYYY-MM-DD format is used.  The values ``never'', ``none'', or ``-''
-can be used for no expiration date.
-
-@item --gen-key
+for the key.  Several formats are supported; commonly the ISO formats
+``YYYY-MM-DD'' or ``YYYYMMDDThhmmss'' are used.  To make the key
+expire in N seconds, N days, N weeks, N months, or N years use
+``seconds=N'', ``Nd'', ``Nw'', ``Nm'', or ``Ny'' respectively.  Not
+specifying a value, or using ``-'' results in a key expiring in a
+reasonable default interval.  The values ``never'', ``none'' can be
+used for no expiration date.
+
+@item --generate-key
+@opindex generate-key
+@itemx --gen-key
 @opindex gen-key
 Generate a new key pair using the current default parameters.  This is
 the standard command to create a new key.  In addition to the key a
 revocation certificate is created and stored in the
 @file{openpgp-revocs.d} directory below the GnuPG home directory.
 
-@item --full-gen-key
-@opindex gen-key
+@item --full-generate-key
+@opindex full-generate-key
+@itemx --full-gen-key
+@opindex full-gen-key
 Generate a new key pair with dialogs for all options.  This is an
-extended version of @option{--gen-key}.
+extended version of @option{--generate-key}.
 
 There is also a feature which allows you to create keys in batch
 mode. See the manual section ``Unattended key generation'' on how
 to use this.
 
 
-@item --gen-revoke @code{name}
+@item --generate-revocation @code{name}
+@opindex generate-revocation
+@itemx --gen-revoke @code{name}
 @opindex gen-revoke
 Generate a revocation certificate for the complete key.  To only revoke
 a subkey or a key signature, use the @option{--edit} command.
@@ -713,7 +743,9 @@ published, which is best done by sending the key to a keyserver
 to a file which is then send to frequent communication partners.
 
 
-@item --desig-revoke @code{name}
+@item --generate-designated-revocation @code{name}
+@opindex generate-designated-revocation
+@itemx --desig-revoke @code{name}
 @opindex desig-revoke
 Generate a designated revocation certificate for a key. This allows a
 user (with the permission of the keyholder) to revoke someone else's
@@ -917,7 +949,8 @@ signing.
   @opindex keyedit:delkey
   Remove a subkey (secondary 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}.
+  that case you better use @code{revkey}.  Also note that this only
+  deletes the public part of a key.
 
   @item revkey
   @opindex keyedit:revkey
@@ -1056,27 +1089,38 @@ full flexibility of the "sign" subcommand from @option{--edit-key}.
 Its intended use is to help unattended key signing by utilizing a list
 of verified fingerprints.
 
-@item --quick-adduid  @var{user-id} @var{new-user-id}
-@opindex quick-adduid
+@item --quick-add-uid  @var{user-id} @var{new-user-id}
+@opindex quick-add-uid
 This command adds a new user id to an existing key.  In contrast to
 the interactive sub-command @code{adduid} of @option{--edit-key} the
 @var{new-user-id} is added verbatim with only leading and trailing
 white space removed, it is expected to be UTF-8 encoded, and no checks
 on its form are applied.
 
-@item --quick-revuid  @var{user-id} @var{user-id-to-revoke}
-@opindex quick-revuid
-This command revokes a User ID on an existing key.  It cannot be used
-to revoke the last User ID on key (some non-revoked User ID must
+@item --quick-revoke-uid  @var{user-id} @var{user-id-to-revoke}
+@opindex quick-revoke-uid
+This command revokes a user ID on an existing key.  It cannot be used
+to revoke the last user ID on key (some non-revoked user ID must
 remain), with revocation reason ``User ID is no longer valid''.  If
 you want to specify a different revocation reason, or to supply
 supplementary revocation text, you should use the interactive
 sub-command @code{revuid} of @option{--edit-key}.
 
-@item --passwd @var{user_id}
+@item --quick-set-primary-uid  @var{user-id} @var{primary-user-id}
+@opindex quick-set-primary-uid
+This command sets or updates the primary user ID flag on an existing
+key.  @var{user-id} specifies the key and @var{primary-user-id} the
+user ID which shall be flagged as the primary user ID.  The primary
+user ID flag is removed from all other user ids and the timestamp of
+all affected self-signatures is set one second ahead.
+
+
+@item --change-passphrase @var{user-id}
+@opindex change-passphrase
+@itemx --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
+specified as @var{user-id}.  This is a shortcut for the sub-command
 @code{passwd} of the edit key menu.
 
 @end table
@@ -1227,7 +1271,7 @@ give the opposite meaning.  The options are:
 
   @item show-policy-urls
   @opindex list-options:show-policy-urls
-  Show policy URLs in the @option{--list-signatures} or @option{--check-sigs}
+  Show policy URLs in the @option{--list-signatures} or @option{--check-signatures}
   listings.  Defaults to no.
 
   @item show-notations
@@ -1237,12 +1281,12 @@ give the opposite meaning.  The options are:
   @opindex list-options:show-std-notations
   @opindex list-options:show-user-notations
   Show all, IETF standard, or user-defined signature notations in the
-  @option{--list-signatures} or @option{--check-sigs} listings. Defaults to no.
+  @option{--list-signatures} or @option{--check-signatures} listings. Defaults to no.
 
   @item show-keyserver-urls
   @opindex list-options:show-keyserver-urls
   Show any preferred keyserver URL in the @option{--list-signatures} or
-  @option{--check-sigs} listings. Defaults to no.
+  @option{--check-signatures} listings. Defaults to no.
 
   @item show-uid-validity
   @opindex list-options:show-uid-validity
@@ -1265,7 +1309,7 @@ give the opposite meaning.  The options are:
   @item show-sig-expire
   @opindex list-options:show-sig-expire
   Show signature expiration dates (if any) during @option{--list-signatures} or
-  @option{--check-sigs} listings. Defaults to no.
+  @option{--check-signatures} listings. Defaults to no.
 
   @item show-sig-subpackets
   @opindex list-options:show-sig-subpackets
@@ -1273,7 +1317,7 @@ give the opposite meaning.  The options are:
   optional argument list of the subpackets to list. If no argument is
   passed, list all subpackets. Defaults to no. This option is only
   meaningful when using @option{--with-colons} along with
-  @option{--list-signatures} or @option{--check-sigs}.
+  @option{--list-signatures} or @option{--check-signatures}.
 
 @end table
 
@@ -1342,7 +1386,7 @@ the opposite meaning. The options are:
 @itemx --disable-large-rsa
 @opindex enable-large-rsa
 @opindex disable-large-rsa
-With --gen-key and --batch, enable the creation of RSA secret keys as
+With --generate-key and --batch, enable the creation of RSA secret keys as
 large as 8192 bit.  Note: 8192 bit is more than is generally
 recommended.  These large keys don't significantly improve security,
 but they are more expensive to use, and their signatures and
@@ -1398,7 +1442,7 @@ Note that this adds a keyring to the current list. If the intent is to
 use the specified keyring alone, use @option{--keyring} along with
 @option{--no-default-keyring}.
 
-If the the option @option{--no-keyring} has been used no keyrings will
+If the option @option{--no-keyring} has been used no keyrings will
 be used at all.
 
 
@@ -1576,17 +1620,17 @@ Set what trust model GnuPG should follow. The models are:
 @table @asis
 
   @item pgp
-  @opindex trust-mode:pgp
+  @opindex trust-model:pgp
   This is the Web of Trust combined with trust signatures as used in PGP
   5.x and later. This is the default trust model when creating a new
   trust database.
 
   @item classic
-  @opindex trust-mode:classic
+  @opindex trust-model:classic
   This is the standard Web of Trust as introduced by PGP 2.
 
   @item tofu
-  @opindex trust-mode:tofu
+  @opindex trust-model:tofu
   @anchor{trust-model-tofu}
   TOFU stands for Trust On First Use.  In this trust model, the first
   time a key is seen, it is memorized.  If later another key is seen
@@ -1632,7 +1676,7 @@ Set what trust model GnuPG should follow. The models are:
   @code{undefined} trust level is returned.
 
   @item tofu+pgp
-  @opindex trust-mode:tofu+pgp
+  @opindex trust-model:tofu+pgp
   This trust model combines TOFU with the Web of Trust.  This is done
   by computing the trust level for each model and then taking the
   maximum trust level where the trust levels are ordered as follows:
@@ -1645,12 +1689,16 @@ Set what trust model GnuPG should follow. The models are:
   which some security-conscious users don't like.
 
   @item direct
-  @opindex trust-mode:direct
+  @opindex trust-model:direct
   Key validity is set directly by the user and not calculated via the
-  Web of Trust.
+  Web of Trust.  This model is soley based on the key and does
+  not distinguish user IDs.  Note that when changing to another trust
+  model the trust values assigned to a key are transformed into
+  ownertrust values, which also indicate how you trust the owner of
+  the key to sign other keys.
 
   @item always
-  @opindex trust-mode:always
+  @opindex trust-model:always
   Skip key validation and assume that used keys are always fully
   valid. You generally won't use this unless you are using some
   external validation scheme. This option also suppresses the
@@ -1660,7 +1708,7 @@ Set what trust model GnuPG should follow. The models are:
   disabled keys.
 
   @item auto
-  @opindex trust-mode:auto
+  @opindex trust-model:auto
   Select the trust model depending on whatever the internal trust
   database says. This is the default model if such a database already
   exists.
@@ -1731,7 +1779,7 @@ when verifying signatures made by keys that are not on the local
 keyring.
 
 If the method "wkd" is included in the list of methods given to
-@option{auto-key-locate}, the Signer's User ID is part of the
+@option{auto-key-locate}, the signer's user ID is part of the
 signature, and the option @option{--disable-signer-uid} is not used,
 the "wkd" method may also be used to retrieve a key.
 
@@ -1800,7 +1848,8 @@ are available for all keyserver types, some common options are:
   used with HKP keyservers.
 
   @item auto-key-retrieve
-  This is the same as the option @option{auto-key-retrieve}.
+  This is an obsolete alias for the option @option{auto-key-retrieve}.
+  Please do not use it; it will be removed in future versions..
 
   @item honor-keyserver-url
   When using @option{--refresh-keys}, if the key in question has a preferred
@@ -2260,6 +2309,12 @@ opposite meaning. The options are:
   the most recent self-signature on each user ID. This option is the
   same as running the @option{--edit-key} command "minimize" after import.
   Defaults to no.
+
+  @item restore
+  @itemx import-restore
+  Import in key restore mode.  This imports all data which is usually
+  skipped during import; including all GnuPG specific data.  All other
+  contradicting options are overridden.
 @end table
 
 @item --import-filter @code{@var{name}=@var{expr}}
@@ -2320,14 +2375,25 @@ The available properties are:
   @item primary
   Boolean indicating whether the user id is the primary one.  (keep-uid)
 
+  @item expired
+  Boolean indicating whether a user id (keep-uid), a key (drop-subkey), or a
+  signature (drop-sig) expired.
+
+  @item revoked
+  Boolean indicating whether a user id (keep-uid) or a key (drop-subkey) has
+  been revoked.
+
+  @item disabled
+  Boolean indicating whether a primary key is disabled. (not used)
+
   @item secret
   Boolean indicating whether a key or subkey is a secret one.
-  drop-subkey)
+  (drop-subkey)
 
   @item sig_created
   @itemx sig_created_d
   The first is the timestamp a signature packet was created.  The
-  second is the same but given as an ISO string,
+  second is the same but given as an ISO date string,
   e.g. "2016-08-17". (drop-sig)
 
   @item sig_algo
@@ -2341,8 +2407,8 @@ The available properties are:
 @item --export-options @code{parameters}
 @opindex export-options
 This is a space or comma delimited string that gives options for
-exporting keys. Options can be prepended with a `no-' to give the
-opposite meaning. The options are:
+exporting keys.  Options can be prepended with a `no-' to give the
+opposite meaning.  The options are:
 
 @table @asis
 
@@ -2370,6 +2436,13 @@ opposite meaning. The options are:
   @c when the exported subkey is to be used on an unattended machine where
   @c a passphrase doesn't necessarily make sense. Defaults to no.
 
+  @item backup
+  @itemx export-backup
+  Export for use as a backup.  The exported data includes all data
+  which is needed to restore the key or keys later with GnuPG.  The
+  format is basically the OpenPGP format but enhanced with GnuPG
+  specific data.  All other contradicting options are overridden.
+
   @item export-clean
   Compact (remove all signatures from) user IDs on the key being
   exported if the user IDs are not usable. Also, do not export any
@@ -2725,6 +2798,9 @@ 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").
 
+If you suffix @var{epoch} with an exclamation mark (!), the system time
+will appear to be frozen at the specified time.
+
 @item --enable-progress-filter
 @opindex enable-progress-filter
 Enable certain PROGRESS status outputs. This option allows frontends
@@ -3293,7 +3369,7 @@ Identical to @option{--trust-model always}. This option is deprecated.
 @item --show-notation
 @itemx --no-show-notation
 @opindex show-notation
-Show signature notations in the @option{--list-signatures} or @option{--check-sigs} listings
+Show signature notations in the @option{--list-signatures} or @option{--check-signatures} listings
 as well as when verifying a signature with a notation in it. These
 options are deprecated. Use @option{--list-options [no-]show-notation}
 and/or @option{--verify-options [no-]show-notation} instead.
@@ -3301,7 +3377,7 @@ and/or @option{--verify-options [no-]show-notation} instead.
 @item --show-policy-url
 @itemx --no-show-policy-url
 @opindex show-policy-url
-Show policy URLs in the @option{--list-signatures} or @option{--check-sigs}
+Show policy URLs in the @option{--list-signatures} or @option{--check-signatures}
 listings as well as when verifying a signature with a policy URL in
 it. These options are deprecated. Use @option{--list-options
 [no-]show-policy-url} and/or @option{--verify-options
@@ -3343,7 +3419,7 @@ For existing users a small
 helper script is provided to create these files (@pxref{addgnupghome}).
 
 For internal purposes @command{@gpgname} creates and maintains a few other
-files; They all live in in the current home directory (@pxref{option
+files; They all live in the current home directory (@pxref{option
 --homedir}).  Only the @command{@gpgname} program may modify these files.
 
 
@@ -3404,10 +3480,6 @@ files; They all live in in the current home directory (@pxref{option
   You should backup all files in this directory and take care to keep
   this backup closed away.
 
-  @item @value{DATADIR}/options.skel
-  @efindex options.skel
-  The skeleton options file.
-
 @end table
 
 Operation is further controlled by a few environment variables:
@@ -3722,17 +3794,68 @@ way to do this.  The options @option{--status-fd} and @option{--batch}
 are almost always required for this.
 
 @menu
+* Programmatic use of GnuPG:: Programmatic use of GnuPG
+* Ephemeral home directories:: Ephemeral home directories
+* The quick key manipulation interface:: The quick key manipulation interface
 * Unattended GPG key generation::  Unattended key generation
 @end menu
 
 
+@node Programmatic use of GnuPG
+@subsection Programmatic use of GnuPG
+
+Please consider using GPGME instead of calling @command{@gpgname}
+directly.  GPGME offers a stable, backend-independent interface for
+many cryptographic operations.  It supports OpenPGP and S/MIME, and
+also allows interaction with various GnuPG components.
+
+GPGME provides a C-API, and comes with bindings for C++, Qt, and
+Python.  Bindings for other languages are available.
+
+@node Ephemeral home directories
+@subsection Ephemeral home directories
+
+Sometimes you want to contain effects of some operation, for example
+you want to import a key to inspect it, but you do not want this key
+to be added to your keyring.  In earlier versions of GnuPG, it was
+possible to specify alternate keyring files for both public and secret
+keys.  In modern GnuPG versions, however, we changed how secret keys
+are stored in order to better protect secret key material, and it was
+not possible to preserve this interface.
+
+The preferred way to do this is to use ephemeral home directories.
+This technique works across all versions of GnuPG.
+
+Create a temporary directory, create (or copy) a configuration that
+meets your needs, make @command{@gpgname} use this directory either
+using the environment variable @var{GNUPGHOME}, or the option
+@option{--homedir}.  GPGME supports this too on a per-context basis,
+by modifying the engine info of contexts.  Now execute whatever
+operation you like, import and export key material as necessary.  Once
+finished, you can delete the directory.  All GnuPG backend services
+that were started will detect this and shut down.
+
+@node The quick key manipulation interface
+@subsection The quick key manipulation interface
+
+Recent versions of GnuPG have an interface to manipulate keys without
+using the interactive command @option{--edit-key}.  This interface was
+added mainly for the benefit of GPGME (please consider using GPGME,
+see the manual subsection ``Programmatic use of GnuPG'').  This
+interface is described in the subsection ``How to manage your keys''.
+
 @node Unattended GPG key generation
 @subsection Unattended key generation
 
-The command @option{--gen-key} may be used along with the option
-@option{--batch} for unattended key generation.  The parameters are
-either read from stdin or given as a file on the command line.
-The format of the parameter file is as follows:
+The command @option{--generate-key} may be used along with the option
+@option{--batch} for unattended key generation.  This is the most
+flexible way of generating keys, but it is also the most complex one.
+Consider using the quick key manipulation interface described in the
+previous subsection ``The quick key manipulation interface''.
+
+The parameters for the key are either read from stdin or given as a
+file on the command line.  The format of the parameter file is as
+follows:
 
 @itemize @bullet
   @item Text only, line length is limited to about 1000 characters.
@@ -3775,16 +3898,21 @@ Perform the key generation.  Note that an implicit commit is done at
 the next @asis{Key-Type} parameter.
 
 @item %pubring @var{filename}
-@itemx %secring @var{filename}
 Do not write the key to the default or commandline given keyring but
 to @var{filename}.  This must be given before the first commit to take
 place, duplicate specification of the same filename is ignored, the
 last filename before a commit is used.  The filename is used until a
 new filename is used (at commit points) and all keys are written to
 that file. If a new filename is given, this file is created (and
-overwrites an existing one).  For GnuPG versions prior to 2.1, both
-control statements must be given. For GnuPG 2.1 and later
-@samp{%secring} is a no-op.
+overwrites an existing one).
+
+See the previous subsection ``Ephemeral home directories'' for a more
+robust way to contain side-effects.
+
+@item %secring @var{filename}
+This option is a no-op for GnuPG 2.1 and later.
+
+See the previous subsection ``Ephemeral home directories''.
 
 @item %ask-passphrase
 @itemx %no-ask-passphrase
@@ -3902,8 +4030,9 @@ generation to associate a key parameter block with a status line.
 @end table
 
 @noindent
-Here is an example on how to create a key:
+Here is an example on how to create a key in an ephemeral home directory:
 @smallexample
+$ export GNUPGHOME="$(mktemp -d)"
 $ cat >foo <<EOF
      %echo Generating a basic OpenPGP key
      Key-Type: DSA
@@ -3915,23 +4044,21 @@ $ cat >foo <<EOF
      Name-Email: joe@@foo.bar
      Expire-Date: 0
      Passphrase: abc
-     %pubring foo.pub
-     %secring foo.sec
      # Do a commit here, so that we can later print "done" :-)
      %commit
      %echo done
 EOF
-$ @gpgname --batch --gen-key foo
+$ @gpgname --batch --generate-key foo
  [...]
-$ @gpgname --no-default-keyring --secret-keyring ./foo.sec \
-       --keyring ./foo.pub --list-secret-keys
-/home/wk/work/gnupg-stable/scratch/foo.sec
-------------------------------------------
-sec  1024D/915A878D 2000-03-09 Joe Tester (with stupid passphrase) <joe@@foo.bar>
-ssb  1024g/8F70E2C0 2000-03-09
+$ @gpgname --list-secret-keys
+/tmp/tmp.0NQxB74PEf/pubring.kbx
+-------------------------------
+sec   dsa1024 2016-12-16 [SCA]
+      768E895903FC1C44045C8CB95EEBDB71E9E849D0
+uid           [ultimate] Joe Tester (with stupid passphrase) <joe@@foo.bar>
+ssb   elg1024 2016-12-16 [E]
 @end smallexample
 
-
 @noindent
 If you want to create a key with the default algorithms you would use
 these parameters:
@@ -3944,8 +4071,6 @@ these parameters:
      Name-Email: joe@@foo.bar
      Expire-Date: 0
      Passphrase: abc
-     %pubring foo.pub
-     %secring foo.sec
      # Do a commit here, so that we can later print "done" :-)
      %commit
      %echo done