[Pkg-gnupg-commit] [gpgme] 56/132: doc: Document that gpgme_op_genkey() parms parameter is not XML.

[Daniel Kahn Gillmor]

This is an automated email from the git hooks/post-receive script.

dkg pushed a commit to branch experimental
in repository gpgme.

commit ad22bee5387b1e9a40e8c822a081db3228bb9def
Author: Daniel Kahn Gillmor <dkg at fifthhorseman.net>
Date:   Thu Jan 26 18:36:39 2017 -0500

    doc: Document that gpgme_op_genkey() parms parameter is not XML.
    
    * doc/gpgme.texi (GnupgKeyParms): document that input format is not
    true XML.
    
    --
    
    Please see discussion at
    https://lists.gnupg.org/pipermail/gnupg-devel/2017-January/032507.html
    
    Signed-off-by: Daniel Kahn Gillmor <dkg at fifthhorseman.net>
---
 doc/gpgme.texi | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index 99627c4..e058fba 100644
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -3874,11 +3874,18 @@ and return a certificate request in @var{public}, which then needs to
 be signed by the certification authority and imported before it can be
 used.  GpgSM does not make the fingerprint available.
 
-The argument @var{parms} specifies parameters for the key in an XML
-string.  The details about the format of @var{parms} are specific to
-the crypto engine used by @var{ctx}.  Here is an example for GnuPG as
-the crypto engine (all parameters of OpenPGP key generation are
-documented in the GPG manual):
+The argument @var{parms} specifies parameters for the key in an string
+that looks something like XML.  The details about the format of
+ at var{parms} are specific to the crypto engine used by @var{ctx}.  The
+first line of the parameters must be @code{<GnupgKeyParams
+format="internal">} and the last line must be
+ at code{</GnupgKeyParams>}.  Every line in between the first and last
+lines is treated as a Header: Value pair.  In particular, no XML
+escaping is necessary if you need to include the characters @code{<},
+ at code{>}, or @code{&}.
+
+Here is an example for GnuPG as the crypto engine (all parameters of
+OpenPGP key generation are documented in the GPG manual):
 
 @example
 <GnupgKeyParms format="internal">
@@ -3914,9 +3921,10 @@ retrieved with @code{gpgme_op_genkey_result}.
 
 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
 operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
- at var{parms} is not a valid XML string, @code{GPG_ERR_NOT_SUPPORTED} if
- at var{public} or @var{secret} is not valid, and @code{GPG_ERR_GENERAL}
-if no key was created by the backend.
+ at var{parms} is not a well-formed string (e.g. does not have the
+expected tag-like headers and footers), @code{GPG_ERR_NOT_SUPPORTED}
+if @var{public} or @var{secret} is not valid, and
+ at code{GPG_ERR_GENERAL} if no key was created by the backend.
 @end deftypefun
 
 @deftypefun gpgme_error_t gpgme_op_genkey_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{parms}}, @w{gpgme_data_t @var{public}}, @w{gpgme_data_t @var{secret}})

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-gnupg/gpgme.git