documentation updates.

7 files changed, 224 insertions, 170 deletions

diff --git a/doc/cha-auth.texi b/doc/cha-auth.texi
index edfb36d161..9f85e2ff10 100644
--- a/doc/cha-auth.texi
+++ b/doc/cha-auth.texi
@@ -114,28 +114,29 @@ certificate authentication.
 
 Note that the DHE key exchange methods are generally
 slower@footnote{It really depends on the group used.  Primes with
-lesser bits are always faster, but also easier to break.  Values less
-than 1024 should not be used today} than plain RSA and require Diffie
+lesser bits are always faster, but also easier to break.  See @ref{Selecting cryptographic key sizes}
+for the acceptable security levels.} than plain RSA and require Diffie
 Hellman parameters to be generated and associated with a credentials
 structure, by the server. For more information check the @ref{Parameter generation}
-section.
+section. The key exchange algorithms for @acronym{OpenPGP} and @acronym{X.509}
+certificates are shown in @ref{tab:key-exchange}.
 
-Key exchange algorithms for @acronym{OpenPGP} and @acronym{X.509}
-certificates:
+@float Table,tab:key-exchange
+@multitable @columnfractions .3 .7
 
-@table @code
+@headitem Key exchange @tab Description
 
-@item RSA:
+@item RSA @tab
 The RSA algorithm is used to encrypt a key and send it to the peer.
 The certificate must allow the key to be used for encryption.
 
-@item RSA_EXPORT:
+@item RSA_EXPORT @tab
 The RSA algorithm is used to encrypt a key and send it to the peer.
 In the EXPORT algorithm, the server signs temporary RSA parameters of
 512 bits --- which are considered weak --- and sends them to the
 client.
 
-@item DHE_RSA:
+@item DHE_RSA @tab
 The RSA algorithm is used to sign ephemeral Diffie-Hellman parameters
 which are sent to the peer. The key in the certificate must allow the
 key to be used for signing. Note that key exchange algorithms which
@@ -143,26 +144,28 @@ use ephemeral Diffie-Hellman parameters, offer perfect forward
 secrecy. That means that even if the private key used for signing is
 compromised, it cannot be used to reveal past session data.
 
-@item ECDHE_RSA:
+@item ECDHE_RSA @tab
 The RSA algorithm is used to sign ephemeral elliptic curve Diffie-Hellman 
 parameters which are sent to the peer. The key in the certificate must allow 
 the key to be used for signing. It also offers perfect forward
 secrecy. That means that even if the private key used for signing is
 compromised, it cannot be used to reveal past session data.
 
-@item DHE_DSS:
+@item DHE_DSS @tab
 The DSA algorithm is used to sign ephemeral Diffie-Hellman parameters
 which are sent to the peer. The certificate must contain DSA
 parameters to use this key exchange algorithm. DSA is the algorithm
 of the Digital Signature Standard (DSS).
 
-@item ECDHE_ECDSA:
+@item ECDHE_ECDSA @tab
 The Elliptic curve DSA algorithm is used to sign ephemeral elliptic
 curve Diffie-Hellman parameters which are sent to the peer. The 
 certificate must contain ECDSA parameters to use this key exchange 
 algorithm. 
 
-@end table
+@end multitable
+@caption{Supported key exchange algorithms.}
+@end float
 
 @node Anonymous authentication
 @section Anonymous Authentication
@@ -241,28 +244,20 @@ authenticated using a certificate with RSA parameters.
 @end table
 
 If clients supporting @acronym{SRP} know the username and password
-before the connection, should initialize the client credentials and
-call the function @funcref{gnutls_srp_set_client_credentials}.
-Alternatively they could specify a callback function by using the
-function @funcref{gnutls_srp_set_client_credentials_function}.  This has
-the advantage that allows probing the server for @acronym{SRP}
-support.  In that case the callback function will be called twice per
-handshake.  The first time is before the ciphersuite is negotiated,
-and if the callback returns a negative error code, the callback will
-be called again if @acronym{SRP} has been negotiated.  This uses a
-special @acronym{TLS}-@acronym{SRP} handshake idiom in order to avoid,
-in interactive applications, to ask the user for @acronym{SRP}
-password and username if the server does not negotiate an
-@acronym{SRP} ciphersuite.
+before the connection, should initialize client credentials and
+call @funcref{gnutls_srp_set_client_credentials}.
+Alternatively @funcref{gnutls_srp_set_client_credentials_function}
+may be used to specify a callback function.
+The callback will be called once during the @acronym{TLS} handshake.
 
 In server side the default behaviour of @acronym{GnuTLS} is to read
 the usernames and @acronym{SRP} verifiers from password files. These
 password files are the ones used by the @emph{Stanford srp libraries}
