README.md in refile-0.4.2 vs README.md in refile-0.5.0

@@ -1,14 +1,20 @@
 # Refile
+
 [![Gem Version](https://badge.fury.io/rb/refile.svg)](http://badge.fury.io/rb/refile)
 [![Build Status](https://travis-ci.org/elabs/refile.svg?branch=master)](https://travis-ci.org/elabs/refile)
 [![Code Climate](https://codeclimate.com/github/elabs/refile/badges/gpa.svg)](https://codeclimate.com/github/elabs/refile)
+[![Inline docs](http://inch-ci.org/github/elabs/refile.svg?branch=master)](http://inch-ci.org/github/elabs/refile)
 
 Refile is a modern file upload library for Ruby applications. It is simple, yet
-powerful. Refile is an attempt by CarrierWave's original author to fix the
-design mistakes and overengineering in CarrierWave.
+powerful.
 
+Links:
+
+- [API documentation](http://www.rubydoc.info/gems/refile)
+- [Source Code](https://github.com/elabs/refile)
+
 Features:
 
 - Configurable backends, file system, S3, etc...
 - Convenient integration with ORMs
 - On the fly manipulation of images and other files
@@ -23,10 +29,20 @@
 ``` ruby
 gem "mini_magick"
 gem "refile", require: ["refile/rails", "refile/image_processing"]
 ```
 
+We're requiring both Refile's Rails integration and image processing via the
+[MiniMagick](https://github.com/minimagick/minimagick) gem, which requires
+[ImageMagick](http://imagemagick.org/) to be installed. To install it simply
+run:
+
+``` sh
+brew install imagemagick # OS X
+sudo apt-get install imagemagick # Ubuntu
+```
+
 Use the `attachment` method to use Refile in a model:
 
 ``` ruby
 class User < ActiveRecord::Base
   attachment :profile_image
@@ -50,11 +66,11 @@
 
 Set up strong parameters:
 
 ``` ruby
 def user_params
-  params.require(:user).permit(:profile_image, :profile_image_cache_id)
+  params.require(:user).permit(:profile_image)
 end
 ```
 
 And start uploading! Finally show the file in your view:
 
@@ -68,11 +84,11 @@
 
 1. Backends: cache and persist files
 2. Model attachments: map files to model columns
 3. A Rack application: streams files and accepts uploads
 4. Rails helpers: conveniently generate markup in your views
-4. A JavaScript library: facilitates direct uploads
+5. A JavaScript library: facilitates direct uploads
 
 Let's look at each of these in more detail!
 
 ## 1. Backend
 
@@ -138,12 +154,12 @@
 
 ``` ruby
 Refile.cache = Refile::Backend::S3.new(max_size: 10.megabytes, ...)
 ```
 
-The Refile gem ships with [S3](lib/refile/backends/s3.rb) and
-[FileSystem](lib/refile/backends/file_system.rb) backends. Additional backends
+The Refile gem ships with [S3](lib/refile/backend/s3.rb) and
+[FileSystem](lib/refile/backend/file_system.rb) backends. Additional backends
 are provided by other gems.
 
 - [Fog](https://github.com/elabs/refile-fog) provides support for a ton of
   different cloud storage providers, including Google Storage and Rackspace
   CloudFiles.
@@ -297,14 +313,14 @@
 example.
 
 ## 4. Rails helpers
 
 Refile provides the `attachment_field` form helper which generates a file field
-as well as a hidden field, suffixed with `cache_id`. This field keeps track of
-the file in case it is not yet permanently stored, for example if validations
-fail. It is also used for direct and presigned uploads. For this reason it is
-highly recommended to use `attachment_field` instead of `file_field`.
+as well as a hidden field. This field keeps track of the file in case it is not
+yet permanently stored, for example if validations fail. It is also used for
+direct and presigned uploads. For this reason it is highly recommended to use
+`attachment_field` instead of `file_field`.
 
 ``` erb
 <%= form_for @user do |form| %>
   <%= form.attachment_field :profile_image %>
 <% end %>
@@ -312,11 +328,11 @@
 
 Will generate something like:
 
 ``` html
 <form action="/users" enctype="multipart/form-data" method="post">
-  <input name="user[profile_image_cache_id]" type="hidden">
+  <input name="user[profile_image]" type="hidden">
   <input name="user[profile_image]" type="file">
 </form>
 ```
 
 The `attachment_url` helper can then be used for generating URLs for the uploaded
@@ -361,10 +377,12 @@
 ``` javascript
 //= require refile
 ```
 
 Otherwise you can grab a copy [here](https://raw.githubusercontent.com/elabs/refile/master/app/assets/javascripts/refile.js).
+Be sure to always update your copy of this file when you upgrade to the latest
+Refile version.
 
 Now mark the field for direct upload:
 
 ``` erb
 <%= form.attachment_field :profile_image, direct: true %>
@@ -474,13 +492,31 @@
 ```
 
 ### Browser compatibility
 
 Refile's JavaScript library requires HTML5 features which are unavailable on
-IE9 and earlier versions. All other major browsers are supported. Note though
-that it has not yet been extensively tested.
+IE9 and earlier versions. All other major browsers are supported.
 
+## Additional metadata
+
+In the quick start example above, we chose to only store the file id, but often
+it is useful to store the file's filename, size and content type as well.
+Refile makes it easy to extract this data and store it alongside the id. All you
+need to do is add columns for these:
+
+``` ruby
+class StoreMetadata < ActiveRecord::Migration
+  def change
+    add_column :profile_image_filename
+    add_column :profile_image_size
+    add_column :profile_image_content_type
+  end
+end
+```
+
+These columns will now be filled automatically.
+
 ## File type validations
 
 Refile can check that attached files have a given content type or extension.
 This allows you to warn users if they try to upload an invalid file.
 
@@ -494,11 +530,11 @@
 ``` ruby
 attachment :cv, extension: "pdf"
 attachment :profile_image, content_type: "image/jpeg"
 ```
 
-You can also provide a list of content type or extensions:
+You can also provide a list of content types or extensions:
 
 ``` ruby
 attachment :cv, extension: ["pdf", "doc"]
 attachment :profile_image, content_type: ["image/jpeg", "image/png", "image/gif"]
 ```
@@ -511,10 +547,25 @@
 ```
 
 When a user uploads a file with an invalid extension or content type and
 submits the form, they'll be presented with a validation error.
 
+If you use a particular content type or set of content types frequently
+you can define your own types like this:
+
+``` ruby
+Refile.types[:document] = Refile::Type.new(:document,
+  content_type: %w[text/plain application/pdf]
+)
+```
+
+Now you can use them like this:
+
+``` ruby
+attachment :profile_image, type: :document
+```
+
 ## Removing attached files
 
 File input fields unfortunately do not have the option of removing an already
 uploaded file. This is problematic when editing a model which has a file attached
 and the user wants to remove this file. To work around this, Refile automatically
@@ -533,11 +584,11 @@
 
 Don't forget to permit this attribute in your controller:
 
 ``` ruby
 def user_params
-  params.require(:user).permit(:profile_image, :profile_image_cache_id, :remove_profile_image)
+  params.require(:user).permit(:profile_image, :remove_profile_image)
 end
 ```
 
 Now when you check this checkbox and submit the form, the previously attached
 file will be removed.
@@ -561,10 +612,10 @@
 
 Then permit this field in your controller:
 
 ``` ruby
 def user_params
-  params.require(:user).permit(:profile_image, :profile_image_cache_id, :remote_profile_image_url)
+  params.require(:user).permit(:profile_image, :remote_profile_image_url)
 end
 ```
 
 Refile will now fetch the file from the given URL, following redirects if
 needed.