updated documentation. The function descriptions were converted to floats.

1 files changed, 18 insertions, 50 deletions

diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi
index 6ee340d75d..dfbb51ecf0 100644
--- a/doc/cha-cert-auth.texi
+++ b/doc/cha-cert-auth.texi
@@ -225,9 +225,9 @@ possession of the private key.
 @showfuncdesc{gnutls_x509_crq_set_key_purpose_oid}
 @showfuncdesc{gnutls_x509_crq_set_basic_constraints}
 
-The following two functions associate the request with
-a private key and sign it. If a request is to be signed
-with a key residing in a token it is recommended to use
+The @funcref{gnutls_x509_crq_set_key} and @funcref{gnutls_x509_crq_sign2} 
+functions associate the request with a private key and sign it. If a 
+request is to be signed with a key residing in a PKCS #11 token it is recommended to use
 the signing functions shown in @ref{Abstract key types}.
 
 @showfuncdesc{gnutls_x509_crq_set_key}
@@ -265,11 +265,10 @@ structure.
 @showfuncdesc{gnutls_pkcs12_verify_mac}
 @showfuncdesc{gnutls_pkcs12_bag_decrypt}
 
-@showfuncB{gnutls_pkcs12_bag_init,gnutls_pkcs12_bag_deinit}
+@showfuncF{gnutls_pkcs12_bag_init,gnutls_pkcs12_bag_deinit,gnutls_pkcs12_bag_get_count,gnutls_pkcs12_bag_get_data,gnutls_pkcs12_bag_get_key_id,gnutls_pkcs12_bag_get_friendly_name}
 
-@showfuncD{gnutls_pkcs12_bag_get_count,gnutls_pkcs12_bag_get_data,gnutls_pkcs12_bag_get_key_id,gnutls_pkcs12_bag_get_friendly_name}
-
-To generate a structure the functions below may be used.
+The functions below are used to generate a PKCS #12 structure. An example
+of their usage is also shown.
 
 @showfuncdesc{gnutls_pkcs12_set_bag}
 @showfuncdesc{gnutls_pkcs12_bag_encrypt}
@@ -277,9 +276,6 @@ To generate a structure the functions below may be used.
 @showfuncdesc{gnutls_pkcs12_export}
 @showfuncE{gnutls_pkcs12_bag_set_data,gnutls_pkcs12_bag_set_crl,gnutls_pkcs12_bag_set_crt,gnutls_pkcs12_bag_set_key_id,gnutls_pkcs12_bag_set_friendly_name}
 
-An example of a @acronym{PKCS} #12 structure generation can be found
-below.
-
 @verbatiminclude examples/ex-pkcs12.c
 
 @node OpenPGP certificates
@@ -338,30 +334,13 @@ returns the key status. The key verification status is the same as in
 @acronym{X.509} certificates, although the meaning and interpretation
 are different. For example an @acronym{OpenPGP} key may be valid, if
 the self signature is ok, even if no signers were found.  The meaning
-of verification status is shown in the figure below.
+of verification status flags is the same as in the @acronym{X.509} certificates
+(see @ref{gnutls_certificate_verify_flags}).
 
 @showfuncdesc{gnutls_openpgp_crt_verify_ring}
 
 @showfuncdesc{gnutls_openpgp_crt_verify_self}
 
-@table @code
-
-@item CERT_INVALID:
-A signature on the key is invalid. That means that the key was
-modified by somebody, or corrupted during transport.
-
-@item CERT_REVOKED:
-The key has been revoked by its owner.
-
-@item CERT_SIGNER_NOT_FOUND:
-The key was not signed by a known signer.
-
-@item GNUTLS_CERT_INSECURE_ALGORITHM:
-The certificate was signed using an insecure algorithm such as MD2 or
-MD5.  These algorithms have been broken and should not be trusted.
-
-@end table
-
 @subsection Verifying a certificate in the context of a TLS session
 
 Similarly with X.509 certificates, one needs to specify
@@ -468,13 +447,13 @@ are shown below.
 Properties of the physical token can also be accessed and altered with @acronym{GnuTLS}.
 For example data in a token can be erased (initialized), PIN can be altered, etc.
 
-@showfuncdesc{gnutls_pkcs11_token_init}
+@showfuncD{gnutls_pkcs11_token_init,gnutls_pkcs11_token_get_url,gnutls_pkcs11_token_get_info,gnutls_pkcs11_token_get_flags}
 @showfuncdesc{gnutls_pkcs11_token_set_pin}
-@showfuncdesc{gnutls_pkcs11_token_get_url}
-@showfuncdesc{gnutls_pkcs11_token_get_info}
-@showfuncdesc{gnutls_pkcs11_token_get_flags}
 
-The following example will list all available PKCS #11 tokens in a system.
+The following examples demonstrate the usage of the API. The first example
+will list all available PKCS #11 tokens in a system and the latter will
+list all certificates in a token that have a corresponding private key.
+
 @example
 int i;
 char* url;
@@ -496,9 +475,6 @@ for (i=0;;i++)
 gnutls_global_deinit();
 @end example
 
-
-That example will only list all certificates in a token that have a corresponding
-private key.
 @verbatiminclude examples/ex-pkcs11-list.c
 
 @subsection Writing objects
@@ -534,8 +510,9 @@ Since there are many forms of a public or private keys supported by @acronym{Gnu
 @acronym{X.509}, @acronym{OpenPGP}, or @acronym{PKCS} #11 it is desirable to allow common operations
 on them. For these reasons the abstract @code{gnutls_privkey_t} and @code{gnutls_pubkey_t} were
 introduced in @code{gnutls/abstract.h} header. Those types are initialized using a specific type of 
-key and then can be used to perform operations in an abstract way. For example in order for someone 
-to sign an X.509 certificate with a key that resides in a smart he has to follow the steps below:
+key and then can be used to perform operations in an abstract way. For example in order
+to sign an X.509 certificate with a key that resides in a token the following steps must be
+used.
 
 @example
 #inlude <gnutls/abstract.h>
@@ -602,12 +579,7 @@ are not extractable.
 
 @showfuncdesc{gnutls_privkey_import_x509}
 
-@showfuncdesc{gnutls_privkey_import_openpgp}
-@showfuncdesc{gnutls_privkey_import_pkcs11}
-
-Other information on the private key can be accessed using
-the following functions.
-
+@showfuncB{gnutls_privkey_import_openpgp,gnutls_privkey_import_pkcs11}
 @showfuncdesc{gnutls_privkey_get_pk_algorithm}
 @showfuncdesc{gnutls_privkey_get_type}
 
@@ -616,7 +588,6 @@ The abstract key types can be used to access signing and
 signature verification operations with the underlying keys.
 
 @showfuncdesc{gnutls_pubkey_verify_data2}
-
 @showfuncdesc{gnutls_pubkey_verify_hash}
 @showfuncdesc{gnutls_privkey_sign_data}
 @showfuncdesc{gnutls_privkey_sign_hash}
@@ -627,11 +598,8 @@ keys with structures is also possible using the
 key abstractions.
 
 @showfuncdesc{gnutls_x509_crq_set_pubkey}
-
 @showfuncdesc{gnutls_x509_crt_set_pubkey}
-@showfuncdesc{gnutls_x509_crt_privkey_sign}
-@showfuncdesc{gnutls_x509_crl_privkey_sign}
-@showfuncdesc{gnutls_x509_crq_privkey_sign}
+@showfuncC{gnutls_x509_crt_privkey_sign,gnutls_x509_crl_privkey_sign,gnutls_x509_crq_privkey_sign}
 
 @node Digital signatures
 @section Digital signatures