-and can be specified using the
-@funcref{gnutls_srp_set_server_credentials_file}.  If a different
-password file format is to be used, then the function
-@funcref{gnutls_srp_set_server_credentials_function}, should be called,
-in order to set an appropriate callback.
+and @funcref{gnutls_srp_set_server_credentials_file} can be used to
+specify them. If a different
+password file format is to be used, then 
+@funcref{gnutls_srp_set_server_credentials_function} should be called,
+to set an appropriate callback.
 
 Some helper functions such as
 
@@ -306,10 +301,10 @@ exchange.  This method offers perfect forward secrecy.
 @end table
 
 Clients supporting @acronym{PSK} should supply the username and key
-before the connection to the client credentials by calling the
-function @funcref{gnutls_psk_set_client_credentials}.  Alternatively they
-could specify a callback function by using the function
-@funcref{gnutls_psk_set_client_credentials_function}.  This has the
+before the TLS session is established by calling 
+@funcref{gnutls_psk_set_client_credentials}.  Alternatively 
+@funcref{gnutls_psk_set_client_credentials_function} can be used to
+specify a callback function. This has the
 advantage that the callback will be called only if @acronym{PSK} has
 been negotiated.
 
@@ -318,12 +313,13 @@ the usernames and @acronym{PSK} keys from a password file. The
 password file should contain usernames and keys in hexadecimal
 format. The name of the password file can be stored to the credentials
 structure by calling @funcref{gnutls_psk_set_server_credentials_file}.  If
-a different password file format is to be used, then the function
-@funcref{gnutls_psk_set_server_credentials_function}, should be used
-instead.
+a different password file format is to be used, then
+a callback should be set instead by @funcref{gnutls_psk_set_server_credentials_function}.
 
 The server can help the client chose a suitable username and password,
-by sending a hint.  In the server, specify the hint by calling
+by sending a hint. Note that there is no common profile for the PSK hint and applications
+are discouraged to use it.
+A server, may specify the hint by calling
 @funcref{gnutls_psk_set_server_credentials_hint}.  The client can retrieve
 the hint, for example in the callback function, using
 @funcref{gnutls_psk_client_get_hint}.
diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi
index c4675ae4ed..26ca9fd2ae 100644
--- a/doc/cha-cert-auth.texi
+++ b/doc/cha-cert-auth.texi
@@ -42,29 +42,34 @@ Detailed examples involving X.509 certificates are listed below.
 
 An @acronym{X.509} certificate usually contains information about the
 certificate holder, the signer, a unique serial number, expiration
-dates and some other fields @xcite{PKIX} as shown in the table below.
+dates and some other fields @xcite{PKIX} as shown in @ref{tab:x509}.
 
-@table @code
+@float Table,tab:x509
+@multitable @columnfractions .3 .7
+
+@headitem Field @tab Description
 
-@item version:
+@item version @tab
 The field that indicates the version of the certificate.
 
-@item serialNumber:
+@item serialNumber @tab
 This field holds a unique serial number per certificate.
 
-@item issuer:
+@item issuer @tab
 Holds the issuer's distinguished name.
 
-@item validity:
+@item validity @tab
 The activation and expiration dates.
 
-@item subject:
+@item subject @tab
 The subject's distinguished name of the certificate.
 
-@item extensions:
+@item extensions @tab
 The extensions are fields only present in version 3 certificates.
 
-@end table
+@end multitable
+@caption{X.509 certificate fields.}
+@end float
 
 The certificate's @emph{subject or issuer name} is not just a single
 string.  It is a Distinguished name and in the @acronym{ASN.1}
@@ -85,40 +90,45 @@ Certificate @emph{extensions} are there to include information about
 the certificate's subject that did not fit in the typical certificate
 fields. Those may be e-mail addresses, flags that indicate whether the
 belongs to a CA etc.  All the supported @acronym{X.509} version 3
-extensions are shown in the table below.
+extensions are shown in @ref{tab:x509-ext}.
 
-@table @code
+@float Table,tab:x509-ext
+@multitable @columnfractions .3 .2 .5
 
-@item subject key id (2.5.29.14):
+@headitem Extension @tab OID @tab Description
+
+@item Subject key id @tab 2.5.29.14 @tab
 An identifier of the key of the subject.
 
-@item authority key id (2.5.29.35):
+@item Authority key id @tab 2.5.29.35 @tab
 An identifier of the authority's key used to sign the certificate.
 
-@item subject alternative name (2.5.29.17):
+@item Subject alternative name @tab 2.5.29.17 @tab
 Alternative names to subject's distinguished name.
 
-@item key usage (2.5.29.15):
+@item Key usage @tab 2.5.29.15 @tab
 Constraints the key's usage of the certificate.
 
-@item extended key usage (2.5.29.37):
+@item Extended key usage @tab 2.5.29.37 @tab
 Constraints the purpose of the certificate.
 
-@item basic constraints (2.5.29.19):
+@item Basic constraints @tab 2.5.29.19 @tab
 Indicates whether this is a CA certificate or not, and specify the
 maximum path lengths of certificate chains.
 
