From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: GnuTLS docs Date: Mon, 09 Apr 2012 10:39:42 +0300 Message-ID: <83k41p8ibl.fsf@gnu.org> References: <87d37q7ld4.fsf@gnu.org> <871uo6puac.fsf@gnu.org> <87y5qa72vm.fsf_-_@lifelogs.com> <834nsycjs0.fsf@gnu.org> <87y5qa5chf.fsf@lifelogs.com> <83pqblc2ih.fsf@gnu.org> <87pqbl6c9l.fsf@lifelogs.com> <83d37lb3nu.fsf@gnu.org> <87d37hofbs.fsf@lifelogs.com> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: dough.gmane.org 1333957310 16649 80.91.229.3 (9 Apr 2012 07:41:50 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Mon, 9 Apr 2012 07:41:50 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Apr 09 09:41:48 2012 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1SH9ER-00050g-PB for ged-emacs-devel@m.gmane.org; Mon, 09 Apr 2012 09:41:48 +0200 Original-Received: from localhost ([::1]:54787 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SH9EQ-0002tf-Ts for ged-emacs-devel@m.gmane.org; Mon, 09 Apr 2012 03:41:46 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:40802) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SH9EM-0002tQ-PE for emacs-devel@gnu.org; Mon, 09 Apr 2012 03:41:44 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1SH9EK-0002GK-Pw for emacs-devel@gnu.org; Mon, 09 Apr 2012 03:41:42 -0400 Original-Received: from mtaout21.012.net.il ([80.179.55.169]:52958) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1SH9EK-0002GG-Cv for emacs-devel@gnu.org; Mon, 09 Apr 2012 03:41:40 -0400 Original-Received: from conversion-daemon.a-mtaout21.012.net.il by a-mtaout21.012.net.il (HyperSendmail v2007.08) id <0M2700100BYX5W00@a-mtaout21.012.net.il> for emacs-devel@gnu.org; Mon, 09 Apr 2012 10:41:38 +0300 (IDT) Original-Received: from HOME-C4E4A596F7 ([84.229.57.204]) by a-mtaout21.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0M27001MUC1D5S00@a-mtaout21.012.net.il> for emacs-devel@gnu.org; Mon, 09 Apr 2012 10:41:38 +0300 (IDT) In-reply-to: <87d37hofbs.fsf@lifelogs.com> X-012-Sender: halo1@inter.net.il X-detected-operating-system: by eggs.gnu.org: Solaris 10 (beta) X-Received-From: 80.179.55.169 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:149494 Archived-At: > From: Ted Zlatanov > Date: Sun, 08 Apr 2012 21:37:43 -0400 > > Thanks, Eli. Could you take a look at the attached first draft? Looks good, thanks. A few comments below. > GnuTLS is a library to establish encrypted SSL or TLS connections. Acronyms such as SSL and TLS will look better in print if you enclose them in @acronym{}, as in "@acronym{SSL}". Also, readers do not necessarily know what these mean, so something like this would be better: The GnuTLS library is an integral part of Emacs. Through it, any Emacs Lisp program can establish encrypted network connections that use @dfn{Socket Secure 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. Note that I reworded the text to use active rather than passive tense, which makes the text more clear and concise. Also note the use of @dfn whenever new terminology is introduced. > Emacs supports it through the @code{gnutls.c} and @code{gnutls.h} C > files and the @file{gnutls.el} Emacs Lisp library. File names should all have the @file markup, like you did with gnutls.el. > @node Overview > @chapter Overview > > The GnuTLS library is an integral part of Emacs. Through it, > encrypted SSL and TLS network connections can be established by any > Emacs Lisp program. The process is as automated and transparent as > possible. That's an exact repetition of what you said in the Top node. In the printed manual, both will appear. So I would suggest to make the first one shorter, or maybe eliminate it entirely. > @chapter Help for users Chapter, section, and subsection headers should capitalize every word. > 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} (the two are > equivalent, the first one being an alias to the second). There should be a cross-reference to where these two functions are described. Like this: 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. > @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 It is best not to leave an empty line between @def* and the explanatory text (here and elsewhere). > it could be done if needed). The priority string syntax is in the > GnuTLS documentation at > @url{http://www.gnu.org/software/gnutls/documentation.html}. The last sentence will look better in HTML if you modify it like this: The priority string syntax is in the @uref{http://www.gnu.org/software/gnutls/documentation.html, GnuTLS documentation}. > @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 Please remove the ".." quotes inside @file, they are not needed. > @defun open-gnutls-stream name buffer host service > > This function creates a buffer connected to a specific @code{host} and > @code{service} (port number or service name). The connection process > is called @code{name} (made unique if necessary). It returns the > connection process. When you describe arguments mentioned in function declarations, use the @var{} markup, not @code{}. That's because these arguments stand for something else: the actual variables that will be used in the call to the function. By contrast, @code is for the actual variables and other literal symbols. > @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 Judging by these examples, all the arguments are strings, which you didn't say in the description. If any of them can be anything else (e.g., if BUFFER can be a buffer object), you should say that as well. > @node Index > @chapter Index > @printindex cp This index comes up empty, right? If you really want a concept index, you should have at least a few @cindex entries in the manual, where issues of interest are described. Or you could omit this index. Thanks again for working on this.