Editing while reading: punctuation, markup, linebreaks

I fixed some extra commas, missing apostrophes, and typos;
added some linebreaks between sentences for very long lines;
added explicit markup for console blocks,
got rid of some tabs,
fixed indentation of an admonition, and some more small tweaks.

This supersedes https://github.com/kennethreitz/tablib/pull/84

5 files changed, 132 insertions, 73 deletions

diff --git a/docs/development.rst b/docs/development.rst
index 3ab05d5..5dcd920 100644
--- a/docs/development.rst
+++ b/docs/development.rst
@@ -43,10 +43,11 @@ control machine.
 
 The repository is publicly accessible.
 
-    ``git clone git://github.com/kennethreitz/tablib.git``
+.. code-block:: console
 
-The project is hosted on **GitHub**.
+    git clone git://github.com/kennethreitz/tablib.git
 
+The project is hosted on **GitHub**.
 
     GitHub:
         http://github.com/kennethreitz/tablib
@@ -55,10 +56,9 @@ The project is hosted on **GitHub**.
 Git Branch Structure
 ++++++++++++++++++++
 
-Feature / Hotfix / Release branches follow a `Successful Git Branching Model`_ . Git-flow_ is a great tool for managing the repository. I highly recommend it.
+Feature / Hotfix / Release branches follow a `Successful Git Branching Model`_ .
+Git-flow_ is a great tool for managing the repository. I highly recommend it.
 
-``develop``
-    The "next release" branch. Likely unstable.
 ``master``
     Current production release (|version|) on PyPi.
 
@@ -86,11 +86,14 @@ Tablib welcomes new format additions! Format suggestions include:
 Coding by Convention
 ++++++++++++++++++++
 
-Tablib features a micro-framework for adding format support. The easiest way to understand it is to use it. So, let's define our own format, named *xxx*.
+Tablib features a micro-framework for adding format support.
+The easiest way to understand it is to use it.
+So, let's define our own format, named *xxx*.
 
 1. Write a new format interface.
 
-    :class:`tablib.core` follows a simple pattern for automatically utilizing your format throughout Tablib. Function names are crucial.
+    :class:`tablib.core` follows a simple pattern for automatically utilizing your format throughout Tablib.
+    Function names are crucial.
 
     Example **tablib/formats/_xxx.py**: ::
 
@@ -116,17 +119,18 @@ Tablib features a micro-framework for adding format support. The easiest way to
             ...
             # returns True if given stream is parsable as xxx
 
-.. admonition:: Excluding Support
-
+   .. admonition:: Excluding Support
 
-    If the format excludes support for an import/export mechanism (*eg.* :class:`csv <tablib.Dataset.csv>` excludes :class:`Databook <tablib.Databook>` support), simply don't define the respective functions. Appropriate errors will be raised.
+       If the format excludes support for an import/export mechanism (*e.g.* 
+       :class:`csv <tablib.Dataset.csv>` excludes 
+       :class:`Databook <tablib.Databook>` support),
+       simply don't define the respective functions.
+       Appropriate errors will be raised.
 
-2.
+2. Add your new format module to the :class:`tablib.formats.available` tuple.
 
-    Add your new format module to the :class:`tablib.formats.available` tuple.
-
-3.
-    Add a mock property to the :class:`Dataset <tablib.Dataset>` class with verbose `reStructured Text`_ docstring. This alleviates IDE confusion, and allows for pretty auto-generated Sphinx_ documentation.
+3. Add a mock property to the :class:`Dataset <tablib.Dataset>` class with verbose `reStructured Text`_ docstring. 
+   This alleviates IDE confusion, and allows for pretty auto-generated Sphinx_ documentation.
 
 4. Write respective :ref:`tests <testing>`.
 
@@ -136,22 +140,33 @@ Tablib features a micro-framework for adding format support. The easiest way to
 Testing Tablib
 --------------
 
-Testing is crucial to Tablib's stability. This stable project is used in production by many companies and developers, so it is important to be certain that every version released is fully operational. When developing a new feature for Tablib, be sure to write proper tests for it as well.
+Testing is crucial to Tablib's stability.
+This stable project is used in production by many companies and developers,
+so it is important to be certain that every version released is fully operational.
+When developing a new feature for Tablib, be sure to write proper tests for it as well.
+
+When developing a feature for Tablib,
+the easiest way to test your changes for potential issues is to simply run the test suite directly.
 
