Add documentation for the Emacs GnuTLS integration.

* info/dir (File):
* Makefile.in: Add emacs-gnutls to the info directory and the
INFO_FILES target.

* doc/misc/emacs-gnutls.texi: Add documentation for the GnuTLS integration.

* doc/misc/gnutls.texi: New file to explain the GnuTLS integration.

* doc/misc/Makefile.in: Add gnutls.texi to build.

6 files changed, 230 insertions, 5 deletions

diff --git a/ChangeLog b/ChangeLog
index 2fe50a6d83b..a1b9a9ca7df 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2012-04-09  Teodor Zlatanov  <tzz@lifelogs.com>
+
+        * info/dir (File):
+        * Makefile.in: Add emacs-gnutls to the info directory and the
+        INFO_FILES target.
+
 2012-04-09  Glenn Morris  <rgm@gnu.org>
 
         * Makefile.in (leim): Check cd return value.  Pass fewer variables.
diff --git a/Makefile.in b/Makefile.in
index 3ee5e8ae8ed..8851384162b 100644
--- a/Makefile.in
+++ b/Makefile.in
@@ -136,11 +136,11 @@ MAN_PAGES=ctags.1 ebrowse.1 emacs.1 emacsclient.1 etags.1 \
 # system, it is inappropriate to imply that it is part of Emacs.
 infodir=@infodir@
 INFO_FILES=ada-mode auth autotype calc ccmode cl dbus dired-x ebrowse   \
-           ede ediff edt eieio efaq eintr elisp emacs emacs-mime epa erc \
-           ert eshell eudc flymake forms gnus idlwave info mairix-el    \
-           message mh-e newsticker nxml-mode org pcl-cvs pgg rcirc      \
-           reftex remember sasl sc semantic ses sieve smtpmail speedbar \
-           tramp url vip viper widget woman
+           ede ediff edt eieio efaq eintr elisp emacs emacs-gnutls      \
+           emacs-mime epa erc ert eshell eudc flymake forms gnus        \
+           idlwave info mairix-el message mh-e newsticker nxml-mode     \
+           org pcl-cvs pgg rcirc reftex remember sasl sc semantic ses   \
+           sieve smtpmail speedbar tramp url vip viper widget woman
 
 # If no makeinfo was found and configured --without-makeinfo, "no"; else "yes".
 HAVE_MAKEINFO=@HAVE_MAKEINFO@
diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index e2f2c949676..ee6b7606c55 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,11 @@
+2012-04-09  Teodor Zlatanov  <tzz@lifelogs.com>
+
+        * Makefile.in: Add gnutls.texi to build.
+
+        * gnutls.texi: New file to explain the GnuTLS integration.
+
+        * emacs-gnutls.texi: Add documentation for the GnuTLS integration.
+
 2012-04-05  Teodor Zlatanov  <tzz@lifelogs.com>
 
         * auth.texi (Secret Service API): Edit further and give examples.
diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in
index 6fd0b983b87..429b84abf8f 100644
--- a/doc/misc/Makefile.in
+++ b/doc/misc/Makefile.in
@@ -68,6 +68,7 @@ INFO_TARGETS = \
         $(infodir)/flymake \
         $(infodir)/forms \
         $(infodir)/gnus \
+        $(infodir)/emacs-gnutls \
         $(infodir)/idlwave \
         $(infodir)/info \
         $(infodir)/mairix-el \
@@ -119,6 +120,7 @@ DVI_TARGETS = \
         flymake.dvi \
         forms.dvi \
         gnus.dvi \
+        emacs-gnutls.dvi \
         idlwave.dvi \
         info.dvi \
         mairix-el.dvi \
@@ -170,6 +172,7 @@ PDF_TARGETS = \
         flymake.pdf \
         forms.pdf \
         gnus.pdf \
+        emacs-gnutls.pdf \
         idlwave.pdf \
         info.pdf \
         mairix-el.pdf \
@@ -342,6 +345,15 @@ eieio.dvi: ${srcdir}/eieio.texi
 eieio.pdf: ${srcdir}/eieio.texi
         $(ENVADD) $(TEXI2PDF) $<
 
