Permalink
Browse files

First pass on editing the README for more readability.

  • Loading branch information...
1 parent 1df1b03 commit adcd03c93efc140c44433b3fe4a6d563a251061d @sikachu sikachu committed Dec 14, 2011
Showing with 42 additions and 23 deletions.
  1. +42 −23 README.md
View
@@ -1,6 +1,9 @@
-# Paperclip [![Build Status](https://secure.travis-ci.org/thoughtbot/paperclip.png?branch=master)](http://travis-ci.org/thoughtbot/paperclip) [![Dependency Status](https://gemnasium.com/thoughtbot/paperclip.png?travis)](https://gemnasium.com/thoughtbot/paperclip)
+Paperclip
+=========
-Paperclip is intended as an easy file attachment library for ActiveRecord. The
+[![Build Status](https://secure.travis-ci.org/thoughtbot/paperclip.png?branch=master)](http://travis-ci.org/thoughtbot/paperclip) [![Dependency Status](https://gemnasium.com/thoughtbot/paperclip.png?travis)](https://gemnasium.com/thoughtbot/paperclip)
+
+Paperclip is intended as an easy file attachment library for Active Record. The
intent behind it was to keep setup as easy as possible and to treat files as
much like other attributes as possible. This means they aren't saved to their
final locations on disk, nor are they deleted if set to nil, until
@@ -12,11 +15,12 @@ packages). Attached files are saved to the filesystem and referenced in the
browser by an easily understandable specification, which has sensible and
useful defaults.
-See the documentation for `has_attached_file` in Paperclip::ClassMethods for
+See the documentation for `has_attached_file` in [`Paperclip::ClassMethods`](http://rubydoc.info/gems/paperclip/Paperclip/ClassMethods) for
more detailed options.
The complete [RDoc](http://rdoc.info/gems/paperclip) is online.
+
Requirements
------------
@@ -32,14 +36,16 @@ In development mode, you might add this line to `config/environments/development
Paperclip.options[:command_path] = "/usr/local/bin/"
-If you're on Mac OSX, you'll want to run the following with Homebrew:
+If you're on Mac OS X, you'll want to run the following with Homebrew:
brew install imagemagick
-If you are dealing with pdf uploads or running the test suite, also run:
+If you are dealing with pdf uploads or running the test suite, you'll also need
+GhostScript to be installed. On Mac OS X, you can also install that using Homebrew:
brew install gs
+
Installation
------------
@@ -60,6 +66,7 @@ Or, if you don't use Bundler (though you probably should, even in Rails 2), with
config.gem "paperclip", :version => "~> 2.4"
...
end
+
For Non-Rails usage:
class ModuleName < ActiveRecord::Base
@@ -117,44 +124,55 @@ Usage
-----
The basics of paperclip are quite simple: Declare that your model has an
-attachment with the has\_attached\_file method, and give it a name. Paperclip
-will wrap up up to four attributes (all prefixed with that attachment's name,
+attachment with the `has_attached_file` method, and give it a name.
+
+Paperclip will wrap up up to four attributes (all prefixed with that attachment's name,
so you can have multiple attachments per model if you wish) and give them a
-friendly front end. The attributes are `<attachment>_file_name`,
-`<attachment>_file_size`, `<attachment>_content_type`, and `<attachment>_updated_at`.
-Only `<attachment>_file_name` is required for paperclip to operate. More
-information about the options to has\_attached\_file is available in the
-documentation of Paperclip::ClassMethods.
+friendly front end. These attributes are:
+
+* `<attachment>_file_name`
+* `<attachment>_file_size`
+* `<attachment>_content_type`
+* `<attachment>_updated_at`
-Attachments can be validated with Paperclip's validation methods,
-validates\_attachment\_presence, validates\_attachment\_content\_type, and
-validates\_attachment\_size.
+By default, only `<attachment>_file_name` is required for paperclip to operate.
+You'll need to add `<attachment>_content_type` in case you want to use content type
+validation.
+
+More information about the options to `has_attached_file` is available in the
+documentation of [`Paperclip::ClassMethods`](http://rubydoc.info/gems/paperclip/Paperclip/ClassMethods).
+
+For validations, attachments can be validated with these Paperclip's validation methods:
+
+* `validates_attachment_presence`
+* `validates_attachment_content_type`
+* `validates_attachment_size`
Storage
-------
The files that are assigned as attachments are, by default, placed in the
-directory specified by the :path option to has\_attached\_file. By default, this
-location is ":rails\_root/public/system/:attachment/:id/:style/:filename". This
+directory specified by the `:path` option to `has_attached_file`. By default, this
+location is `:rails_root/public/system/:attachment/:id/:style/:filename`. This
location was chosen because on standard Capistrano deployments, the
-public/system directory is symlinked to the app's shared directory, meaning it
-will survive between deployments. For example, using that :path, you may have a
+`public/system` directory is symlinked to the app's shared directory, meaning it
+will survive between deployments. For example, using that `:path`, you may have a
file at
/data/myapp/releases/20081229172410/public/system/avatars/13/small/my_pic.png
-_NOTE: This is a change from previous versions of Paperclip, but is overall a
+_**NOTE**: This is a change from previous versions of Paperclip, but is overall a
safer choice for the default file store._
You may also choose to store your files using Amazon's S3 service. You can find
more information about S3 storage at the description for
-Paperclip::Storage::S3.
+[`Paperclip::Storage::S3`](http://rubydoc.info/gems/paperclip/Paperclip/Storage/S3).
Files on the local filesystem (and in the Rails app's public directory) will be
available to the internet at large. If you require access control, it's
possible to place your files in a different location. You will need to change
-both the :path and :url options in order to make sure the files are unavailable
-to the public. Both :path and :url allow the same set of interpolated
+both the `:path` and `:url` options in order to make sure the files are unavailable
+to the public. Both `:path` and `:url` allow the same set of interpolated
variables.
Post Processing
@@ -409,3 +427,4 @@ License
-------
Paperclip is Copyright © 2008-2011 thoughtbot. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.
+

0 comments on commit adcd03c

Please sign in to comment.