Attached is a proposed modification to the README file, including recent comments by Simon.

1 files changed, 139 insertions, 44 deletions

diff --git a/README b/README
index a41ffe3246..0b16d96540 100644
--- a/README
+++ b/README
@@ -1,45 +1,113 @@
 GnuTLS README -- Important introductory notes.
-Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005,
-              2006, 2007, 2008, 2009, 2010  Free Software Foundation, Inc.
-See the end for copying conditions.
+
+Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
+              2008, 2009, 2010  Free Software Foundation, Inc.
+
+See the end of this document for copying conditions.
 
 GnuTLS implements the TLS/SSL (Transport Layer Security aka Secure
-Sockets Layer) protocol.  GnuTLS is a GNU project.  More up to date
-information can be found at <http://www.gnu.org/software/gnutls/> and
-<http://www.gnutls.org/>.
-
-See the documentation in doc/ and examples in doc/examples/.
-
-COMPILATION ISSUES
-------------------
-
-The library needs libgcrypt. You can find libgcrypt at
-<ftp://ftp.gnupg.org/pub/gcrypt/libgcrypt/>.  Note that by
-compiling libgcrypt with CPU optimizations gnutls' speed will
-increase.
-
-In case you are compiling for embedded systems you should check the
-configure options (that is run: 'configure --help'), and disable
-unneeded features of gnutls.
-
-LICENSE ISSUES
---------------
-
-Since the 0.4.2 version the gnutls library is covered under the GNU
-Lesser GPL. Previously released versions were licensed under the GNU
-GPL.
-
-We changed the license for most of GnuTLS because other free libraries
-already exist that do the same jobs and have lax licenses.  We want
-GnuTLS to be usable in all the same places as those other libraries.
-We kept some parts of GnuTLS under the GPL because they are unique,
-and with the GPL they provide free software projects (which deserve
-our help) an advantage over non-free projects (which do not deserve
-our help, since they refuse to share with us).  For more explanation,
-see http://www.gnu.org/philosophy/why-not-lgpl.html.
-
-The GNU Lesser GPL license applies to the main gnutls library, while
-the gnutls-extra library is under the GPL. The gnutls-extra library
+Sockets Layer) protocol.  GnuTLS is a GNU project.  Additional
+information can be found at <http://www.gnu.org/software/gnutls/>
+and <http://www.gnutls.org/>.
+
+
+README
+------
+This README is targeted for users of the library who build from
+sources but do not necessarily develop.  If you are interested
+in developing and contributing to the GnuTLS project, please
+see README-alpha and visit 
+http://www.gnu.org/software/gnutls/manual/html_node/Contributing.html.
+
+
+COMPILATION
+-----------
+A typical command sequence for building the library is shown below.
+A complete list of options available for configure can be found
+by running './configure --help'.
+
+    cd gnutls-2.10.3
+    ./configure --prefix=/usr
+    make
+    sudo make install
+
+The commands above build and install the static archives (libgnutls.a
+and libgnutls-extra.a), the shared object (libgnutls.so  and
+libgnutls-extra.so), and additional binaries such as certtool and
+gnutls-cli.
+
+The library depends on libnettle OR libgcrypt (but never both).  GnuTLS
+currently uses libnettle as the default cryptographic library.  Versions
+2.10.3 and prior used libgcrypt as the default cryptographic library.
+Nettle can be found at http://www.gnu.org/software/nettle/, while
+libgcrypt can be found at <ftp://ftp.gnupg.org/pub/gcrypt/libgcrypt/>.
+
+To configure libnettle for installation and use by GnuTLS, a typical
+command sequence would be:
+
+    cd nettle-2.1
+    ./configure --prefix=/usr --disable-openssl --enable-shared
+    make
+    sudo make install
+
+For the Nettle project, --enable-shared will instruct automake and
+friends to build and install both the static archive (libnettle.a)
+and the shared object (libnettle.so).
+
+In case you are compiling for an embedded system, you can disable
+unneeded features of GnuTLS.  In general, it is usually best not to
+disable anything (for future mailing list questions and possible bugs).
+
+Depending on your installation, additional libraries, such as libtasn1
+and zlib, may be required.
+
+
+DOCUMENTATION
+-------------
+See the documentation in doc/ and online at
+http://www.gnu.org/software/gnutls/manual/html_node/index.htm.
+
+
+EXAMPLES
+--------
+See the examples in doc/examples/ and online at 'How To Use GnuTLS in
+Applications' at http://www.gnu.org/software/gnutls/manual/html_node/How-
+to-use-GnuTLS-in-applications.html#How-to-use-GnuTLS-in-applications.
+The examples include client, server, and multi-threaded examples.
+
+
+SECURITY ADVISORIES
+-------------------
+The project collects and publishes information on past security 
+incidents and vulnerabilities.  Open information exchange, including
+information which is [sometimes] suppressed in non-open or non-free
+projects, is one of the goals of the GnuTLS project.  Please visit
+http://www.gnu.org/software/gnutls/security.html.
+
+
+MAILING LISTS
+-------------
+The GnuTLS project maintains mailing lists for users, developers, and
+commits.  Please see http://www.gnu.org/software/gnutls/lists.html.
+
+
+LICENSING
+---------
+Since version 0.4.2, the GnuTLS library has been released under the GNU
+Lesser General Public License (LGPL).  Previous versions were licensed
+under the GNU General Public License (GPL).
+
+We changed the license for most of the GnuTLS components because other
+free libraries exist and offer similar functionality with lax licenses.
+We want GnuTLS to be usable in the same places as those other libraries.
+We kept some parts of GnuTLS under the GPL because they are unique, and
+the terms of the license under GPL provides free software projects (which
+deserve our help) an advantage over non-free projects (which do not
+deserve our help, since they refuse to share with us).  For information, see
+http://www.gnu.org/philosophy/why-not-lgpl.html.
+
+The GNU LPGL applies to the main gnutls library, while
+the gnutls-extra library is under the GPL.  The gnutls-extra library
 contains the code for "GnuTLS Inner Application" support and the
 OpenSSL compatibility layer.  The gnutls library is located in the
 lib/ directory, while the gnutls-extra library is at libextra/.
