Backport addition of emacs-gnutls manual from trunk
This commit is contained in:
Teodor Zlatanov
Glenn Morris
parent
d11f2f381a
commit
5f9a4e98c0
6 changed files with 233 additions and 3 deletions
|
|
@ -1,3 +1,7 @@
|
|||
2012-04-12 Teodor Zlatanov <tzz@lifelogs.com>
|
||||
|
||||
* info/dir, Makefile.in (INFO_FILES): Add emacs-gnutls.
|
||||
|
||||
2012-03-04 Paul Eggert <eggert@cs.ucla.edu>
|
||||
|
||||
configure: fix ncurses 'configure' issue on Solaris 10 (Bug#10677)
|
||||
|
|
|
|||
|
|
@ -1,3 +1,13 @@
|
|||
2012-04-12 Eli Zaretskii <eliz@gnu.org>
|
||||
|
||||
* makefile.w32-in (INFO_TARGETS, DVI_TARGETS, clean): Add emacs-gnutls.
|
||||
($(infodir)/emacs-gnutls, emacs-gnutls.dvi): New targets.
|
||||
|
||||
2012-04-12 Teodor Zlatanov <tzz@lifelogs.com>
|
||||
|
||||
* emacs-gnutls.texi: Add documentation for the GnuTLS integration.
|
||||
* Makefile.in: Add emacs-gnutls.texi to build.
|
||||
|
||||
2012-04-11 Alan Mackenzie <acm@muc.de>
|
||||
|
||||
* cc-mode.texi (c-offsets-alist): Correct a typo.
|
||||
|
|
|
|||
|
|
@ -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 \
|
||||
|
|
@ -344,6 +347,15 @@ eieio.dvi: ${srcdir}/eieio.texi
|
|||
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)
|
||||
|
|
|
|||
198
doc/misc/emacs-gnutls.texi
Normal file
198
doc/misc/emacs-gnutls.texi
Normal file
|
|
@ -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:
|
||||
|
|
@ -51,7 +51,7 @@ INFO_TARGETS = $(infodir)/ccmode \
|
|||
$(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 @@ DVI_TARGETS = calc.dvi cc-mode.dvi cl.dvi dbus.dvi dired-x.dvi \
|
|||
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 @@ $(infodir)/edt: edt.texi doclicense.texi
|
|||
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 @@ clean: mostlyclean
|
|||
$(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
|
||||
|
|
|
|||
1
info/dir
1
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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue