Clean-up markup and some spellings.

docs/RestrictedPython4/index.rst

@@ -12,7 +12,7 @@ Zope and Plone should become Python 3 compatible.
 
 One of the core features of Zope 2 and therefore Plone is the possibility to implement and modify Python scripts and templates through the web (TTW) without harming the application or server itself.
 
-As Python is a `Turing Complete`_ programming language programmers don't have any limitation and could potentially harm the Application and Server itself.
+As Python is a `Turing complete`_ programming language programmers don't have any limitation and could potentially harm the Application and Server itself.
 
 RestrictedPython and AccessControl aims on this topic to provide a reduced subset of the Python Programming language, where all functions that could harm the system are permitted by default.
 
@@ -30,6 +30,7 @@ will be completed):
 * PyPy2.7
 
 .. _`security support` : https://docs.python.org/devguide/index.html#branchstatus
+.. _`Turing complete`: https://en.wikipedia.org/wiki/Turing_completeness
 
 We explicitly excluded Python 3.3 and PyPy3 (which is based on the Python 3.3 specification) as the changes in Python 3.4 are significant and the Python 3.3 is nearing the end of its supported lifetime.
 
@@ -46,18 +47,18 @@ The following packages / modules have hard dependencies on RestrictedPython:
 * Products.PluginIndexes -->
 * five.pt (wrapping some functions and protection for Chameleon) -->
 
-Additionally the folowing add ons have dependencies on RestrictedPython
+Additionally the following add ons have dependencies on RestrictedPython
 
 * None
 
-How RestrictedPython 4+ works internal
---------------------------------------
+How RestrictedPython 4+ works internally
+----------------------------------------
 
-RestrictedPython core functions is split over several files:
+RestrictedPython's core functions are split over several files:
 
-* __init__.py --> exports API direct under Namespace, any other should never be imported directly.
-* compile.py --> holds the compile_restricted methods for internal _compile_restricted_mode is the important function
-* transformer --> Home of ``RestrictingNodeTransformer``
+* __init__.py --> It exports the API directly in the ``RestrictedPython`` namespace. It should be not necessary to import from any other module inside the package.
+* compile.py --> It contains the ``compile_restricted`` functions where internally ``_compile_restricted_mode`` is the important one
+* transformer.py --> Home of the ``RestrictingNodeTransformer``
 
 ``RestrictingNodeTransformer``
 ..............................

docs/api/index.rst

@@ -1,5 +1,5 @@
-API von RestrictedPython 4.0
-============================
+API of RestrictedPython 4.0
+===========================
 
 .. code:: Python
 

docs/conf.py

@@ -150,7 +150,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

docs/idea.rst

@@ -1,7 +1,7 @@
 The Idea behind RestrictedPython
 ================================
 
-Python is a `Turing-complete`_ programming language.
+Python is a `Turing complete`_ programming language.
 To offer a Python interface for users in web context is a potential security risk.
 Web frameworks and Content Management Systems (CMS) want to offer their users as much extensibility as possible through the web (TTW).
 This also means to have permissions to add functionality via a Python Script.
@@ -81,6 +81,6 @@ Also RestrictedPython provides three predefined, limited versions of Python's ow
 
 Additional there exist guard functions to make attributes of Python objects immutable --> ``full_write_guard`` (write and delete protected)
 
-.. _Turing-complete: https://en.wikipedia.org/wiki/Turing_completeness
+.. _`Turing complete`: https://en.wikipedia.org/wiki/Turing_completeness
 .. _Ada Ravenscar Profile: https://en.wikipedia.org/wiki/Ravenscar_profile
 .. _EBNF: https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form

docs/notes.rst

@@ -1,7 +1,7 @@
 How it works
 ============
 
-This is old documentation from RestrictedPython 3 and before.
+*Caution:* This is old documentation from RestrictedPython 3 and before.
 Information should be transferred and this file should be removed.
 
 Every time I see this code, I have to relearn it.  These notes will

docs/upgrade/index.rst

@@ -6,7 +6,7 @@ RestrictedPython is a classic approach of compiler construction to create a limi
 Defining a programming language requires a regular grammar (`Chomsky 3`_ / `EBNF`_) definition.
 This grammar will be implemented in an abstract syntax tree (AST), which will be passed on to a code generator to produce a machine-readable version.
 
-.. _`_sec_code_generation`
+.. _`_sec_code_generation`:
 
 Code generation
 ---------------

docs/upgrade_dependencies/index.rst

@@ -1,10 +1,7 @@
 Upgrade dependencies
 ====================
 
-Zope Core Packages that has RestrictedPython as dependencies
-------------------------------------------------------------
-
-The following Packages used in Zope2 for Plone depend on RestricedPython:
+The following packages used in Zope2 and Plone depend on ``RestricedPython``:
 
 * AccessControl
 * zope.untrustedpython
@@ -23,22 +20,23 @@ RestrictedPython did move some of the imports to the base namespace, so you shou
 
 * compile_restricted methods:
 
-  * ``from RestrictedPython.compile import compile_restricted``
-  * ``from RestrictedPython.compile import compile_restricted_eval``
-  * ``from RestrictedPython.compile import compile_restricted_exec``
-  * ``from RestrictedPython.compile import compile_restricted_function``
-  * ``from RestrictedPython.compile import compile_restricted_single``
+  * ``from RestrictedPython import compile_restricted``
+  * ``from RestrictedPython import compile_restricted_eval``
+  * ``from RestrictedPython import compile_restricted_exec``
+  * ``from RestrictedPython import compile_restricted_function``
+  * ``from RestrictedPython import compile_restricted_single``
 
