General edit of new FileStore docs

Edit text for clarity, simplicity.

doc/filestore.rst

@@ -2,8 +2,13 @@
 FileStore and file uploads
 ==========================
 
-CKAN allows users to upload files directly to it against a resource or images
-displayed against groups and organizations.
+When enabled, CKAN's FileStore allows users to upload data files to CKAN
+resources, and to upload logo images for groups and organizations. Users will
+see an upload button when creating or updating a resource, group or
+organization.
+
+.. versionadded:: 2.2
+   Uploading logo images for groups and organizations was added in CKAN 2.2.
 
 .. versionchanged:: 2.2
    Previous versions of CKAN used to allow uploads to remote cloud hosting but
@@ -23,16 +28,17 @@ To setup CKAN's FileStore with local file storage:
 
      sudo mkdir -p |storage_path|
 
-2. Add the following lines to your CKAN config file, after the ``[app:main]``
+2. Add the following line to your CKAN config file, after the ``[app:main]``
    line:
 
    .. parsed-literal::
 
       ckan.storage_path = |storage_path|
 
-3. Set the permissions of the :ref:`ckan.storage_path`. For example if you're running
-   CKAN with Apache, then Apache's user (``www-data`` on Ubuntu) must have
-   read, write and execute permissions for the :ref:`ckan.storage_path`:
+3. Set the permissions of your :ref:`ckan.storage_path` directory.
+   For example if you're running CKAN with Apache, then Apache's user
+   (``www-data`` on Ubuntu) must have read, write and execute permissions for
+   the :ref:`ckan.storage_path`:
 
    .. parsed-literal::
 
@@ -46,36 +52,33 @@ To setup CKAN's FileStore with local file storage:
       |reload_apache|
 
 
------------------------
-FileStore web interface
------------------------
-
-Upload of files to storage is integrated directly into the Dataset creation
-and editing system with files being associated to Resources.
-
 -------------
 FileStore API
 -------------
 
 .. versionchanged:: 2.2
-    The previous API has been deprecated although should still work if you where
-    using local file storage.
+   The FileStore API was redesigned for CKAN 2.2.
+   The previous API has been deprecated.
 
-The API is part of the :py:func:`~ckan.logic.action.create.resource_create` and
+Files can be uploaded to the FileStore using the
+:py:func:`~ckan.logic.action.create.resource_create` and
 :py:func:`~ckan.logic.action.update.resource_update` action API
 functions. You can post mutipart/form-data to the API and the key, value
 pairs will treated as as if they are a JSON object.
 The extra key ``upload`` is used to actually post the binary data.
 
-Curl automatically puts the multipart-form-data heading when using the
-``--form`` option:
+For example, to create a new CKAN resource and upload a file to it using 
+`curl <http://curl.haxx.se/>`_:
 
 .. parsed-literal::
 
  curl -H'Authorization: your-api-key' 'http://yourhost/api/action/resource_create' --form upload=@filetoupload --form package_id=my_dataset
 
-The Python requests library used the files parameter and automatically sets
-the multipart/form-data header too:
+(Curl automatically sends a ``multipart-form-data`` heading with you use the
+``--form`` option.)
+
+To create a new resource and upload a file to it using the Python library
+`requests <http://python-requests.org/>`_:
 
 .. parsed-literal::
 
@@ -85,13 +88,17 @@ the multipart/form-data header too:
                headers={"X-CKAN-API-Key": "21a47217-6d7b-49c5-88f9-72ebd5a4d4bb"},
                files=[('upload', file('/path/to/file/to/upload.csv'))])
 
-With :py:func:`~ckan.logic.action.update.resource_update`, if you want to
-override a file you just need to set the upload field again::
+(Requests automatically sends a ``multipart-form-data`` heading when you use the
+``files=`` parameter.)
+
+To overwrite an uploaded file with a new version of the file, post to the
+:py:func:`~ckan.logic.action.update.resource_update` action and use the
+``upload`` field::
 
     curl -H'Authorization: your-api-key' 'http://yourhost/api/action/resource_update' --form upload=@newfiletoupload --form id=resourceid
 
-If you want to clear the upload and change it for a remote URL
-there is special boolean field clear_upload to do this::
+To replace an uploaded file with a link to a file at a remote URL, use the
+``clear_upload`` field::
 
     curl -H'Authorization: your-api-key' 'http://yourhost/api/action/resource_update' --form url=http://expample.com --form clear_upload=true --form id=resourceid