[Emacs-diffs] /srv/bzr/emacs/emacs-24 r107820: Backport addition of emacs-gnutls manual from trunk

[Glenn Morris]

------------------------------------------------------------
revno: 107820
author: Teodor Zlatanov <address@hidden>
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Thu 2012-04-12 19:59:47 -0400
message:
  Backport addition of emacs-gnutls manual from trunk
added:
  doc/misc/emacs-gnutls.texi
modified:
  ChangeLog
  doc/misc/ChangeLog
  doc/misc/Makefile.in
  doc/misc/makefile.w32-in
  info/dir

=== modified file 'ChangeLog'
--- a/ChangeLog 2012-03-04 18:07:33 +0000
+++ b/ChangeLog 2012-04-12 23:59:47 +0000
@@ -1,3 +1,7 @@
+2012-04-12  Teodor Zlatanov  <address@hidden>
+
+       * info/dir, Makefile.in (INFO_FILES): Add emacs-gnutls.
+
 2012-03-04  Paul Eggert  <address@hidden>
 
        configure: fix ncurses 'configure' issue on Solaris 10 (Bug#10677)

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2012-04-11 15:24:20 +0000
+++ b/doc/misc/ChangeLog        2012-04-12 23:59:47 +0000
@@ -1,3 +1,13 @@
+2012-04-12  Eli Zaretskii  <address@hidden>
+
+       * makefile.w32-in (INFO_TARGETS, DVI_TARGETS, clean): Add emacs-gnutls.
+       ($(infodir)/emacs-gnutls, emacs-gnutls.dvi): New targets.
+
+2012-04-12  Teodor Zlatanov  <address@hidden>
+
+       * emacs-gnutls.texi: Add documentation for the GnuTLS integration.
+       * Makefile.in: Add emacs-gnutls.texi to build.
+
 2012-04-11  Alan Mackenzie  <address@hidden>
 
        * cc-mode.texi (c-offsets-alist): Correct a typo.

=== modified file 'doc/misc/Makefile.in'
--- a/doc/misc/Makefile.in      2012-04-07 19:23:53 +0000
+++ b/doc/misc/Makefile.in      2012-04-12 23:59:47 +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 \
@@ -344,6 +347,15 @@
 eieio.pdf: ${srcdir}/eieio.texi
        $(ENVADD) $(TEXI2PDF) ${srcdir}/eieio.texi
 
+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-12 23:59:47 +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 'doc/misc/makefile.w32-in'
--- a/doc/misc/makefile.w32-in  2012-01-19 07:21:25 +0000
+++ b/doc/misc/makefile.w32-in  2012-04-12 23:59:47 +0000
@@ -51,7 +51,7 @@
                $(infodir)/remember $(infodir)/nxml-mode \
                $(infodir)/epa $(infodir)/mairix-el $(infodir)/sasl \
                $(infodir)/auth $(infodir)/eieio $(infodir)/ede \
-               $(infodir)/semantic $(infodir)/edt
+               $(infodir)/semantic $(infodir)/edt $(infodir)/emacs-gnutls
 DVI_TARGETS = calc.dvi cc-mode.dvi cl.dvi dbus.dvi dired-x.dvi \
                ediff.dvi forms.dvi gnus.dvi message.dvi emacs-mime.dvi \
                sieve.dvi pgg.dvi mh-e.dvi \
@@ -62,7 +62,7 @@
                newsticker.dvi rcirc.dvi erc.dvi ert.dvi \
                remember.dvi nxml-mode.dvi \
                epa.dvi mairix-el.dvi sasl.dvi auth.dvi eieio.dvi ede.dvi \
-               semantic.dvi edt.dvi
+               semantic.dvi edt.dvi emacs-gnutls.dvi
 INFOSOURCES = info.texi
 
 # The following rule does not work with all versions of `make'.
@@ -350,6 +350,11 @@
 edt.dvi: edt.texi doclicense.texi
        $(ENVADD) $(TEXI2DVI) $(srcdir)/edt.texi
 
+$(infodir)/emacs-gnutls: emacs-gnutls.texi doclicense.texi
+       $(MAKEINFO) $(MAKEINFO_OPTS) emacs-gnutls.texi
+emacs-gnutls.dvi: emacs-gnutls.texi doclicense.texi
+       $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-gnutls.texi
+
 mostlyclean:
        - $(DEL) *.log *.cp *.fn *.ky *.pg *.vr core *.tp *.core gnustmp.*
 
@@ -377,7 +382,7 @@
                 $(infodir)/epa* $(infodir)/sasl* \
                 $(infodir)/mairix-el* $(infodir)/auth* \
                 $(infodir)/eieio* $(infodir)/ede* \
-                $(infodir)/semantic* $(infodir)edt*
+                $(infodir)/semantic* $(infodir)edt* $(infodir)/emacs-gnutls*
 
 distclean: clean
        - $(DEL) makefile

=== modified file 'info/dir'
--- a/info/dir  2011-01-22 04:01:40 +0000
+++ b/info/dir  2012-04-12 23:59:47 +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