-When developing a feature for Tablib, the easiest way to test your changes for potential issues is to simply run the test suite directly. ::
+.. code-block:: console
 
-	$ ./test_tablib.py
+    $ ./test_tablib.py
 
 
-`Jenkins CI`_, amongst other tools, supports Java's xUnit testing report format. Nose_ allows us to generate our own xUnit reports.
+`Jenkins CI`_, amongst other tools, supports Java's xUnit testing report format.
+Nose_ allows us to generate our own xUnit reports.
 
-Installing nose is simple. ::
+Installing nose is simple.
 
-	$ pip install nose
+.. code-block:: console
 
-Once installed, we can generate our xUnit report with a single command. ::
+    $ pip install nose
 
-	$ nosetests test_tablib.py --with-xunit
+Once installed, we can generate our xUnit report with a single command.
+
+.. code-block:: console
+
+    $ nosetests test_tablib.py --with-xunit
 
 This will generate a **nosetests.xml** file, which can then be analyzed.
 
@@ -165,7 +180,9 @@ This will generate a **nosetests.xml** file, which can then be analyzed.
 Continuous Integration
 ----------------------
 
-Every commit made to the **develop** branch is automatically tested and inspected upon receipt with `Travis CI`_. If you have access to the main repository and broke the build, you will receive an email accordingly.
+Every commit made to the **develop** branch is automatically tested and inspected upon receipt with `Travis CI`_.
+If you have access to the main repository and broke the build,
+you will receive an email accordingly.
 
 Anyone may view the build status and history at any time.
 
@@ -182,19 +199,27 @@ Additional reports will also be included here in the future, including :pep:`8`
 Building the Docs
 -----------------
 
-Documentation is written in the powerful, flexible, and standard Python documentation format, `reStructured Text`_.
-Documentation builds are powered by the powerful Pocoo project, Sphinx_. The :ref:`API Documentation <api>` is mostly documented inline throughout the module.
+Documentation is written in the powerful, flexible,
+and standard Python documentation format, `reStructured Text`_.
+Documentation builds are powered by the powerful Pocoo project, Sphinx_.
+The :ref:`API Documentation <api>` is mostly documented inline throughout the module.
+
+The Docs live in ``tablib/docs``.
+In order to build them, you will first need to install Sphinx.
+
+.. code-block:: console
 
-The Docs live in ``tablib/docs``. In order to build them, you will first need to install Sphinx. ::
+    $ pip install sphinx
 
-	$ pip install sphinx
 
+Then, to build an HTML version of the docs, simply run the following from the ``docs`` directory:
 
-Then, to build an HTML version of the docs, simply run the following from the **docs** directory: ::
+.. code-block:: console
 
-	$ make html
+    $ make html
 
-Your ``docs/_build/html`` directory will then contain an HTML representation of the documentation, ready for publication on most web servers.
+Your ``docs/_build/html`` directory will then contain an HTML representation of the documentation,
+ready for publication on most web servers.
 
 You can also generate the documentation in **epub**, **latex**, **json**, *&c* similarly.
 
diff --git a/docs/index.rst b/docs/index.rst
index 20103b6..f21582e 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -22,7 +22,10 @@ Release v\ |version|. (:ref:`Installation <install>`)
 .. * :ref:`search`
 
 
-Tablib is an :ref:`MIT Licensed <mit>` format-agnostic tabular dataset library, written in Python. It allows you to import, export, and manipulate tabular data sets. Advanced features include, segregation, dynamic columns, tags & filtering, and seamless format import & export.
+Tablib is an :ref:`MIT Licensed <mit>` format-agnostic tabular dataset library, written in Python.
+It allows you to import, export, and manipulate tabular data sets.
+Advanced features include segregation, dynamic columns, tags & filtering,
+and seamless format import & export.
 
 ::
 
@@ -37,7 +40,7 @@ Tablib is an :ref:`MIT Licensed <mit>` format-agnostic tabular dataset library,
    - {Age: 21, First Name: Bessie, Last Name: Monke}
 
    >>> data.xlsx
-   <censored binary data>
+   <redacted binary data>
 
 
 Testimonials
@@ -52,16 +55,20 @@ and `The Sunlight Foundation <http://sunlightfoundation.com/>`_ use Tablib inter
 
 
 **Greg Thorton**
