README patch

[Simon Josefsson]

Jeffrey Walton <noloader at gmail.com> writes:

> Hi Guys,
>
> Here's my first attempt at contributing to the project. Its probably
> pretty boring stuff for you guys, but it was a lot of lessons learned
> for me. Hopefully it will help others in a similar situation.
>
> I did not know the best way to submit the patch.  A Google search of
> 'GnuTLS patch' showed hits from other sites (and not gnu.org), so I'm
> guessing patches are emailed.  I can't imagine I'm allowed to
> check-in, so I did not even bother with looking up the git commands.

Thanks -- the best way to submit a patch is to send git-format-patch
output, against up-to-date master.  There is also the section in the
manual about this:

http://www.gnu.org/software/gnutls/manual/html_node/Contributing.html

It could also use some improvements, specifically mention git.  And
remove ChangeLog, we generate it from git log.

> The paperwork was mailed back to FSF on Saturday. If the paperwork is
> not yet on file, then I place the changes included in the patch in
> public domain.

Having it sent is good enough.

Your patch looks good generally, but some specific comments below.
Please send an updated patch and we'll install it.

> +See the end of this documentfor copying conditions.
                               ^

typo

> +COMPILATION
> +-----------
> +
> +A complete list of options available for configure can be found
> +by running './configure --help'.  Additional options can sometimes
> +be found by inspecting configure.ac.

Looking at configure.ac should never be needed, and may be confusing
since we have multiple configure.ac's.  Do you have some example when
./configure --help isn't enough and looking at configure.ac helps?  I
suggest to drop the last sentence above -- we don't want normal users go
looking in configure.ac.

>  In case you are compiling for
> +an embedded system, you should disable unneeded features of GnuTLS.

s/should/can/ -- the best is to not disable anything.

> +A typical command sequence for building the library is shown below.
> +
> +    cd gnutls-2.10.3
> +    ./configure --prefix=/usr
> +    make
> +    sudo make install
> +
> +The commands will build and install both the static archive
> +(libnettle.a), the shared object (libnettle.so), and additional
> +tools such as certtool and gnutls-cli.

That should be libgnutls.a, libgnutls-extra.a instead of libnettle.a,
and libgnutls.so, libgnutls-extra.so instead of libnettle.so.

> +The librar depends on libgcrypt and/or libnettle.  You can find
             ^                     ^^^^

Libgcrypt vs libnettle is OR, never AND.  Since libnettle is the
default, it should probably be mentioned before libgcrypt.

> +libgcrypt at <ftp://ftp.gnupg.org/pub/gcrypt/libgcrypt/>.  Note
> +that by compiling libgcrypt with CPU optimizations gnutls' speed
> +will increase.
> +
> +Nettle can be found at http://www.lysator.liu.se/~nisse/nettle/.

Maybe we should point to http://www.gnu.org/software/nettle/ as that is
more likely to be a stable URL.

> +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
> +
> +Note that --enable-shared will have automake and friends build and
> +install both the static archive (libnettle.a) and the shared object
> +(libnettle.so).

I'm not sure this makes sense in the _GnuTLS_ readme at all.  Maybe you
could submit this to libnettle?

Isn't --enable-shared the default?

> +Depending on your installation, additinal libraries may be required.
                                       ^ typo, add 'o'

> +See README-alpha and http://www.gnu.org/software/gnutls/devel.html
> +for additional information.

We shouldn't point to these resources here, I think, they are for
developers.  How about just saying that libtasn1 and zlib are
additional, optional, dependencies?

>  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.
> +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 fewer
> +restrcitions.

'fewer restrictions' is a bit biased, some may view other free libraries
licenses as problematic -- compare the advertisement clause in the
OpenSSL license.

I suggest to retain the old wording, and thus do 's/fewer
restrictions/lax license/'.

> +PATCHES
> +-------
> +Patches are welcome and encouraged.  When submitting patches, please be sure
> +to use sources from the Git repositiory.  To create a patch for the project,
> +please use the following command.
> +
> +    diff --unified FILE-original.c FILE-changed.c > FILE.patch

Let's suggest git-format-patch instead, since that retains authorship,
date, and includes a commit message too.

/Simon