-@item CRL distribution points (2.5.29.31):
+@item CRL distribution points @tab 2.5.29.31 @tab
 This extension is set by the CA, in order to inform about the issued
 CRLs.
 
-@item Proxy Certification Information (1.3.6.1.5.5.7.1.14):
+@item Proxy Certification Information @tab 1.3.6.1.5.5.7.1.14 @tab
 Proxy Certificates includes this extension that contains the OID of
 the proxy policy language used, and can specify limits on the maximum
 lengths of proxy chains.  Proxy Certificates are specified in
 @xcite{RFC3820}.
 
-@end table
+@end multitable
+@caption{X.509 certificate extensions.}
+@end float
 
 In @acronym{GnuTLS} the @acronym{X.509} certificate structures are
 handled using the @code{gnutls_x509_crt_t} type and the corresponding
@@ -185,31 +195,37 @@ authority list has been set via the
 thus it is not required to setup a trusted list as above.
 Convenience functions such as @funcref{gnutls_certificate_verify_peers2} 
 are equivalent and will verify the peer's certificate chain
-in a TLS session.
+in a TLS session. The certificate verification functions output
+codes as in @ref{tab:cert-verify}.
 
-@table @code
+@float Table,tab:cert-verify
+@multitable @columnfractions .55 .45
+
+@headitem Flag @tab Description
 
-@item GNUTLS_CERT_INVALID:
+@item GNUTLS_CERT_INVALID @tab
 The certificate is not signed by one of the known authorities, or
 the signature is invalid.
 
-@item GNUTLS_CERT_REVOKED:
+@item GNUTLS_CERT_REVOKED @tab
 The certificate has been revoked by its CA.
 
-@item GNUTLS_CERT_SIGNER_NOT_FOUND:
+@item GNUTLS_CERT_SIGNER_NOT_FOUND @tab
 The certificate's issuer is not known. This is the case when the
 issuer is not in the trusted certificates list.
 
-@item GNUTLS_CERT_SIGNER_NOT_CA:
+@item GNUTLS_CERT_SIGNER_NOT_CA @tab
 The certificate's signer was not a CA. This may happen if
 this was a version 1 certificate, which is common with some CAs, or
 a version 3 certificate without the basic constrains extension.
 
-@item GNUTLS_CERT_INSECURE_ALGORITHM:
+@item GNUTLS_CERT_INSECURE_ALGORITHM @tab
 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
+@end multitable
+@caption{Certificate verification output flags.}
+@end float
 
 There is also to possibility to pass some input to the verification
 functions in the form of flags. For @funcref{gnutls_x509_trust_list_verify_crt} the
@@ -217,48 +233,53 @@ flags are passed straightforward, but
 @funcref{gnutls_certificate_verify_peers2} depends on the flags set by
 calling @funcref{gnutls_certificate_set_verify_flags}.  All the available
 flags are part of the enumeration
-@code{gnutls_certificate_verify_flags} and are explained in the table
-below.
+@code{gnutls_certificate_verify_flags} and are explained in @ref{tab:cert-flags}.
 
-@table @code
-@item GNUTLS_VERIFY_DISABLE_CA_SIGN:
+@float Table,tab:cert-flags
+@multitable @columnfractions .5 .5
+
+@headitem Flag @tab Description
+@item GNUTLS_VERIFY_\-DISABLE_CA_SIGN @tab
 If set a signer does not have to be a certificate authority. This
 flag should normaly be disabled, unless you know what this means.
 
-@item GNUTLS_VERIFY_ALLOW_X509_V1_CA_CRT:
+@item GNUTLS_VERIFY_\-ALLOW_X509_V1_CA_CRT @tab
 Allow only trusted CA certificates that have version 1.  This is
-safer than GNUTLS_VERIFY_ALLOW_ANY_X509_V1_CA_CRT, and should be
+safer than GNUTLS_VERIFY_\-ALLOW_ANY_X509_V1_CA_CRT, and should be
 used instead. That way only signers in your trusted list will be
 allowed to have certificates of version 1. This is the default.
 
-@item GNUTLS_VERIFY_DO_NOT_ALLOW_X509_V1_CA_CRT:
+@item GNUTLS_VERIFY_\-DO_NOT_ALLOW_X509_V1_CA_CRT @tab
 Do not allow trusted version 1 CA certificates.  This option is to be used
 in order consider all V1 certificates as deprecated.
 
-@item GNUTLS_VERIFY_ALLOW_ANY_X509_V1_CA_CRT:
+@item GNUTLS_VERIFY_\-ALLOW_ANY_X509_V1_CA_CRT @tab
 Allow CA certificates that have version 1 (both root and
 intermediate). This is dangerous since those haven't the
 basicConstraints extension. Must be used in combination with
-GNUTLS_VERIFY_ALLOW_X509_V1_CA_CRT.
+GNUTLS_VERIFY_\-ALLOW_X509_V1_CA_CRT.
 
