better description and one example in README for Github and PyPI

README.rst

@@ -2,6 +2,49 @@
 RestrictedPython
 ================
 
-RestrictedPython is a defined subset of the Python language which allows to provide a program input into a trusted environment.
+RestrictedPython is a tool that helps to define a subset of the Python language which allows to provide a program input into a trusted environment.
+RestrictedPython is not a sandbox system or a secured environment, but it helps to define a trusted environment and execute untrusted code inside of it.
 
 For full documentation please see  http://restrictedpython.readthedocs.io/ or the local ``docs/index``.
+
+Example
+=======
+
+To give a basic understanding what RestrictedPython does here two examples:
+
+An unproblematic code example
+-----------------------------
+
+Python allows you to execute a large set of commands.
+This would not harm any system.
+
+    >>> from RestrictedPython import compile_restricted
+    >>> from RestrictedPython import safe_builtins
+    >>>
+    >>> source_code = """
+    ... def example():
+    ...     return 'Hello World!'
+    ... """
+    >>>
+    >>> locals = {}
+    >>> byte_code = compile_restricted(source_code, '<inline>', 'exec')
+    >>> exec(byte_code, safe_builtins, locals)
+    >>>
+    >>> locals['example']()
+    'Hello World!'
+
+Problematic code example
+------------------------
+
+This example directly executed in Python could harm your system.
+
+  >>> from RestrictedPython import compile_restricted
+  >>> from RestrictedPython import safe_builtins
+  >>>
+  >>> source_code = """
+  ... import os
+  ...
+  ... os.listdir('/')
+  ... """
+  >>> byte_code = compile_restricted(source_code, '<inline>', 'exec')
+  >>> # exec(byte_code, safe_builtins, {})

setup.py

@@ -27,8 +27,9 @@ def read(*rnames):
       version='4.0a2.dev0',
       url='http://pypi.python.org/pypi/RestrictedPython',
       license='ZPL 2.1',
-      description='RestrictedPython provides a restricted execution '
-                  'environment for Python, e.g. for running untrusted code.',
+      description='RestrictedPython is a defined subset of the Python language'
+                  ' which allows to provide a program input into a trusted'
+                  ' environment.',
       long_description=(read('README.rst') + '\n' +
                         read('docs', 'CHANGES.rst')),
       classifiers=[

src/RestrictedPython/README.rst

@@ -1,5 +1,7 @@
 .. contents::
 
+.. TODO:: move this documentation into docs
+
 Overview
 ========