[Emacs-diffs] /srv/bzr/emacs/emacs-24 r107814: Add documentation for the Emacs GnuTLS integration.

[Ted Zlatanov]

------------------------------------------------------------
revno: 107814
committer: Ted Zlatanov <address@hidden>
branch nick: quickfixes
timestamp: Mon 2012-04-09 09:10:22 -0400
message:
  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.
added:
  doc/misc/emacs-gnutls.texi
modified:
  ChangeLog
  Makefile.in
  doc/misc/ChangeLog
  doc/misc/Makefile.in
  info/dir

=== modified file 'ChangeLog'
--- a/ChangeLog 2012-04-09 06:40:20 +0000
+++ b/ChangeLog 2012-04-09 13:10:22 +0000
@@ -1,3 +1,9 @@
+2012-04-09  Teodor Zlatanov  <address@hidden>
+
+       * info/dir (File):
+       * Makefile.in: Add emacs-gnutls to the info directory and the
+       INFO_FILES target.
+
 2012-04-09  Glenn Morris  <address@hidden>
 
        * Makefile.in (leim): Check cd return value.  Pass fewer variables.

=== modified file 'Makefile.in'
--- a/Makefile.in       2012-04-09 06:40:20 +0000
+++ b/Makefile.in       2012-04-09 13:10:22 +0000
@@ -136,11 +136,11 @@
 # system, it is inappropriate to imply that it is part of Emacs.
 address@hidden@
 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".
 address@hidden@

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2012-04-06 01:56:38 +0000
+++ b/doc/misc/ChangeLog        2012-04-09 13:10:22 +0000
@@ -1,3 +1,11 @@
+2012-04-09  Teodor Zlatanov  <address@hidden>
+
+       * 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  <address@hidden>
 
        * auth.texi (Secret Service API): Edit further and give examples.

=== modified file 'doc/misc/Makefile.in'
--- a/doc/misc/Makefile.in      2012-01-19 07:21:25 +0000
+++ b/doc/misc/Makefile.in      2012-04-09 13:10:22 +0000
@@ -68,6 +68,7 @@
        $(infodir)/flymake \
        $(infodir)/forms \
        $(infodir)/gnus \
+       $(infodir)/emacs-gnutls \
        $(infodir)/idlwave \
        $(infodir)/info \
        $(infodir)/mairix-el \
@@ -119,6 +120,7 @@
        flymake.dvi \
        forms.dvi \
        gnus.dvi \
+       emacs-gnutls.dvi \
        idlwave.dvi \
        info.dvi \
        mairix-el.dvi \
@@ -170,6 +172,7 @@
        flymake.pdf \
        forms.pdf \
        gnus.pdf \
+       emacs-gnutls.pdf \
        idlwave.pdf \
        info.pdf \
        mairix-el.pdf \
@@ -342,6 +345,15 @@
 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)

=== added file 'doc/misc/emacs-gnutls.texi'
--- a/doc/misc/emacs-gnutls.texi        1970-01-01 00:00:00 +0000
+++ b/doc/misc/emacs-gnutls.texi        2012-04-09 13:10:22 +0000
@@ -0,0 +1,198 @@
+\input texinfo                  @c -*-texinfo-*-
+
address@hidden ../../info/emacs-gnutls
address@hidden Emacs GnuTLS Integration @value{VERSION}
+
address@hidden VERSION 0.3
+
address@hidden
+This file describes the Emacs GnuTLS integration.
+
+Copyright @copyright{} 2012 Free Software Foundation, Inc.
+
address@hidden
+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.
address@hidden quotation
address@hidden copying
+
address@hidden Emacs lisp libraries
address@hidden
+* GnuTLS: (gnutls).          The Emacs GnuTLS Integration.
address@hidden direntry
+
address@hidden
address@hidden Emacs GnuTLS Integration
address@hidden by Ted Zlatanov
address@hidden
address@hidden 0pt plus 1filll
address@hidden
address@hidden titlepage
+
address@hidden
+
address@hidden
address@hidden Top
address@hidden Emacs GnuTLS
+This manual describes the Emacs GnuTLS integration.
+
+GnuTLS is a library that establishes encrypted @acronym{SSL} or
address@hidden connections.  Emacs supports it through the
address@hidden and @file{gnutls.h} C files and the @file{gnutls.el}
+Emacs Lisp library.
+
address@hidden
+
address@hidden
+* Overview::                    Overview of the GnuTLS integration.
+* Help For Users::
+* Help For Developers::
+* Function Index::
+* Variable Index::
address@hidden menu
address@hidden ifnottex
+
address@hidden Overview
address@hidden 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
address@hidden 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.
+
address@hidden Help For Users
address@hidden 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
address@hidden 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
address@hidden  This is a little bit trickier on the W32
+(Windows) platform, but if you have the GnuTLS DLLs (available from
address@hidden://sourceforge.net/projects/ezwinports/files/} thanks to Eli
+Zaretskii) in the same directory as Emacs, you should be OK.
+
address@hidden gnutls-available-p
+This function returns t if GnuTLS is available in this instance of Emacs.
address@hidden 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.
+
address@hidden 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.
address@hidden defvar
+
address@hidden gnutls-algorithm-priority
+The @code{gnutls-algorithm-priority} variable sets the GnuTLS priority
+string.  This is global, not per host name (although
address@hidden supports a priority string per connection so
+it could be done if needed).  The priority string syntax is in the
address@hidden://www.gnu.org/software/gnutls/documentation.html, GnuTLS
+documentation}.
address@hidden defvar
+
address@hidden 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:
address@hidden/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;
address@hidden/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.
address@hidden defvar
+
address@hidden 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}.
address@hidden defvar
+
address@hidden Help For Developers
address@hidden 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}.
+
address@hidden open-gnutls-stream name buffer host service
+This function creates a buffer connected to a specific @var{host} and
address@hidden (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.
+
address@hidden
+;; 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")
address@hidden lisp
+
address@hidden 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.
+
address@hidden 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.
address@hidden defun
+
address@hidden Function Index
address@hidden Function Index
address@hidden fn
+
address@hidden Variable Index
address@hidden Variable Index
address@hidden vr
+
address@hidden
+
address@hidden End:

=== modified file 'info/dir'
--- a/info/dir  2011-01-22 04:01:40 +0000
+++ b/info/dir  2012-04-09 13:10:22 +0000
@@ -40,6 +40,7 @@
 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