README patch

[Jeffrey Walton]

Hi Simon,

Thanks for the feedback. I'll get the issues fixed shortly for the project.

> Let's suggest git-format-patch instead, since that retains authorship,
> date, and includes a commit message too.
Even better. Would you be able to share the command(s)? I'm an SVN
guy. So I have not yet suffered the Git learning curve.

Sorry about the top post. It was easier to pluck out the one item of interest.

Jeff

On Mon, Nov 22, 2010 at 6:56 AM, Simon Josefsson <simon at josefsson.org> wrote:
> 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
>