Clarify C compatibility policy

and a couple of other minor doc fixups.

3 files changed, 36 insertions, 21 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 807cd5320..0ae75c7ce 100644
--- a/CONTRIBUTING.md
+++ b/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.
-For code under `examples`, this is governed by the [CC0 Public Domain Dedication](examples/COPYING).
-All other code is released under the [GPL v2 with linking exception](COPYING).
+By contributing to libgit2, you agree to release your contribution under
+the terms of the license.  Except for the `examples` directory, all code
+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
-a forum / Stack Overflow then please flag this in your PR and also make sure you've
-given proper credit to the original author in the code snippet.
+If you are pulling in code from core Git, another project or code you've
+pulled from a forum / Stack Overflow then please flag this in your PR and
+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)
-(a.k.a. C89) with some specific conventions for function and type naming,
-code formatting, and testing.
+The public API of `libgit2` is [ANSI C](http://en.wikipedia.org/wiki/ANSI_C)
+(a.k.a. C89) compatible.  Internally, `libgit2` is written using a portable
+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
diff --git a/CONVENTIONS.md b/CONVENTIONS.md
index 59b41a2e6..5b8238a78 100644
--- a/CONVENTIONS.md
+++ b/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 greatest extent possible, 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.
+The public API of `libgit2` is [ANSI C](http://en.wikipedia.org/wiki/ANSI_C)
+(a.k.a. C89) compatible.
+
+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.
diff --git a/README.md b/README.md
index f814b8732..aa75bb093 100644
--- a/README.md
+++ b/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) 
-    on GitHub for bug reports.  The mailing list archives are still available at 
+    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
     <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