@@ -47,12 +115,39 @@ lib/ directory, while the gnutls-extra library is at libextra/.
 
 BUGS
 ----
+Currently GnuTLS needs testing.  Thorough testing is very important and
+expensive.  Often times, the developers do not have access to a particular
+piece of hardware or configuration to reproduce a scenario.  Notifying
+the developers about a possible bug will greatly help the project.  
+
+If you believe you have found a bug, please report it to bug-gnutls@gnu.org
+together with any applicable information.  A web interface for the system
+is available at http://savannah.gnu.org/support/?group=gnutls.
+
+Applicable information would include why the issue is a GnuTLS bug (if
+not readily apparent), output from 'uname -a', the version of the library or
+tool being used, a stack trace if available ('bt full' if under gdb), and
+perhaps a network trace.  Vague queries or piecemeal messages are difficult
+to act upon and don't help the development effort.
+
+Additional information can be found at the project's Bug Report page at
+http://www.gnu.org/software/gnutls/manual/html_node/Bug-Reports.html.
+
+
+PATCHES
+-------
+Patches are welcome and encouraged.  Details of contributing can be found
+at http://www.gnu.org/software/gnutls/manual/html_node/Contributing.html.
+
+Patches are submitted through the bug tracking system.  When submitting
+patches, please be sure to use sources from the git repository.  To
+create a patch for the project from a local git repository, please use
+the following commands.  'gnutls' should be the local directory of a
+previous git clone, and <filename> should reflect a descriptive name for
+the patch.
 
-Currently GnuTLS needs testing.  By notifying the developers about a
-possible bug you may help a lot, since testing is really important and
-expensive.  If you think you found a bug, report it to
-bug-gnutls@gnu.org together with the needed information, in order for
-developers to reproduce it.
+    cd gnutls
+    git diff > <filename>.patch
 
 ----------------------------------------------------------------------
 Copying and distribution of this file, with or without modification,