convert the readme to markdown and add proper trademark and license info

deff9cf5 · Chad Pytel · 7a38ef79 · deff9cf5
Commit deff9cf5 authored Jan 19, 2011 by Chad Pytel
Hide whitespace changes
Inline Side-by-side

Showing with 76 additions and 55 deletions

README.md
+76 -55

No files found.
--- a/README.rdoc
+++ b/README.rdoc
-=Paperclip
+Paperclip
+=========
 Paperclip is intended as an easy file attachment library for ActiveRecord. The
 intent behind it was to keep setup as easy as possible and to treat files as
@@ -12,76 +13,77 @@ 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 for
 more detailed options.
 The complete RDoc[http://rdoc.info/gems/paperclip] is online.
-==Installation
+Installation
+------------
 Include the gem in your Gemfile:
-  gem "paperclip", "~> 2.3"
+    gem "paperclip", "~> 2.3"
-==Installation
+Or as a plugin:
-As a plugin:
  ruby script/plugin install git://github.com/thoughtbot/paperclip.git
-==Quick Start
+Quick Start
+-----------
 In your model:
-  class User < ActiveRecord::Base
+    class User < ActiveRecord::Base
-    has_attached_file :avatar, :styles => { :medium => "300x300>", :thumb => "100x100>" }
+      has_attached_file :avatar, :styles => { :medium => "300x300>", :thumb => "100x100>" }
-  end
+    end
 In your migrations:
-  class AddAvatarColumnsToUser < ActiveRecord::Migration
+    class AddAvatarColumnsToUser < ActiveRecord::Migration
-    def self.up
+      def self.up
-      add_column :users, :avatar_file_name,    :string
+        add_column :users, :avatar_file_name,    :string
-      add_column :users, :avatar_content_type, :string
+        add_column :users, :avatar_content_type, :string
-      add_column :users, :avatar_file_size,    :integer
+        add_column :users, :avatar_file_size,    :integer
-      add_column :users, :avatar_updated_at,   :datetime
+        add_column :users, :avatar_updated_at,   :datetime
-    end
+      end
-    def self.down
+      def self.down
-      remove_column :users, :avatar_file_name
+        remove_column :users, :avatar_file_name
-      remove_column :users, :avatar_content_type
+        remove_column :users, :avatar_content_type
-      remove_column :users, :avatar_file_size
+        remove_column :users, :avatar_file_size
-      remove_column :users, :avatar_updated_at
+        remove_column :users, :avatar_updated_at
+      end
    end
-  end
 In your edit and new views:
-  <% form_for :user, @user, :url => user_path, :html => { :multipart => true } do |form| %>
+    <% form_for :user, @user, :url => user_path, :html => { :multipart => true } do |form| %>
-    <%= form.file_field :avatar %>
+      <%= form.file_field :avatar %>
-  <% end %>
+    <% end %>
 In your controller:
-  def create
+    def create
-    @user = User.create( params[:user] )
+      @user = User.create( params[:user] )
-  end
+    end
 In your show view:
-  <%= image_tag @user.avatar.url %>
+    <%= image_tag @user.avatar.url %>
-  <%= image_tag @user.avatar.url(:medium) %>
+    <%= image_tag @user.avatar.url(:medium) %>
-  <%= image_tag @user.avatar.url(:thumb) %>
+    <%= image_tag @user.avatar.url(:thumb) %>
-==Usage
+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,
 so you can have multiple attachments per model if you wish) and give the a
-friendly front end. The attributes are <attachment>_file_name,
+friendly front end. The attributes are `<attachment>_file_name`,
-<attachment>_file_size, <attachment>_content_type, and <attachment>_updated_at.
+`<attachment>_file_size`, `<attachment>_content_type`, and `<attachment>_updated_at`.
-Only <attachment>_file_name is required for paperclip to operate. More
+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.
@@ -89,7 +91,8 @@ Attachments can be validated with Paperclip's validation methods,
 validates_attachment_presence, validates_attachment_content_type, and
 validates_attachment_size.