-@item GNUTLS_VERIFY_DO_NOT_ALLOW_SAME:
+@item GNUTLS_VERIFY_\-DO_NOT_ALLOW_SAME @tab
 If a certificate is not signed by anyone trusted but exists in
 the trusted CA list do not treat it as trusted.
 
-@item GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2:
+@item GNUTLS_VERIFY_\-ALLOW_SIGN_RSA_MD2 @tab
 Allow certificates to be signed using the old MD2 algorithm.
 
-@item GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5:
+@item GNUTLS_VERIFY_\-ALLOW_SIGN_RSA_MD5 @tab
 Allow certificates to be signed using the broken MD5 algorithm.
 
-@item GNUTLS_VERIFY_DISABLE_TIME_CHECKS:
+@item GNUTLS_VERIFY_\-DISABLE_TIME_CHECKS @tab
 Disable checking of activation
 and expiration validity periods of certificate chains. Don't set
 this unless you understand the security implications.
 
-@item GNUTLS_VERIFY_DISABLE_CRL_CHECKS:
+@item GNUTLS_VERIFY_\-DISABLE_CRL_CHECKS @tab
 Disables checking for validity using certificate revocation lists.
-@end table
+
+@end multitable
+@caption{Certificate verification flags.}
+@end float
 
 Although the verification of a certificate path indicates that the
 certificate is signed by trusted authority, does not reveal anything
@@ -431,7 +452,7 @@ the user to insert the token. All the initialization functions are below.
 @end itemize
 
 Note that due to limitations of @acronym{PKCS} #11 there are issues when multiple libraries 
