[pypy-commit] pypy.org extradoc: Grammar and American English cleanups.

[edelsohn]

Author: edelsohn
Branch: extradoc
Changeset: r319:35a2f6a3f68d
Date: 2012-02-11 20:02 -0500
http://bitbucket.org/pypy/pypy.org/changeset/35a2f6a3f68d/

Log:	Grammar and American English cleanups.

diff --git a/source/performance.txt b/source/performance.txt
--- a/source/performance.txt
+++ b/source/performance.txt
@@ -1,25 +1,25 @@
 One of the goals of the PyPy project is to provide a fast and compliant
-python interpreter. Part of the way we achieve this is to provide a
+python interpreter. Some of the ways we achieve this are by providing a
 high-performance garbage collector (GC) and a high-performance
 Just-in-Time compiler (JIT).  Results of comparing PyPy and CPython can
 be found on the `speed website`_. Those benchmarks are not a random
-collection: they are a combination of real-world Python programs,
+collection: they are a combination of real-world Python programs --- 
 benchmarks originally included with the (now dead) Unladen Swallow
-project, and benchmarks we found PyPy to be slow on (and improved).
+project --- and benchmarks for which we found PyPy to be slow (and improved).
 Consult the descriptions of each for details.
 
-The JIT is however not a magic bullet. There are several characteristics
-that might be surprising for people that are not used to JITs in
-general, or to the PyPy JIT in particular.  The JIT is generally good at
-speeding up straightforward Python code that spends a lot of time in the
-bytecode dispatch loop, i.e. running actual Python code --- as opposed
-to running things that are only invoked by your Python code.  Good
+The JIT, however, is not a magic bullet. There are several characteristics
+that might surprise people who are not used to JITs in
+general or to the PyPy JIT in particular.  The JIT is generally good at
+speeding up straight-forward Python code that spends a lot of time in the
+bytecode dispatch loop, i.e., running actual Python code --- as opposed
+to running things that only are invoked by Python code.  Good
 examples include numeric calculations or any kind of heavily
 object-oriented program.  Bad examples include doing computations with
-large longs --- which is done by unoptimizable support code.  When the
-JIT does not help, PyPy is generally slower than CPython.
+large longs --- which is performed by unoptimizable support code.  When the
+JIT cannot help, PyPy is generally slower than CPython.
 
-In more details, the JIT is known not to work on:
+More specifically, the JIT is known not to work on:
 
 * **Tests**: The ideal unit tests execute each piece of tested code
   once.  This leaves no time for the JIT to warm up.
@@ -34,35 +34,36 @@
 * **Long-running runtime functions**: These are the functions provided
   by the runtime of PyPy that do a significant amount of work.
   PyPy's runtime is generally not as optimized as CPython's and we expect those
-  functions to take somewhere between same time as CPython to 2x longer.
-  This includes for example computing with longs, or sorting large lists.
+  functions to take somewhere between the same time as CPython to twice as long.
+  This includes, for example, computing with longs, or sorting large lists.
   A counterexample is regular expressions: although they take time, they
   come with their own JIT.
 
 Unrelated things that we know PyPy to be slow at (note that we're probably
 working on it):
 
-* **Building very large dicts**: This is so far an issue with our GCs.
+* **Building very large dicts**: At present, this is an issue with our GCs.
   Building large lists works much better; the random order of
   dictionary elements is what hurts performance right now.
 
 * **CPython C extension modules**: Any C extension module recompiled
-  with PyPy takes a very large hit in performance.  The purpose of being
-  able to compile C extension modules with PyPy is for them to work at
-  all.  If the extension module is for speedup purposes only, then it
-  makes no sense to have it on top of PyPy right now.  Just remove it
-  and use a straightforward Python version.  If the extension module is
+  with PyPy takes a very large hit in performance.  PyPy supports C
+  extension modules solely to provide basic functionality.
+  If the extension module is for speedup purposes only, then it
+  makes no sense to use it with PyPy at the moment.  Instead, remove it
+  and use a native Python implementation, which also allows opportunities
+  for JIT optimization.  If the extension module is
   both performance-critical and an interface to some C library, then it
-  might be worthwhile to consider rewriting it as a pure Python version,
-  using something like ``ctypes``.
+  might be worthwhile to consider rewriting it as a pure Python version
+  that uses something like ``ctypes`` for the interface.
 
 * **Missing RPython modules**: A few modules of the standard library
   (like ``csv`` and ``cPickle``) are in C in CPython, but in pure Python
   in PyPy.  Sometimes the JIT is able to do a relatively good job, and
-  sometimes not.  In any case it is still slower in PyPy than in CPython.
+  sometimes not.  In any case, it is still slower in PyPy than in CPython.
 
-We generally consider things that are slower on PyPy than CPython bugs
-of PyPy.  In case you find some issue that is not documented here,
+We generally consider things that are slower on PyPy than CPython to be bugs
+of PyPy.  If you find some issue that is not documented here,
 please report it to our `bug tracker`_ for investigation.
 
 .. _`bug tracker`: http://bugs.pypy.org