-* predefined builtins:
+* predefined built-ins:
 
-  * ``from RestrictedPython.Guards import safe_builtins``
-  * ``from RestrictedPython.Limits import limited_builtins``
-  * ``from RestrictedPython.Utilities import utility_builtins``
+  * ``from RestrictedPython import safe_builtins``
+  * ``from RestrictedPython import limited_builtins``
+  * ``from RestrictedPython import utility_builtins``
 
-* Helper methods
+* helper methods:
 
-  * ``from RestrictedPython.PrintCollector import PrintCollector``
+  * ``from RestrictedPython import PrintCollector``
 
-Any import from ``RestrictedPython.rcompile`` indicates that there have been advanced checks implemented.
-Those advanced checks where implemented via ``MutatingWalker``'s.
-Any check needs to be reimplemented as a subclass of RestrictingNodeTransformer.
+Any import from ``RestrictedPython.RCompile`` indicates that there have been advanced checks implemented.
+Those advanced checks where implemented via a ``MutatingWalker``.
+Any checks needs to be reimplemented as a subclass of
+``RestrictingNodeTransformer``.

docs/usage/index.rst

@@ -4,23 +4,23 @@ Usage of RestrictedPython
 API overview
 ------------
 
-RestrictedPython do have tree major scopes:
+RestrictedPython has tree major scopes:
 
-* ``compile_restricted`` methods
+1. ``compile_restricted`` methods:
 
   * ``compile_restricted``
   * ``compile_restricted_exec``
   * ``compile_restricted_eval``
   * ``compile_restricted_single``
   * ``compile_restricted_function``
 
-* restricted builtins
+2. restricted builtins
 
   * ``safe_builtins``
   * ``limited_builtins``
   * ``utility_builtins``
 
-* Helper Moduls
+3. helper modules
 
   * ``PrintCollector``
 
@@ -62,25 +62,26 @@ With that simple addition:
     from RestrictedPython import compile_restricted as compile
 
 it uses a predefined policy that checks and modify the source code and checks against a restricted subset of the Python language.
-Execution of the compiled source code is still against the full available set of library modules and methods.
+The compiled source code is still executed against the full available set of library modules and methods.
 
-The ``exec()`` :ref:`Python ``exec()`` method <python3:meth:exec>` did take three params:
+The Python :py:func:`exec` takes three parameters:
 
 * ``code`` which is the compiled byte code
 * ``globals`` which is global dictionary
 * ``locals`` which is the local dictionary
 
-By limiting the entries in globals and locals dictionary you restrict access to available library modules and methods.
+By limiting the entries in the ``globals`` and ``locals`` dictionaries you
+restrict the access to the available library modules and methods.
 
-So providing defined dictionaries for the ``exec()`` method should be used in context of RestrictedPython.
+Providing defined dictionaries for ``exec()`` should be used in context of RestrictedPython.
 
 .. code:: Python
 
     byte_code = <code>
     exec(byte_code, { ... }, { ... })
 
 Typically there is a defined set of allowed modules, methods and constants used in that context.
-RestrictedPython did provide three predefined builtins for that:
+RestrictedPython provides three predefined built-ins for that:
 
 * ``safe_builtins``
 * ``limited_builtins``
@@ -105,13 +106,13 @@ So you normally end up using:
 
 One common advanced usage would be to define an own restricted builtin dictionary.
 
-.. _sec_usage_frameworks
+.. _sec_usage_frameworks:
 
-Usage on frameworks and Zope
+Usage in frameworks and Zope
 ----------------------------
 
-One major issue with using ``compile_restricted`` directly in a framework is, that you have to use try except statements to handle problems and it might be a bit harder to provide useful information to the user.
-RestrictedPython did provide four specialized compile_restricted methods:
+One major issue with using ``compile_restricted`` directly in a framework is, that you have to use try-except statements to handle problems and it might be a bit harder to provide useful information to the user.
+RestrictedPython provides four specialized compile_restricted methods:
 
 * ``compile_restricted_exec``
 * ``compile_restricted_eval``
@@ -125,7 +126,7 @@ Those four methods return a tuple with four elements:
 * ``warnings`` a list with warnings
 * ``used_names`` a set / dictionary with collected used names of library calls
 
-Those three information "lists" could be used to provide the user with informations about its source code.
+Those three information "lists" could be used to provide the user with informations about the compiled source code.
 
 Typical uses cases for the four specialized methods:
 
@@ -134,7 +135,7 @@ Typical uses cases for the four specialized methods:
 * ``compile_restricted_single``
 * ``compile_restricted_function``
 
-Modifying the builtins is straight forward, it is just a dictionary containing access pointer to available library elements.
+Modifying the builtins is straight forward, it is just a dictionary containing access pointers to available library elements.
 Modification is normally removing elements from existing builtins or adding allowed elements by copying from globals.
 
 For frameworks it could possibly also be useful to change handling of specific Python language elements.
@@ -145,9 +146,9 @@ A policy is basically a special ``NodeTransformer`` that could be instantiated w
 
     OwnRestrictingNodeTransformer(errors=[], warnings=[], used_names=[])
 
-One Special case (defined for non blocking other ports to Python 3 of the Zope Packages) is to actually use RestrictedPython in an unrestricted Mode, by providing a Null-Policy (None).
+One special case (defined to unblock ports of Zope Packages to Python 3) is to actually use RestrictedPython in an unrestricted mode, by providing a Null-Policy (aka ``None``).
 
-All ``compile_restricted*`` methods do have a optional param policy, where a specific policy could be provided.
+All ``compile_restricted*`` methods do have a optional parameter ``policy``, where a specific policy could be provided.
 
 .. code:: Python