[pypy-commit] cffi default: Try to rewrite and expand a bit the introduction.

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: 
Changeset: r343:df89dccc974a
Date: 2012-06-14 17:13 +0200
http://bitbucket.org/cffi/cffi/changeset/df89dccc974a/

Log:	Try to rewrite and expand a bit the introduction.

diff --git a/README.md b/README.md
--- a/README.md
+++ b/README.md
@@ -2,17 +2,34 @@
 ====
 
 Foreign Function Interface for Python calling C code. The aim of this project
-is to provide a convinient and reliable way of calling C code from Python.
-The interface is based on [luajit FFI](http://luajit.org/ext_ffi.html) and follows a few principles:
+is to provide a convenient and reliable way of calling C code from Python.
+The interface is based on [luajit FFI](http://luajit.org/ext_ffi.html) and
+follows a few principles:
 
-* You want to use C code from Python code, so you should be able to do so
-  without needing to learn a 3rd language
-  (unlike [Cython](http://www.cython.org) or [SWIG](http://www.swig.org/) or ctypes)
+* The goal is to call C code from Python.  You should be able to do so
+  without learning a 3rd language: every alternative requires you to learn
+  their own language ([Cython](http://www.cython.org),
+  [SWIG](http://www.swig.org/)) or API
+  ([ctypes](http://docs.python.org/library/ctypes.html)).  So we tried to
+  assume that you know Python and C and minimize the extra bits of API that
+  you need to learn.
 
-* Keep all the python-related logic in Python instead of C (unlike
-  [CPython native C extensions](http://docs.python.org/extending/extending.html))
+* Keep all the Python-related logic in Python so that you don't need to
+  write much C code (unlike
+  [CPython native C extensions](http://docs.python.org/extending/extending.html)).
 
-* Be complete and work on the level of API (unlike [ctypes](http://docs.python.org/library/ctypes.html))
+* Work either at the level of the ABI (Application Binary Interface)
+  or the API (Application Programming Interface).  Usually, C
+  libraries have a specified C API but often not an ABI (e.g. they may
+  document a "struct" as having at least these fields, but maybe more).
+  ([ctypes](http://docs.python.org/library/ctypes.html) works at the ABI
+  level, whereas
+  [native C extensions](http://docs.python.org/extending/extending.html)
+  work at the API level.)
+
+* We try to be complete.  For now some C99 constructs are not supported,
+  but all C89 should be, including macros (apart from the most advanced
+  (ab)uses of these macros).
 
 Simple example
 --------------