-   Tablib by @kennethreitz saved my life. I had to consolidate like 5 huge poorly maintained lists of domains and data. It was a breeze!
+   Tablib by @kennethreitz saved my life.
+   I had to consolidate like 5 huge poorly maintained lists of domains and data.
+   It was a breeze!
 
 **Dave Coutts**
-   It's turning into one of my most used modules of 2010. You really hit a sweet spot for managing tabular data with a minimal amount of code and effort.
+   It's turning into one of my most used modules of 2010.
+   You really hit a sweet spot for managing tabular data with a minimal amount of code and effort.
 
 **Joshua Ourisman**
    Tablib has made it so much easier to deal with the inevitable 'I want an Excel file!' requests from clients...
 
 **Brad Montgomery**
-    I think you nailed the "Python Zen" with tablib. Thanks again for an awesome lib!
+    I think you nailed the "Python Zen" with tablib.
+    Thanks again for an awesome lib!
 
 
 User's Guide
diff --git a/docs/install.rst b/docs/install.rst
index 7b0b00b..c332325 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -2,7 +2,9 @@
 Installation
 ============
 
-This part of the documentation covers the installation of Tablib. The first step to using any software package is getting it properly installed. Please read this section carefully, or you may miss out on some nice  :ref:`speed enhancements <peed-extensions>`.
+This part of the documentation covers the installation of Tablib.
+The first step to using any software package is getting it properly installed.
+Please read this section carefully, or you may miss out on some nice  :ref:`speed enhancements <peed-extensions>`.
 
 
 .. _installing:
@@ -14,7 +16,8 @@ Installing Tablib
 Distribute & Pip
 ----------------
 
-Of course, the recommended way to install Tablib is with `pip <http://www.pip-installer.org/>`_::
+Of course, the recommended way to install Tablib is with `pip <http://www.pip-installer.org/>`_:
+.. code-block:: console
 
     $ pip install tablib
 
