Clarify C compatibility policy

and a couple of other minor doc fixups.

CONTRIBUTING.md

@@ -5,9 +5,13 @@ your help.
 
 ## Licensing
 
-By contributing to libgit2, you agree to release your contribution under the terms of the license.
+By contributing to libgit2, you agree to release your contribution under
-For code under `examples`, this is governed by the [CC0 Public Domain Dedication](examples/COPYING).
+the terms of the license.  Except for the `examples` directory, all code
-All other code is released under the [GPL v2 with linking exception](COPYING).
+is released under the [GPL v2 with linking exception](COPYING).
+
+The `examples` code is governed by the
+[CC0 Public Domain Dedication](examples/COPYING), so that you may copy
+from them into your own application.
 
 ## Discussion & Chat
 
@@ -76,15 +80,19 @@ you're porting code *from* to see what you need to do.  As a general rule,
 MIT and BSD (3-clause) licenses are typically no problem.  Apache 2.0
 license typically doesn't work due to GPL incompatibility.
 
-If you are pulling in code from core Git, another project or code you've pulled from
+If you are pulling in code from core Git, another project or code you've
-a forum / Stack Overflow then please flag this in your PR and also make sure you've
+pulled from a forum / Stack Overflow then please flag this in your PR and
-given proper credit to the original author in the code snippet.
+also make sure you've given proper credit to the original author in the
+code snippet.
 
 ## Style Guide
 
-`libgit2` is written in [ANSI C](http://en.wikipedia.org/wiki/ANSI_C)
+The public API of `libgit2` is [ANSI C](http://en.wikipedia.org/wiki/ANSI_C)
-(a.k.a. C89) with some specific conventions for function and type naming,
+(a.k.a. C89) compatible.  Internally, `libgit2` is written using a portable
-code formatting, and testing.
+subset of C99 - in order to compiler with GCC, Clang, MSVC, etc., we keep
+local variable declarations at the tops of blocks only and avoid `//` style
+comments.  Additionally, `libgit2` follows some extra conventions for
+function and type naming, code formatting, and testing.
 
 We like to keep the source code consistent and easy to read.  Maintaining
 this takes some discipline, but it's been more than worth it.  Take a look

CONVENTIONS.md

@@ -6,14 +6,18 @@ guidelines that should help with that.
 ## Compatibility
 
 `libgit2` runs on many different platforms with many different compilers.
-It is written in [ANSI C](http://en.wikipedia.org/wiki/ANSI_C) (a.k.a. C89)
-with some specific standards for function and type naming, code formatting,
-and testing.
 
-We try to avoid more recent extensions to maximize portability.  We also, to
+The public API of `libgit2` is [ANSI C](http://en.wikipedia.org/wiki/ANSI_C)
-the greatest extent possible, try to avoid lots of `#ifdef`s inside the core
+(a.k.a. C89) compatible.
-code base.  This is somewhat unavoidable, but since it can really hamper
+
-maintainability, we keep it to a minimum.
+Internally, `libgit2` is written using a portable subset of C99 - in order
+to maximize compatibility (e.g. with MSVC) we avoid certain C99
+extensions.  Specifically, we keep local variable declarations at the tops
+of blocks only and we avoid `//` style comments.
+
+Also, to the greatest extent possible, we try to avoid lots of `#ifdef`s
+inside the core code base.  This is somewhat unavoidable, but since it can
+really hamper maintainability, we keep it to a minimum.
 
 ## Match Surrounding Code
 
@@ -209,6 +213,9 @@ All inlined functions must be declared as:
 GIT_INLINE(result_type) git_modulename_functionname(arg_list);
 ```
 
+`GIT_INLINE` (or `inline`) should not be used in public headers in order
+to preserve ANSI C compatibility.
+
 ## Tests
 
 `libgit2` uses the [clar](https://github.com/vmg/clar) testing framework.

README.md

@@ -20,17 +20,17 @@ Additionally, the example code has been released to the public domain (see the
 * API documentation: <http://libgit2.github.com/libgit2>
 * IRC: [#libgit2](irc://irc.freenode.net/libgit2) on irc.freenode.net.
 * Mailing list: The libgit2 mailing list was
-    traditionally hosted in Librelist but has been deprecated. We encourage you to 
+    traditionally hosted in Librelist but has been deprecated. We encourage you to
     [use StackOverflow](http://stackoverflow.com/questions/tagged/libgit2) instead for any questions regarding
-    the library, or [open an issue](https://github.com/libgit2/libgit2/issues) 
+    the library, or [open an issue](https://github.com/libgit2/libgit2/issues)
-    on GitHub for bug reports.  The mailing list archives are still available at 
+    on GitHub for bug reports.  The mailing list archives are still available at
     <http://librelist.com/browser/libgit2/>.
 
 
 What It Can Do
 ==============
 
-`libgit2` is already very usable and is being used in production for many applications including the GitHub.com site, in Plastic SCM 
+`libgit2` is already very usable and is being used in production for many applications including the GitHub.com site, in Plastic SCM
 and also powering Microsoft's Visual Studio tools for Git.  The library provides:
 
 * SHA conversions, formatting and shortening
@@ -65,7 +65,7 @@ Under Unix-like systems, like Linux, \*BSD and Mac OS X, libgit2 expects `pthrea
 they should be installed by default on all systems. Under Windows, libgit2 uses the native Windows API
 for threading.
 
-The `libgit2` library is built using `CMake 2.6+` (<http://www.cmake.org>) on all platforms.
+The `libgit2` library is built using [CMake](<http://www.cmake.org>) (version 2.6 or newer) on all platforms.
 
 On most systems you can build the library using the following commands