-are sharing a module. To avoid this problem GnuTLS uses p11-kit@footnote{http://p11-glue.freedesktop.org/}
+are sharing a module. To avoid this problem GnuTLS uses p11-kit@footnote{@url{http://p11-glue.freedesktop.org/}}
 that provides a middleware to control access to resources over the
 multiple users.
 
@@ -444,7 +465,7 @@ key on a smart card may be referenced as:
 @example
 pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315; \
 manufacturer=EnterSafe;object=test1;objecttype=public;\
-id=32:f1:53:f3:e3:79:90:b0:86:24:14:10:77:ca:5d:ec:2d:15:fa:ed
+id=32f153f3e37990b08624141077ca5dec2d15faed
 @end example
 
 while the smart card itself can be referenced as:
@@ -680,9 +701,12 @@ signature (2nd preimage resistance).
 
 If you are using @funcref{gnutls_certificate_verify_peers2} to verify the
 certificate chain, you can call
-@funcref{gnutls_certificate_set_verify_flags} with the
-@code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2} or
-@code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5} flag, as in:
+@funcref{gnutls_certificate_set_verify_flags} with the flags:
+@itemize
+@item @code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2}
+@item @code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5}
+@end itemize
+as in the following example:
 
 @smallexample
   gnutls_certificate_set_verify_flags (x509cred,
diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index 632b70ea6a..c30d2be524 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -76,8 +76,9 @@ verbose information on the @acronym{GnuTLS} functions internal flow.
 
 When debugging is not required, important issues, such as detected
 attacks on the protocol still need to be logged. This is provided
-by @funcref{gnutls_global_set_audit_log_function}, that uses a logging
-function that accepts the detected error message and the corresponding
+by the logging function set by
+@funcref{gnutls_global_set_audit_log_function}. The set function
+accepts the detected error message and the corresponding
 TLS session. The session information might be used to derive IP addresses
 or other information about the peer involved.
 
diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi
index 3c4a86624e..8a2cf552f5 100644
--- a/doc/cha-intro-tls.texi
+++ b/doc/cha-intro-tls.texi
@@ -85,9 +85,12 @@ you, call @code{gnutls_transport_set_errno} with the intended errno
 value instead of setting @code{errno} directly.
 
 @acronym{GnuTLS} currently only interprets the EINTR and EAGAIN errno
-values and returns the corresponding @acronym{GnuTLS} error codes
-@code{GNUTLS_E_INTERRUPTED} and @code{GNUTLS_E_AGAIN}.  These values
-are usually returned by interrupted system calls, or when non blocking
+values and returns the corresponding @acronym{GnuTLS} error codes:
+@itemize
+@item @code{GNUTLS_E_INTERRUPTED} 
+@item @code{GNUTLS_E_AGAIN}
+@end itemize
+These values are usually returned by interrupted system calls, or when non blocking
 IO is used.  All @acronym{GnuTLS} functions can be resumed (called
 again), if any of these error codes is returned.  The error codes
 above refer to the system call, not the @acronym{GnuTLS} function,
@@ -158,69 +161,75 @@ just after the handshake protocol has finished.
 @cindex Symmetric encryption algorithms
 
 Confidentiality in the record layer is achieved by using symmetric
-block encryption algorithms like @code{3DES}, @code{AES}@footnote{AES,
-or Advanced Encryption Standard, is actually the RIJNDAEL algorithm.
-This is the algorithm that replaced DES.}, or stream algorithms like
-@code{ARCFOUR_128}@footnote{@code{ARCFOUR_128} is a compatible
-algorithm with RSA's RC4 algorithm, which is considered to be a trade
-secret.}. Ciphers are encryption algorithms that use a single, secret,
+block encryption algorithms like @code{3DES}, @code{AES}
+or stream algorithms like @code{ARCFOUR_128}.
+ Ciphers are encryption algorithms that use a single, secret,
 key to encrypt and decrypt data. Block algorithms in TLS also provide
 protection against statistical analysis of the data.  Thus, if you're
 using the @acronym{TLS} protocol, a random number of blocks will be
 appended to data, to prevent eavesdroppers from guessing the actual
 data size.
 
-Supported cipher algorithms:
+The supported in @acronym{GnuTLS} ciphers and MAC algorithms are shown in @ref{tab:ciphers} and
+@ref{tab:macs}.
 
-@table @code
-@item 3DES_CBC:
+@float Table,tab:ciphers
+@multitable @columnfractions .30 .70
+@headitem Algorithm @tab Description
+@item 3DES_CBC @tab
 This is the DES block cipher algorithm used with triple
 encryption (EDE). Has 64 bits block size and is used in CBC mode.
 
-@item ARCFOUR_128:
-A fast stream cipher.
+@item ARCFOUR_128 @tab
+ARCFOUR_128 is a compatible algorithm with RSA's RC4 algorithm, which is considered to be a trade
+secret. It is a fast cipher but considered weak today.
 
-@item ARCFOUR_40:
+@item ARCFOUR_40 @tab
 This is the ARCFOUR cipher fed with a 40 bit key,
 which is considered weak.
 
-@item AES_CBC:
+@item AES_CBC @tab
 AES or RIJNDAEL is the block cipher algorithm that replaces the old
 DES algorithm.  Has 128 bits block size and is used in CBC mode.
 
-@item AES_GCM:
+@item AES_GCM @tab
 This is the AES algorithm in the authenticated encryption GCM mode.
 This mode combines message authentication and encryption and can
 be extremely fast on CPUs that support hardware acceleration.
 
-@item CAMELLIA_CBC:
+@item CAMELLIA_CBC @tab
 This is an 128-bit block cipher developed by Mitsubish and NTT. It
 is one of the approved ciphers of the European NESSIE and Japanese
 CRYPTREC projects.
 
-@end table
-
+@end multitable
+@caption{Supported ciphers.}
+@end float
 
-Supported MAC algorithms:
 
-@table @code
-@item MAC_MD5:
+@float Table,tab:macs
+@multitable @columnfractions .30 .70
+@headitem Algorithm @tab Description
+@item MAC_MD5 @tab
 This is a cryptographic hash algorithm designed by Ron Rivest. Outputs
 128 bits of data.
 
-@item MAC_SHA1:
+@item MAC_SHA1 @tab
 A cryptographic hash algorithm designed by NSA. Outputs 160
 bits of data.
 
-@item MAC_SHA256:
+@item MAC_SHA256 @tab
 A cryptographic hash algorithm designed by NSA. Outputs 256
 bits of data.
 
-@item MAC_AEAD:
+@item MAC_AEAD @tab
 This indicates that an authenticated encryption algorithm, such as
 GCM, is in use.
 
-@end table
+@end multitable
+@caption{Supported MAC algorithms.}
+@end float
+
 
 @node Compression algorithms used in the record layer
 @subsection Compression Algorithms Used in the Record Layer
@@ -307,7 +316,7 @@ different incoming IP addresses.
 
 To enable the workaround in the @command{gnutls-cli} client or the
 @command{gnutls-serv} server, for testing of other implementations, use
-the following parameter: @option{--priority "NORMAL:%COMPAT"}.
+the parameter: @option{--priority "NORMAL:%COMPAT"}.
 
 
 @node The TLS Alert Protocol
@@ -392,8 +401,8 @@ To initiate the handshake.
 @subsection TLS Cipher Suites
 
 The Handshake Protocol of @acronym{TLS} negotiates cipher suites of
-the form @code{TLS_DHE_RSA_WITH_3DES_CBC_SHA}.  The usual cipher
-suites contain these parameters:
+a special form illustrated by the @code{TLS_DHE_RSA_WITH_3DES_CBC_SHA} cipher suite name.  A typical cipher
+suite contains these parameters:
 
 @itemize
 
@@ -422,45 +431,50 @@ All the supported ciphersuites are shown in @ref{ciphersuites}.
 In order to specify cipher suite preferences, the
 previously shown priority functions accept a string
 that specifies the algorithms to be enabled in a TLS handshake.
-That string may contain some high level keyword such as:
+That string may contain some high level keyword such as
+the keywords in @ref{tab:prio-keywords}.
 
-@table @asis
-@item PERFORMANCE:
+@float Table,tab:prio-keywords
+@multitable @columnfractions .30 .70
+@headitem Keyword @tab Description
+@item PERFORMANCE @tab
 All the "secure" ciphersuites are enabled,
 limited to 128 bit ciphers and sorted by terms of speed
 performance.
 
-@item NORMAL:
+@item NORMAL @tab
 Means all "secure" ciphersuites. The 256-bit ciphers are
 included as a fallback only.  The ciphers are sorted by security
 margin.
 
-@item SECURE128: 
+@item SECURE128 @tab
 Means all "secure" ciphersuites of security level 128-bit
 or more.
 
-@item SECURE192:
+@item SECURE192 @tab
 Means all "secure" ciphersuites of security level 192-bit
 or more.
 
-@item SUITEB128: 
+@item SUITEB128 @tab
 Means all the NSA Suite B cryptography (RFC5430) ciphersuites
 with an 128 bit security level.
 
-@item SUITEB192:
+@item SUITEB192 @tab
 Means all the NSA Suite B cryptography (RFC5430) ciphersuites
 with an 192 bit security level.
 
-@item EXPORT:
+@item EXPORT @tab
 Means all ciphersuites are enabled, including the
 low-security 40 bit ciphers.
 
-@item NONE:
+@item NONE @tab
 Means nothing is enabled.  This disables even protocols and
 compression methods. It should be followed by the
 algorithms to be enabled.
 
-@end table
+@end multitable
+@caption{Supported priority string keywords.}
+@end float
 
 or it might contain special keywords, that will be explained
 later on.
@@ -481,7 +495,9 @@ this string you have to prefix it with "COMP-", protocol versions
 with "VERS-", signature algorithms with "SIGN-" and certificate types with "CTYPE-". All other
 algorithms don't need a prefix.}. The order with which every algorithm
 is specified is significant. Similar algorithms specified before others
-will take precedence.
+will take precedence. The individual algorithms are shown in @ref{tab:prio-algorithms}
+and special keywords are in @ref{tab:prio-special}.
+
 
 Keywords prepended to individual algorithms:
 @table @asis
@@ -494,57 +510,63 @@ appended with an algorithm will add this algorithm.
 
 @end table
 
-Individual algorithms:
-@table @asis
-@item Ciphers: 
+
+@float Table,tab:prio-algorithms
+@multitable @columnfractions .30 .70
+@headitem Type @tab Keywords
+@item Ciphers @tab
 AES-128-CBC, AES-256-CBC, AES-128-GCM, CAMELLIA-128-CBC,
 CAMELLIA-256-CBC, ARCFOUR-128, 3DES-CBC ARCFOUR-40. Catch all
 name is CIPHER-ALL which will add all the algorithms from NORMAL
 priority.
 
-@item Key exchange: 
+@item Key exchange @tab
 RSA, DHE-RSA, DHE-DSS, SRP, SRP-RSA, SRP-DSS,
 PSK, DHE-PSK, ECDHE-RSA, ANON-ECDH, ANON-DH, RSA-EXPORT. The
 Catch all name is KX-ALL which will add all the algorithms from NORMAL
 priority.
 
-@item MAC: 
+@item MAC @tab
 MD5, SHA1, SHA256, AEAD (used with
 GCM ciphers only). All algorithms from NORMAL priority can be accessed with MAC-ALL.
 
-@item Compression algorithms: 
+@item Compression algorithms @tab
 COMP-NULL, COMP-DEFLATE. Catch all is COMP-ALL.
 
-@item TLS versions: 
+@item TLS versions @tab
 VERS-SSL3.0, VERS-TLS1.0, VERS-TLS1.1,
 VERS-TLS1.2. Catch all is VERS-TLS-ALL.
 
-@item Signature algorithms: 
+@item Signature algorithms @tab
 SIGN-RSA-SHA1, SIGN-RSA-SHA224, 
 SIGN-RSA-SHA256, SIGN-RSA-SHA384, SIGN-RSA-SHA512, SIGN-DSA-SHA1, 
 SIGN-DSA-SHA224, SIGN-DSA-SHA256, SIGN-RSA-MD5. Catch all
 is SIGN-ALL. This is only valid for TLS 1.2 and later.
 
-@item Elliptic curves:
+@item Elliptic curves @tab
 CURVE-SECP224R1, CURVE-SECP256R1, CURVE-SECP384R1, CURVE-SECP521R1. Catch all is CURVE-ALL.
 
-@end table
+@end multitable
+@caption{The supported priority strings.}
+@end float
 
 
-Special keywords:
-@table @asis
 
-@item %COMPAT:
+@float Table,tab:prio-special
+@multitable @columnfractions .50 .50
+@headitem Keyword @tab Description
+
+@item %COMPAT @tab
 will enable compatibility mode. It might mean that violations
 of the protocols are allowed as long as maximum compatibility with
 problematic clients and servers is achieved.
 
-@item %DISABLE_SAFE_RENEGOTIATION:
+@item %DISABLE_SAFE_RENEGOTIATION @tab
 will disable safe renegotiation
 completely.  Do not use unless you know what you are doing.
 Testing purposes only.
 
-@item %UNSAFE_RENEGOTIATION:
+@item %UNSAFE_RENEGOTIATION @tab
 will allow handshakes and rehandshakes
 without the safe renegotiation extension.  Note that for clients
 this mode is insecure (you may be under attack), and for servers it
@@ -552,32 +574,34 @@ will allow insecure clients to connect (which could be fooled by an
 attacker).  Do not use unless you know what you are doing and want
 maximum compatibility.
 
-@item %PARTIAL_RENEGOTIATION:
+@item %PARTIAL_RENEGOTIATION @tab
 will allow initial handshakes to proceed,
 but not rehandshakes.  This leaves the client vulnerable to attack,
 and servers will be compatible with non-upgraded clients for
 initial handshakes.  This is currently the default for clients and
 servers, for compatibility reasons.
 
-@item %SAFE_RENEGOTIATION:
+@item %SAFE_RENEGOTIATION @tab
 will enforce safe renegotiation.  Clients and
 servers will refuse to talk to an insecure peer.  Currently this
 causes operability problems, but is required for full protection.
 
-@item %SSL3_RECORD_VERSION:
+@item %SSL3_RECORD_VERSION @tab
 will use SSL3.0 record version in client hello.
 This is the default.
 
-@item %LATEST_RECORD_VERSION:
+@item %LATEST_RECORD_VERSION @tab
 will use the latest TLS version record version in client hello.
 
-@item %VERIFY_ALLOW_SIGN_RSA_MD5:
+@item %VERIFY_ALLOW_SIGN_RSA_MD5 @tab
 will allow RSA-MD5 signatures in certificate chains.
 
-@item %VERIFY_ALLOW_X509_V1_CA_CRT:
+@item %VERIFY_ALLOW_X509_V1_CA_CRT @tab
 will allow V1 CAs in chains.
 
-@end table
+@end multitable
+@caption{Special priority string keywords.}
+@end float
 
 @node Client Authentication
 @subsection Client Authentication
diff --git a/doc/cha-library.texi b/doc/cha-library.texi
index 84e88e8a99..74865237fa 100644
--- a/doc/cha-library.texi
+++ b/doc/cha-library.texi
@@ -115,7 +115,7 @@ negative number indicates failure, or a situation that some action has
 to be taken. Thus negative error codes may be fatal or not.
 
 Fatal errors terminate the connection immediately and further sends
-and receives will be disallowed. An example of a fatal error code is
+and receives will be disallowed.  Such an example is
 @code{GNUTLS_E_DECRYPTION_FAILED}. Non-fatal errors may warn about
 something, i.e., a warning alert was received, or indicate the some
 action has to be taken. This is the case with the error code
@@ -206,10 +206,10 @@ data to the transport layer.
 
 @end itemize
 
-Other callback functions such as the one set by
-@funcref{gnutls_srp_set_server_credentials_function}, may require more
-complicated input, including data to be allocated.  These callbacks
-should allocate and free memory using the functions shown below.
+Other callback functions may require more complicated input and data
+to be allocated. Such an example is 
+@funcref{gnutls_srp_set_server_credentials_function}.
+All callbacks should allocate and free memory using the functions shown below.
 
 @itemize
 
diff --git a/doc/cha-programs.texi b/doc/cha-programs.texi
index e8f7e62503..bbdfade5c3 100644
--- a/doc/cha-programs.texi
+++ b/doc/cha-programs.texi
@@ -417,7 +417,7 @@ like:
 @smallexample
 $ gnutls-cli -p 5556 test.gnutls.org --pskusername jas \
   --pskkey 9e32cf7786321a828ef7668f09fb35db \
-  --priority NORMAL:+DHE-PSK:+PSK:-RSA:-DHE-RSA
+  --priority NORMAL:-KX-ALL:+ECDHE-PSK:DHE-PSK:+PSK
 @end smallexample
 
 @menu
@@ -450,13 +450,13 @@ Enter password:
 @end smallexample
 
 If the server supports several cipher suites, you may need to force it
-to chose PSK by using a cipher priority parameter such as
-@option{--priority NORMAL:+PSK:-RSA:-DHE-RSA:-DHE-PSK}.
+to chose PSK by using a cipher priority parameter such as in the
+example below:
 
 @smallexample
 $ ./gnutls-cli -p 5556 localhost --pskusername psk_identity \
   --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 \
-  --priority NORMAL:+DHE-PSK:+PSK
+  --priority NORMAL:-KX-ALL:+ECDHE-PSK:+DHE-PSK:+PSK
 Resolving 'localhost'...
 Connecting to '127.0.0.1:5556'...
 - PSK authentication.
diff --git a/doc/scripts/mytexi2latex b/doc/scripts/mytexi2latex
index aa547665e9..fe7ea2dd60 100755
--- a/doc/scripts/mytexi2latex
+++ b/doc/scripts/mytexi2latex
@@ -88,9 +88,14 @@ while ($line = <FILE>) {
                         $mode = pop(@stack);
                 } else {
 			$line =~ s/\@caption\{/\\caption\{/g;
-			$line =~ s/\@multitable \@columnfractions ([\.\d]+) ([\.\d]+) ([\.\d]+)$/\n\\begin{tabular}{|p{3.3cm}|p{3.3cm}|p{4.3cm}|}\n\\hline\n/g;
-			$line =~ s/\@multitable \@columnfractions ([\.\d]+) ([\.\d]+) ([\.\d]+) ([\.\d]+) ([\.\d]+)$/\n\\begin{tabular}{|p{2cm}|p{2cm}|p{2cm}|p{2cm}|p{3cm}|}\n\\hline\n/g;
-			push(@stack, FLOAT_TABLE);
+
+			if ($line =~ m/\@multitable/) {
+				push(@stack, FLOAT_TABLE);
+				$line =~ s/\@multitable \@columnfractions ([\.\d]+) ([\.\d]+)$/\n\\begin{tabular}{|p{$1\\linewidth}|p{$2\\linewidth}|}\n\\hline\n/g;
+				$line =~ s/\@multitable \@columnfractions ([\.\d]+) ([\.\d]+) ([\.\d]+)$/\n\\begin{tabular}{|p{$1\\linewidth}|p{$2\\linewidth}|p{$3\\linewidth}|}\n\\hline\n/g;
+				$line =~ s/\@multitable \@columnfractions ([\.\d]+) ([\.\d]+) ([\.\d]+) ([\.\d]+) ([\.\d]+)$/\n\\begin{tabular}{|p{$1\\linewidth}|p{$2\\linewidth}|p{$3\\linewidth}|p{$4\\linewidth}|p{$5\\linewidth}|}\n\\hline\n/g;
+			}
+			
 			goto multitable;
 		}
 		$prev_mode = $mode;
@@ -166,8 +171,8 @@ multitable:
         } else {
 		$prev_mode = $mode;
 
-		$line =~ s/\@iftex/% /g;
-		$line =~ s/\@end iftex/% /g;
+		$line =~ s/\@iftex/%c /g;
+		$line =~ s/\@end iftex/%c /g;
                 $line =~ s/\@anchor (.+)/\\label{$1}/g;
 		$line =~ s/\@anchor\{($spacematch+)\}/\\label{$1}/g;
 		if ($line =~ s/\@subsection (.+)/\\subsection{$1}/g) {
@@ -235,11 +240,15 @@ multitable:
                         push(@stack, NORMAL);
                         $mode = TABLE_ITEMIZE;
                 }
-                if ($line =~ s/\@multitable \@columnfractions ([\.\d]+) ([\.\d]+) ([\.\d]+)$/\n\\begin{tabular}{|p{3.3cm}|p{3.3cm}|p{4.3cm}|}\n\\hline\n/g) {
+                if ($line =~ s/\@multitable \@columnfractions ([\.\d]+) ([\.\d]+)$/\n\\begin{tabular}{|p{$1\\linewidth}|p{$2\\linewidth}|}\n\\hline\n/g) {
+                        push(@stack, NORMAL);
+                        $mode = MULTITABLE;
+                }
+                if ($line =~ s/\@multitable \@columnfractions ([\.\d]+) ([\.\d]+) ([\.\d]+)$/\n\\begin{tabular}{|p{$1\\linewidth}|p{$2\\linewidth}|p{$3\\linewidth}|}\n\\hline\n/g) {
                         push(@stack, NORMAL);
                         $mode = MULTITABLE;
                 }
-                if ($line =~ s/\@multitable \@columnfractions ([\.\d]+) ([\.\d]+) ([\.\d]+) ([\.\d]+) ([\.\d]+)$/\n\\begin{tabular}{|p{2cm}|p{2cm}|p{2cm}|p{2cm}|p{3cm}|}\n\\hline\n/g) {
+                if ($line =~ s/\@multitable \@columnfractions ([\.\d]+) ([\.\d]+) ([\.\d]+) ([\.\d]+) ([\.\d]+)$/\n\\begin{tabular}{|p{$1\\linewidth}|p{$2\\linewidth}|p{$3\\linewidth}|p{$4\\linewidth}|p{$5\\linewidth}|}\n\\hline\n/g) {
                         push(@stack, NORMAL);
                         $mode = MULTITABLE;
                 }
@@ -264,7 +273,7 @@ multitable:
 	if ($verbatim == 0) {
 		$line =~ s/\_/\\_/g;
 		$line =~ s/\~/\\~/g;
-		$line =~ s/\%/\\%/g;
+		$line =~ s/\%(?!c)/\\%/g;
 		$line =~ s/\#/\\\#/g;
                 $line =~ s/\@verbatiminclude (.*)/\\examplefile{\.\.\/$1}/g;
 		$line =~ s/\@image\{($match+)\,($match+)\}/\\includegraphics\[width\=$2\]\{\.\.\/$1\.pdf\}/g;