fixed some typos and clarifying

docs/api.rst

@@ -12,7 +12,7 @@ Basics
 ------
 
 Jinja2 uses a central object called the template :class:`Environment`.
-Instances of this class are used to store the configuration, global objects
+Instances of this class are used to store the configuration and global objects,
 and are used to load templates from the file system or other locations.
 Even if you are creating templates from strings by using the constructor of
 :class:`Template` class, an environment is created automatically for you,

docs/index.rst

@@ -1,7 +1,7 @@
 Welcome to Jinja2
 =================
 
-Jinja2 is a modern and designer friendly templating language for Python,
+Jinja2 is a modern and designer-friendly templating language for Python,
 modelled after Django's templates.  It is fast, widely used and secure
 with the optional sandboxed template execution environment:
 
@@ -20,7 +20,7 @@ with the optional sandboxed template execution environment:
 -   powerful automatic HTML escaping system for XSS prevention
 -   template inheritance
 -   compiles down to the optimal python code just in time
--   optional ahead of time template compilation
+-   optional ahead-of-time template compilation
 -   easy to debug.  Line numbers of exceptions directly point to
     the correct line in the template.
 -   configurable syntax

docs/intro.rst

@@ -17,7 +17,7 @@ Jinja2 works with Python 2.6.x, 2.7.x and >= 3.3.  If you are using Python
 was dropped in Jinja2 version 2.7.
 
 If you wish to use the :class:`~jinja2.PackageLoader` class, you will also
-need setuptools or distribute installed at runtime.
+need `setuptools`_ or `distribute`_ installed at runtime.
 
 Installation
 ------------
@@ -25,8 +25,8 @@ Installation
 You have multiple ways to install Jinja2.  If you are unsure what to do, go
 with the Python egg or tarball.
 
-As a Python egg (via easy_install)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+As a Python egg (via `easy_install`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can install the most recent Jinja2 version using `easy_install`_ or `pip`_::
 
@@ -46,13 +46,11 @@ From the tarball release
 2.  Unpack the tarball
 3.  ``sudo python setup.py install``
 
-Note that you either have to have setuptools or `distribute`_ installed;
+Note that you either have to have `setuptools` or `distribute` installed;
 the latter is preferred.
 
 This will install Jinja2 into your Python installation's site-packages directory.
 
-.. _distribute: http://pypi.python.org/pypi/distribute
-
 Installing the development version
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -62,10 +60,11 @@ Installing the development version
 4.  ``ln -s jinja2 /usr/lib/python2.X/site-packages``
 
 As an alternative to steps 4 you can also do ``python setup.py develop``
-which will install the package via distribute in development mode.  This also
+which will install the package via `distribute` in development mode.  This also
 has the advantage that the C extensions are compiled.
 
 .. _download page: http://pypi.python.org/pypi/Jinja2
+.. _distribute: http://pypi.python.org/pypi/distribute 
 .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
 .. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall
 .. _pip: http://pypi.python.org/pypi/pip
@@ -117,7 +116,7 @@ there and behavior might be inconsistent.  If you notice any bugs, please
 provide feedback in the `Jinja bug tracker`_.
 
 Also please keep in mind that the documentation is written with Python 2
-in mind, you will have to adapt the shown code examples to Python 3 syntax
+in mind, so you will have to adapt the shown code examples to Python 3 syntax
 for yourself.
 
 

jinja2/environment.py

@@ -108,7 +108,7 @@ class Environment(object):
     Modifications on environments after the first template was loaded
     will lead to surprising effects and undefined behavior.
 
-    Here the possible initialization parameters:
+    Here are the possible initialization parameters:
 
         `block_start_string`
             The string marking the begin of a block.  Defaults to ``'{%'``.

jinja2/filters.py

@@ -204,8 +204,7 @@ def do_dictsort(value, case_sensitive=False, by='key'):
             sort the dict by key, case sensitive
 
         {% for item in mydict|dictsort(false, 'value') %}
-            sort the dict by key, case insensitive, sorted
-            normally and ordered by value.
+            sort the dict by value, case insensitive
     """
     if by == 'key':
         pos = 0