Re: GnuTLS docs

[Eli Zaretskii]

> From: Ted Zlatanov <address@hidden>
> 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.