-==Storage
+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
@@ -99,10 +102,10 @@ 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
+    /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.
+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
@@ -115,7 +118,8 @@ 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
+Post Processing
+---------------
 Paperclip supports an extensible selection of post-processors. When you define
 a set of styles for an attachment, by default it is expected that those
@@ -126,8 +130,8 @@ your Rails app's lib/paperclip_processors directory is automatically loaded by
 paperclip, allowing you to easily define custom processors. You can specify a
 processor with the :processors option to has_attached_file:
-  has_attached_file :scan, :styles => { :text => { :quality => :better } },
+    has_attached_file :scan, :styles => { :text => { :quality => :better } },
-                           :processors => [:ocr]
+                             :processors => [:ocr]
 This would load the hypothetical class Paperclip::Ocr, which would have the
 hash "{ :quality => :better }" passed to it along with the uploaded file. For
@@ -137,7 +141,7 @@ The default processor is Paperclip::Thumbnail. For backwards compatability
 reasons, you can pass a single geometry string or an array containing a
 geometry and a format, which the file will be converted to, like so:
-  has_attached_file :avatar, :styles => { :thumb => ["32x32#", :png] }
+    has_attached_file :avatar, :styles => { :thumb => ["32x32#", :png] }
 This will convert the "thumb" style to a 32x32 square in png format, regardless
 of what was uploaded. If the format is not specified, it is kept the same (i.e.
@@ -149,17 +153,18 @@ be given the result of the previous processor's execution. All processors will
 receive the same parameters, which are what you define in the :styles hash.
 For example, assuming we had this definition:
-  has_attached_file :scan, :styles => { :text => { :quality => :better } },
+    has_attached_file :scan, :styles => { :text => { :quality => :better } },
-                           :processors => [:rotator, :ocr]
+                             :processors => [:rotator, :ocr]
 then both the :rotator processor and the :ocr processor would receive the
 options "{ :quality => :better }". This parameter may not mean anything to one
 or more or the processors, and they are expected to ignore it.
-NOTE: Because processors operate by turning the original attachment into the
+_NOTE: Because processors operate by turning the original attachment into the
-styles, no processors will be run if there are no styles defined.
+styles, no processors will be run if there are no styles defined._
-==Events
+Events
+------
 Before and after the Post Processing step, Paperclip calls back to the model
 with a few callbacks, allowing the model to change or cancel the processing
@@ -172,16 +177,18 @@ normal ActiveRecord callbacks as possible, so if you return false (specifically
 will halt. Returning false in an after_ filter will not halt anything, but you
 can access the model and the attachment if necessary.
-NOTE: Post processing will not even *start* if the attachment is not valid
+_NOTE: Post processing will not even *start* if the attachment is not valid
 according to the validations. Your callbacks and processors will *only* be
-called with valid attachments.
+called with valid attachments._
-==Testing
+Testing
+-------
 Paperclip provides rspec-compatible matchers for testing attachments. See the
 documentation on Paperclip::Shoulda::Matchers for more information.
-==Contributing
+Contributing
+------------
 If you'd like to contribute a feature or bugfix: Thanks! To make sure your
 fix/feature has a high chance of being included, please read the following
@@ -192,3 +199,17 @@ guidelines:
 2. Make sure there are tests! We will not accept any patch that is not tested.
   It's a rare time when explicit tests aren't needed. If you have questions
   about writing tests for paperclip, please ask the mailing list.
+Credits
+-------
+![thoughtbot](http://thoughtbot.com/images/tm/logo.png)
+Paperclip is maintained and funded by [thoughtbot, inc](http://thoughtbot.com/community)
+The names and logos for thoughtbot are trademarks of thoughtbot, inc.
+License
+-------
+Paperclip is Copyright © 2008-2011 thoughtbot. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.