Improve installation instructions.

1 files changed, 193 insertions, 6 deletions

diff --git a/doc/gnutls.texi b/doc/gnutls.texi
index 333513fee9..2b5ef1fc9b 100644
--- a/doc/gnutls.texi
+++ b/doc/gnutls.texi
@@ -73,7 +73,6 @@ Documentation License''.
 
 @menu
 * Preface::
-* Obtaining and Installing::
 * The Library::
 * Introduction to TLS::
 * Authentication methods::
@@ -123,13 +122,83 @@ Updated versions of the @acronym{GnuTLS} software and this document
 will be available from @url{http://www.gnutls.org/} and
 @url{http://www.gnu.org/software/gnutls/}.
 
-@node Obtaining and Installing
-@chapter Obtaining and Installing
+@menu
+* Getting help::
+* Commercial Support::
+* Downloading and Installing::
+* Bug Reports::
+* Contributing::
+@end menu
+
+@node Getting help
+@section Getting help
+
+A mailing list where users may help each other exists, and you can
+reach it by sending e-mail to @email{help-gnutls@@gnu.org}.  Archives
+of the mailing list discussions, and an interface to manage
+subscriptions, is available through the World Wide Web at
+@url{http://lists.gnu.org/mailman/listinfo/help-gnutls}.
+
+A mailing list for developers are also available, see
+@url{http://www.gnu.org/software/gnutls/lists.html}.
+
+Bug reports should be sent to @email{bug-gnutls@@gnu.org}, see
+@xref{Bug Reports}.
+
+@node Commercial Support
+@section Commercial Support
+
+Commercial support is available for users of GnuTLS.  The kind of
+support that can be purchased may include:
+
+@itemize
+
+@item Implement new features.
+Such as a new TLS extension.
+
+@item Port GnuTLS to new platforms.
+This could include porting to an embedded platforms that may need
+memory or size optimization.
+
+@item Integrating TLS as a security environment in your existing project.
+
+@item System design of components related to TLS.
+
+@end itemize
+
+If you are interested, please write to:
+
+@verbatim
+Simon Josefsson Datakonsult
+Hagagatan 24
+113 47 Stockholm
+Sweden
+
+E-mail: simon@josefsson.org
+@end verbatim
+
+If your company provide support related to GnuTLS and would like to be
+mentioned here, contact the author (@pxref{Bug Reports}).
+
+@node Downloading and Installing
+@section Downloading and Installing
+@cindex Installation
+@cindex Download
 
 GnuTLS is available for download from the following URL:
 
 @url{http://www.gnutls.org/download.html}
 
+The latest version is stored in a file, e.g.,
+@samp{gsasl-@value{VERSION}.tar.gz} where the @samp{@value{VERSION}}
+value is the highest version number in the directory.
+
+GnuTLS uses a Linux-like development cycle: even minor version numbers
+indicate a stable release and a odd minor version number indicates a
+development release.  For example, GnuTLS 1.6.3 denote a stable
+release since 6 is even, and GnuTLS 1.7.11 denote a development
+release since 7 is odd.
+
 GnuTLS depends on Libgcrypt, and you will need to install Libgcrypt
 before installing GnuTLS.  Libgcrypt is available from
 @url{ftp://ftp.gnupg.org/gcrypt/libgcrypt}.  Libgcrypt needs another
@@ -140,9 +209,12 @@ installing Libgcrypt.  Libgpg-error is available from
 Don't forget to verify the cryptographic signature after downloading
 source code packages.
 
-Compiling GnuTLS should be straight-forward: just unpack the package,
-invoke @code{./configure} and then @code{make check install}.  There
-are a number of compile-time parameters, as discussed below.
+The package is then extracted, configured and built like many other
+packages that use Autoconf.  For detailed information on configuring
+and building it, refer to the @file{INSTALL} file that is part of the
+distribution archive.  Typically you invoke @code{./configure} and
+then @code{make check install}.  There are a number of compile-time
+parameters, as discussed below.
 
 The compression libraries (libz and lzo) are optional dependencies.
 You can get libz from @url{http://www.zlib.net/}.  You can get lzo
@@ -171,6 +243,121 @@ functionality in GnuTLS.
 Regarding the Guile bindings, there are additional installation
 considerations, see @xref{Guile Preparations}.
 
+A few @code{configure} options may be relevant, summarized in the
+table.
+
+@table @code
+
+@item --disable-srp-authentication
+@itemx --disable-psk-authentication
+@itemx --disable-anon-authentication
+@itemx --disable-tls-authorization
+@itemx --disable-extra-pki
+@itemx --disable-openpgp-authentication
+@itemx --disable-openssl-compatibility
+Disable or enable particular features.  Generally not recommended.
+
+@end table
+
+For the complete list, refer to the output from @code{configure
+--help}.
+
+@node Bug Reports
+@section Bug Reports
+@cindex Reporting Bugs
+
+If you think you have found a bug in GnuTLS, please investigate it and
+report it.
+
+@itemize @bullet
+
+@item Please make sure that the bug is really in GnuTLS, and
+preferably also check that it hasn't already been fixed in the latest
+version.
+
+@item You have to send us a test case that makes it possible for us to
+reproduce the bug.
+
+@item You also have to explain what is wrong; if you get a crash, or
+if the results printed are not good and in that case, in what way.
+Make sure that the bug report includes all information you would need
+to fix this kind of bug for someone else.
+
+@end itemize
+
+Please make an effort to produce a self-contained report, with
+something definite that can be tested or debugged.  Vague queries or
+piecemeal messages are difficult to act on and don't help the
+development effort.
+
+If your bug report is good, we will do our best to help you to get a
+corrected version of the software; if the bug report is poor, we won't
+do anything about it (apart from asking you to send better bug
+reports).
+
+If you think something in this manual is unclear, or downright
+incorrect, or if the language needs to be improved, please also send a
+note.
+
+Send your bug report to:
+
+@center @samp{bug-gnutls@@gnu.org}
+
+@node Contributing
+@section Contributing
+@cindex Contributing
+@cindex Hacking
+
+If you want to submit a patch for inclusion -- from solve a typo you
+discovered, up to adding support for a new feature -- you should
+submit it as a bug report (@pxref{Bug Reports}).  There are some
+things that you can do to increase the chances for it to be included
+in the official package.
+
+Unless your patch is very small (say, under 10 lines) we require that
+you assign the copyright of your work to the Free Software Foundation.
+This is to protect the freedom of the project.  If you have not
+already signed papers, we will send you the necessary information when
+you submit your contribution.
+
+For contributions that doesn't consist of actual programming code, the
+only guidelines are common sense.  Use it.
+
+For code contributions, a number of style guides will help you:
+
+@itemize @bullet
+
+@item Coding Style.
+Follow the GNU Standards document (@pxref{top, GNU Coding Standards,,
+standards}).
+
+If you normally code using another coding standard, there is no
+problem, but you should use @samp{indent} to reformat the code
+(@pxref{top, GNU Indent,, indent}) before submitting your work.
+
+@item Use the unified diff format @samp{diff -u}.
+
+@item Return errors.
+No reason whatsoever should abort the execution of the library.  Even
+memory allocation errors, e.g. when malloc return NULL, should work
+although result in an error code.
+
+@item Design with thread safety in mind.
+Don't use global variables.  Don't even write to per-handle global
+variables unless the documented behaviour of the function you write is
+to write to the per-handle global variable.
+
+@item Avoid using the C math library.
+It causes problems for embedded implementations, and in most
+situations it is very easy to avoid using it.
+
+@item Document your functions.
+Use comments before each function headers, that, if properly
+formatted, are extracted into Texinfo manuals and GTK-DOC web pages.
+
+@item Supply a ChangeLog and NEWS entries, where appropriate.
+
+@end itemize
 @node The Library
 @chapter The Library