@@ -23,13 +26,19 @@ Of course, the recommended way to install Tablib is with `pip <http://www.pip-in
 Download the Source
 -------------------
 
-You can also install tablib from source. The latest release (|version|) is available from GitHub.
+You can also install tablib from source.
+The latest release (|version|) is available from GitHub.
 
 * tarball_
 * zipball_
 
 .. _
-Once you have a copy of the source, you can embed it in your Python package, or install it into your site-packages easily. ::
+
+Once you have a copy of the source,
+you can embed it in your Python package,
+or install it into your site-packages easily.
+
+.. code-block:: console
 
     $ python setup.py install
 
@@ -46,25 +55,32 @@ Speed Extensions
 
 .. versionadded:: 0.8.5
 
-Tablib is partially dependent on the **pyyaml**, **simplejson**, and **xlwt** modules. To reduce installation issues, fully integrated versions of all required libraries are included in Tablib.
+Tablib is partially dependent on the **pyyaml**, **simplejson**, and **xlwt** modules.
+To reduce installation issues, fully integrated versions of all required libraries are included in Tablib.
+
+However, if performance is important to you (and it should be), you can install  **pyyaml** with C extensions from PyPi.
 
-However, if performance is important to you (and it should be), you can install  **pyyaml** with C extensions from PyPi. ::
+.. code-block:: console
 
     $ pip install PyYAML
 
-If you're using Python 2.5, you should also install the **simplejson** module (pip will do this for you). If you're using Python 2.6+, the built-in **json** module is already optimized and in use. ::
+If you're using Python 2.5, you should also install the **simplejson** module (pip will do this for you).
+If you're using Python 2.6+, the built-in **json** module is already optimized and in use.
+
+.. code-block:: console
 
     $ pip install simplejson
 
 
 
 .. _updates:
+
 Staying Updated
 ---------------
 
 The latest version of Tablib will always be available here:
 
-* PyPi: http://pypi.python.org/pypi/tablib/
+* PyPI: http://pypi.python.org/pypi/tablib/
 * GitHub: http://github.com/kennethreitz/tablib/
 
 When a new version is available, upgrading is simple::
diff --git a/docs/intro.rst b/docs/intro.rst
index 0977ecb..fc952d0 100644
--- a/docs/intro.rst
+++ b/docs/intro.rst
@@ -6,16 +6,15 @@ Introduction
 This part of the documentation covers all the interfaces of Tablib.
 Tablib is a format-agnostic tabular dataset library, written in Python.
 It allows you to Pythonically import, export, and manipulate tabular data sets.
-Advanced features include, segregation, dynamic columns, tags / filtering, and
+Advanced features include segregation, dynamic columns, tags / filtering, and
 seamless format import/export.
 
 
 Philosophy
----------
+----------
 
 Tablib was developed with a few :pep:`20` idioms in mind.
 
-
 #. Beautiful is better than ugly.
 #. Explicit is better than implicit.
 #. Simple is better than complex.
diff --git a/docs/tutorial.rst b/docs/tutorial.rst
index d552e21..7545e66 100644
--- a/docs/tutorial.rst
+++ b/docs/tutorial.rst
@@ -8,7 +8,10 @@ Quickstart
 .. module:: tablib
 
 
-Eager to get started? This page gives a good introduction in how to get started with Tablib. This assumes you already have Tablib installed. If you do not, head over to the :ref:`Installation <install>` section.
+Eager to get started?
+This page gives a good introduction in how to get started with Tablib.
+This assumes you already have Tablib installed.
+If you do not, head over to the :ref:`Installation <install>` section.
 
 First, make sure that:
 
@@ -16,7 +19,7 @@ First, make sure that:
 * Tablib is :ref:`up-to-date <updates>`
 
 
-Lets gets started with some simple use cases and examples.
+Let's get started with some simple use cases and examples.
 
 
 
@@ -35,8 +38,8 @@ You can now start filling this :class:`Dataset <tablib.Dataset>` object with dat
 
 .. admonition:: Example Context
 
-     From here on out, if you see ``data``, assume that it's a fresh :class:`Dataset <tablib.Dataset>` object.
-
+    From here on out, if you see ``data``, assume that it's a fresh 
+    :class:`Dataset <tablib.Dataset>` object.
 
 
 
@@ -57,7 +60,7 @@ Let's say you want to collect a simple list of names. ::
         # add names to Dataset
         data.append([fname, lname])
 
-You can get a nice, Pythonic view of the dataset at any time with :class:`Dataset.dict`.
+You can get a nice, Pythonic view of the dataset at any time with :class:`Dataset.dict`::
 
     >>> data.dict
     [('Kenneth', 'Reitz'), ('Bessie', 'Monke')]
@@ -69,14 +72,16 @@ Adding Headers
 --------------
 
 
-It's time to enhance our :class:`Dataset` by giving our columns some titles. To do so, set :class:`Dataset.headers`. ::
+It's time to enhance our :class:`Dataset` by giving our columns some titles.
+To do so, set :class:`Dataset.headers`. ::
 
     data.headers = ['First Name', 'Last Name']
 
 Now our data looks a little different. ::
 
     >>> data.dict
-    [{'Last Name': 'Reitz', 'First Name': 'Kenneth'}, {'Last Name': 'Monke', 'First Name': 'Bessie'}]
+    [{'Last Name': 'Reitz', 'First Name': 'Kenneth'},
+     {'Last Name': 'Monke', 'First Name': 'Bessie'}]
 
 
 
@@ -93,7 +98,8 @@ Now that we have a basic :class:`Dataset` in place, let's add a column of **ages
 Let's view the data now. ::
 
     >>> data.dict
-    [{'Last Name': 'Reitz', 'First Name': 'Kenneth', 'Age': 22}, {'Last Name': 'Monke', 'First Name': 'Bessie', 'Age': 20}]
+    [{'Last Name': 'Reitz', 'First Name': 'Kenneth', 'Age': 22},
+     {'Last Name': 'Monke', 'First Name': 'Bessie', 'Age': 20}]
 
 It's that easy.
 
@@ -136,7 +142,7 @@ Tablib's killer feature is the ability to export your :class:`Dataset` objects i
 **Microsoft Excel** ::
 
     >>> data.xls
-    <censored binary data>
+    <redacted binary data>
 
 
 ------------------------
@@ -150,7 +156,8 @@ You can slice and dice your data, just like a standard Python list. ::
     ('Kenneth', 'Reitz', 22)
 
 
-If we had a set of data consisting of thousands of rows, it could be useful to get a list of values in a column.
+If we had a set of data consisting of thousands of rows,
+it could be useful to get a list of values in a column.
 To do so, we access the :class:`Dataset` as if it were a standard Python dictionary.  ::
 
     >>> data['First Name']
@@ -175,11 +182,11 @@ Let's find the average age. ::
 Removing Rows & Columns
 -----------------------
 
-It's easier than you could imagine::
+It's easier than you could imagine. Delete a column::
 
     >>> del data['Col Name']
 
-::
+Delete a range of rows::
 
     >>> del data[0:12]
 
@@ -188,7 +195,6 @@ It's easier than you could imagine::
 Advanced Usage
 ==============
 
-
 This part of the documentation services to give you an idea that are otherwise hard to extract from the :ref:`API Documentation <api>`
 
 And now for something completely different.
@@ -202,9 +208,11 @@ Dynamic Columns
 
 .. versionadded:: 0.8.3
 
-Thanks to Josh Ourisman, Tablib now supports adding dynamic columns. A dynamic column is a single callable object (*ie.* a function).
+Thanks to Josh Ourisman, Tablib now supports adding dynamic columns.
+A dynamic column is a single callable object (*e.g.* a function).
 
-Let's add a dynamic column to our :class:`Dataset` object. In this example, we have a function that generates a random grade for our students. ::
+Let's add a dynamic column to our :class:`Dataset` object.
+In this example, we have a function that generates a random grade for our students. ::
 
     import random
 
@@ -226,7 +234,8 @@ Let's remove that column.  ::
     >>> del data['Grade']
 
 
-When you add a dynamic column, the first argument that is passed in to the given callable is the current data row. You can use this to perform calculations against your data row.
+When you add a dynamic column, the first argument that is passed in to the given callable is the current data row.
+You can use this to perform calculations against your data row.
 
 For example, we can use the data available in the row to guess the gender of a student. ::
 
@@ -260,9 +269,11 @@ Filtering Datasets with Tags
 .. versionadded:: 0.9.0
 
 
-When constructing a :class:`Dataset` object, you can add tags to rows by specifying the ``tags`` parameter.
-This allows you to filter your :class:`Dataset` later. This can be useful to separate rows of data based on
-arbitrary criteria (*e.g.* origin) that you don't want to include in your :class:`Dataset`.
+When constructing a :class:`Dataset` object,
+you can add tags to rows by specifying the ``tags`` parameter.
+This allows you to filter your :class:`Dataset` later.
+This can be useful to separate rows of data based on arbitrary criteria
+(*e.g.* origin) that you don't want to include in your :class:`Dataset`.
 
 Let's tag some students. ::
 
@@ -285,10 +296,12 @@ It's that simple. The original :class:`Dataset` is untouched.
 Excel Workbook With Multiple Sheets
 ------------------------------------
 
-When dealing with a large number of :class:`Datasets <Dataset>` in spreadsheet format, it's quite common to group multiple spreadsheets into a single Excel file, known as a Workbook. Tablib makes it extremely easy to build workbooks with the handy, :class:`Databook` class.
+When dealing with a large number of :class:`Datasets <Dataset>` in spreadsheet format,
+it's quite common to group multiple spreadsheets into a single Excel file, known as a Workbook.
+Tablib makes it extremely easy to build workbooks with the handy :class:`Databook` class.
 
-
-Let's say we have 3 different :class:`Datasets <Dataset>`. All we have to do is add then to a :class:`Databook` object... ::
+Let's say we have 3 different :class:`Datasets <Dataset>`.
+All we have to do is add them to a :class:`Databook` object... ::
 
     book = tablib.Databook((data1, data2, data3))
 
@@ -297,7 +310,7 @@ Let's say we have 3 different :class:`Datasets <Dataset>`. All we have to do is
     with open('students.xls', 'wb') as f:
         f.write(book.xls)
 
-The resulting **students.xls** file will contain a separate spreadsheet for each :class:`Dataset` object in the :class:`Databook`.
+The resulting ``students.xls`` file will contain a separate spreadsheet for each :class:`Dataset` object in the :class:`Databook`.
 
 .. admonition:: Binary Warning
 
@@ -312,9 +325,8 @@ Separators
 
 .. versionadded:: 0.8.2
 
-When, it's often useful to create a blank row containing information on the upcoming data. So,
-
-
+When constructing a spreadsheet,
+it's often useful to create a blank row containing information on the upcoming data. So,
 
 ::