+emacs-gnutls : $(infodir)/emacs-gnutls
+$(infodir)/emacs-gnutls: emacs-gnutls.texi
+        $(mkinfodir)
+        cd $(srcdir); $(MAKEINFO) $(MAKEINFO_OPTS) $<
+emacs-gnutls.dvi: ${srcdir}/emacs-gnutls.texi
+        $(ENVADD) $(TEXI2DVI) $<
+emacs-gnutls.pdf: ${srcdir}/emacs-gnutls.texi
+        $(ENVADD) $(TEXI2PDF) $<
+
 emacs-mime : $(infodir)/emacs-mime
 $(infodir)/emacs-mime: emacs-mime.texi
         $(mkinfodir)
diff --git a/doc/misc/emacs-gnutls.texi b/doc/misc/emacs-gnutls.texi
new file mode 100644
index 00000000000..d429f21fbf6
--- /dev/null
+++ b/doc/misc/emacs-gnutls.texi
@@ -0,0 +1,198 @@
+\input texinfo                  @c -*-texinfo-*-
+
+@setfilename ../../info/emacs-gnutls
+@settitle Emacs GnuTLS Integration @value{VERSION}
+
+@set VERSION 0.3
+
+@copying
+This file describes the Emacs GnuTLS integration.
+
+Copyright @copyright{} 2012 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below.  A copy of the license
+is included in the section entitled ``GNU Free Documentation License''
+in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
+modify this GNU manual.  Buying copies from the FSF supports it in
+developing GNU and promoting software freedom.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License.  If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs lisp libraries
+@direntry
+* GnuTLS: (gnutls).          The Emacs GnuTLS Integration.
+@end direntry
+
+@titlepage
+@title Emacs GnuTLS Integration
+@author by Ted Zlatanov
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top Emacs GnuTLS
+This manual describes the Emacs GnuTLS integration.
+
+GnuTLS is a library that establishes encrypted @acronym{SSL} or
+@acronym{TLS} connections.  Emacs supports it through the
+@file{gnutls.c} and @file{gnutls.h} C files and the @file{gnutls.el}
+Emacs Lisp library.
+
+@insertcopying
+
+@menu
+* Overview::                    Overview of the GnuTLS integration.
+* Help For Users::
+* Help For Developers::
+* Function Index::
+* Variable Index::
+@end menu
+@end ifnottex
+
+@node Overview
+@chapter Overview
+
+The GnuTLS library is an optional add-on for Emacs.  Through it, any
+Emacs Lisp program can establish encrypted network connections that
+use @dfn{Secure Socket Layer} (@acronym{SSL}) and @dfn{Transport Layer
+Security} (@acronym{TLS}) protocols.  The process of using
+@acronym{SSL} and @acronym{TLS} in establishing connections is as
+automated and transparent as possible.
+
+The user has only a few customization options currently: the log
+level, priority string, trustfile list, and the minimum number of bits
+to be used in Diffie-Hellman key exchange.  Rumors that every Emacs
+library requires at least 83 customizable variables are thus proven
+false.
+
+@node Help For Users
+@chapter Help For Users
+
+From the user's perspective, there's nothing to the GnuTLS
+integration.  It Just Works for any Emacs Lisp code that uses
+@code{open-protocol-stream} or @code{open-network-stream}
+(@pxref{Network,, Network Connections, elisp, The Emacs Lisp Reference
+Manual}).  The two functions are equivalent, the first one being an
+alias of the second.
+
+There's one way to find out if GnuTLS is available, by calling
+@code{gnutls-available-p}.  This is a little bit trickier on the W32
+(Windows) platform, but if you have the GnuTLS DLLs (available from
+@url{http://sourceforge.net/projects/ezwinports/files/} thanks to Eli
+Zaretskii) in the same directory as Emacs, you should be OK.
+
+@defun gnutls-available-p
+This function returns t if GnuTLS is available in this instance of Emacs.
+@end defun
+
+Oh, but sometimes things go wrong.  Budgets aren't balanced,
+television ads lie, and even TLS and SSL connections can fail to work
+properly.  Well, there's something to be done in the last case.
+
+@defvar gnutls-log-level
+The @code{gnutls-log-level} variable sets the log level.  1 is
+verbose.  2 is very verbose.  5 is crazy.  Crazy!  Set it to 1 or 2
+and look in the @code{*Messages*} buffer for the debugging
+information.
+@end defvar
+
+@defvar gnutls-algorithm-priority
+The @code{gnutls-algorithm-priority} variable sets the GnuTLS priority
+string.  This is global, not per host name (although
+@code{gnutls-negotiate} supports a priority string per connection so
+it could be done if needed).  The priority string syntax is in the
+@uref{http://www.gnu.org/software/gnutls/documentation.html, GnuTLS
+documentation}.
+@end defvar
+
+@defvar gnutls-trustfiles
+The @code{gnutls-trustfiles} variable is a list of trustfiles
+(certificates for the issuing authorities).  This is global, not per
+host name (although @code{gnutls-negotiate} supports a trustfile per
+connection so it could be done if needed).  The trustfiles can be in
+PEM or DER format and examples can be found in most Unix
+distributions.  By default four locations are tried in this order:
+@file{/etc/ssl/certs/ca-certificates.crt} for Debian, Ubuntu, Gentoo
+and Arch Linux; @file{/etc/pki/tls/certs/ca-bundle.crt} for Fedora
+and RHEL; @file{/etc/ssl/ca-bundle.pem} for Suse;
+@file{/usr/ssl/certs/ca-bundle.crt} for Cygwin.  You can easily
+customize @code{gnutls-trustfiles} to be something else, but let us
+know if you do, so we can make the change to benefit the other users
+of that platform.
+@end defvar
+
+@defvar gnutls-min-prime-bits
+The @code{gnutls-min-prime-bits} variable is a pretty exotic
+customization for cases where you want to refuse handshakes with keys
+under a specific size.  If you don't know for sure that you need it,
+you don't.  Leave it @code{nil}.
+@end defvar
+
+@node Help For Developers
+@chapter Help For Developers
+
+The GnuTLS library is detected automatically at compile time.  You
+should see that it's enabled in the @code{configure} output.  If not,
+follow the standard procedure for finding out why a system library is
+not picked up by the Emacs compilation.  On the W32 (Windows)
+platform, installing the DLLs with a recent build should be enough.
+
+Just use @code{open-protocol-stream} or @code{open-network-stream}
+(the two are equivalent, the first one being an alias to the second).
+You should not have to use the @file{gnutls.el} functions directly.
+But you can test them with @code{open-gnutls-stream}.
+
+@defun open-gnutls-stream name buffer host service
+This function creates a buffer connected to a specific @var{host} and
+@var{service} (port number or service name).  The parameters and their
+syntax are the same as those given to @code{open-network-stream}
+(@pxref{Network,, Network Connections, elisp, The Emacs Lisp Reference
+Manual}).  The connection process is called @var{name} (made unique if
+necessary).  This function returns the connection process.
+
+@lisp
+;; open a HTTPS connection
+(open-gnutls-stream "tls" "tls-buffer" "yourserver.com" "https")
+
+;; open a IMAPS connection
+(open-gnutls-stream "tls" "tls-buffer" "imap.gmail.com" "imaps")
+@end lisp
+
+@end defun
+
+The function @code{gnutls-negotiate} is not generally useful and it
+may change as needed, so please see @file{gnutls.el} for the details.
+
+@defun gnutls-negotiate spec
+Please see @file{gnutls.el} for the @var{spec} details and for usage,
+but do not rely on this function's interface if possible.
+@end defun
+
+@node Function Index
+@chapter Function Index
+@printindex fn
+
+@node Variable Index
+@chapter Variable Index
+@printindex vr
+
+@bye
+
+@c End:
diff --git a/info/dir b/info/dir
index 06ee2ab8240..d18a38cefa6 100644
--- a/info/dir
+++ b/info/dir
@@ -40,6 +40,7 @@ Emacs editing modes
 Emacs network features
 * EUDC: (eudc).                 Emacs client for directory servers (LDAP, PH).
 * Gnus: (gnus).                 The newsreader Gnus.
+* GnuTLS: (emacs-gnutls).       The Emacs GnuTLS integration.
 * Mairix: (mairix-el).          Emacs interface to the Mairix mail indexer.
 * MH-E: (mh-e).                 Emacs interface to the MH mail system.
 * Message: (message).           Mail and news composition mode that