shrine 3.0.1 → 3.1.0

data/doc/multiple_files.md

@@ -14,7 +14,7 @@ relationship with the main table, and files will be attached on the records in
 the new table. That way each record from the main table can implicitly have
 multiple attachments through the associated records.
 
-```plaintext
+```
 album1
   photo1
     - attachment1
@@ -74,13 +74,15 @@ Sequel.migration do
   change do
     create_table :albums do
       primary_key :id
-      column      :title, :text
+
+      String :title
     end
 
     create_table :photos do
       primary_key :id
       foreign_key :album_id, :albums
-      column      :image_data, :text
+
+      String :image_data
     end
   end
 end

data/doc/paperclip.md

@@ -6,7 +6,7 @@ This guide is aimed at helping Paperclip users transition to Shrine, and it
 consists of three parts:
 
 1. Explanation of the key differences in design between Paperclip and Shrine
-2. Instructions how to migrate and existing app that uses Paperclip to Shrine
+2. Instructions how to migrate an existing app that uses Paperclip to Shrine
 3. Extensive reference of Paperclip's interface with Shrine equivalents
 
 ## Overview
@@ -182,7 +182,7 @@ require "image_processing/mini_magick"
 class ImageUploader < Shrine
   plugin :derivatives
 
-  Attacher.derivatives_processor do |original|
+  Attacher.derivatives do |original|
     magick = ImageProcessing::MiniMagick.source(original)
 
     {
@@ -297,16 +297,21 @@ file.mime_type #=> "application/x-php"
 ## Migrating from Paperclip
 
 You have an existing app using Paperclip and you want to transfer it to Shrine.
-First we need to make new uploads write to the `<attachment>_data` column.
-Let's assume we have a `Photo` model with the "image" attachment:
+Let's assume we have a `Photo` model with the "image" attachment.
+
+### 1. Add Shrine column
+
+First we need to create the `image_data` column for Shrine:
 
 ```rb
 add_column :photos, :image_data, :text
 ```
 
-Afterwards we need to make new uploads write to the `image_data` column. This
-can be done by including the below module to all models that have Paperclip
-attachments:
+### 2. Dual write
+
+Next, we need to make new Paperclip attachments write to the `image_data`
+column. This can be done by including the below module to all models that have
+Paperclip attachments:
 
 ```rb
 require "shrine"
@@ -318,8 +323,7 @@ Shrine.storages = {
 
 Shrine.plugin :model
 Shrine.plugin :derivatives
-```
-```rb
+
 module PaperclipShrineSynchronization
   def self.included(model)
     model.before_save do
@@ -336,8 +340,8 @@ module PaperclipShrineSynchronization
     if attachment.size.present?
       attacher.set shrine_file(attachment)
 
-      attachment.styles.each do |name, style|
-        attacher.merge_derivatives(name => shrine_file(style))
+      attachment.styles.each do |style_name, style|
+        attacher.merge_derivatives(style_name => shrine_file(style))
       end
     else
       attacher.set nil
@@ -372,7 +376,7 @@ module PaperclipShrineSynchronization
   # If you'll be using a `:prefix` on your Shrine storage, or you're storing
   # files on the filesystem, make sure to subtract the appropriate part
   # from the path assigned to `:id`.
-  def style_to_shrine_data(style)
+  def shrine_style_file(style)
     Shrine.uploaded_file(
       storage:  :store,
       id:       style.attachment.path(style.name),
@@ -389,34 +393,35 @@ end
 ```
 
 After you deploy this code, the `image_data` column should now be successfully
-synchronized with new attachments.  Next step is to run a script which writes
-all existing Paperclip attachments to `image_data`:
+synchronized with new attachments.
+
+### 3. Data migration
+
+Next step is to run a script which writes all existing Paperclip attachments to
+`image_data`:
 
 ```rb
 Photo.find_each do |photo|
-  Paperclip::AttachmentRegistry.each_definition do |klass, name, options|
-    photo.write_shrine_data(name) if klass == Photo
-  end
+  photo.write_shrine_data(:image)
   photo.save!
 end
 ```
 
+### 4. Rewrite code
+
 Now you should be able to rewrite your application so that it uses Shrine
-instead of Paperclip, using equivalent Shrine storages. For help with
-translating the code from Paperclip to Shrine, you can consult the reference
-below.
+instead of Paperclip (you can consult the reference in the next section). You
+can remove the `PaperclipShrineSynchronization` module as well.
 
-You'll notice that Shrine metadata will be absent from the migrated files' data
-(specifically versions). You can run a script that will fill in any missing
-metadata defined in your Shrine uploader:
+### 5. Remove Paperclip columns
 
-```rb
-Shrine.plugin :refresh_metadata
+If everything is looking good, we can remove Paperclip columns:
 
-Photo.find_each do |photo|
-  photo.image_attacher.refresh_metadata!
-  photo.save
-end
+```rb
+remove_column :photos, :image_file_name
+remove_column :photos, :image_file_size
+remove_column :photos, :image_content_type
+remove_column :photos, :image_updated_at
 ```
 
 ## Paperclip to Shrine direct mapping
@@ -457,8 +462,8 @@ Processing is defined by using the `derivatives` plugin:
 class ImageUploader < Shrine
   plugin :derivatives
 
-  Attacher.derivatives_processor do |original|
-    magick = ImageProcessing::MiniMagick.source(image)
+  Attacher.derivatives do |original|
+    magick = ImageProcessing::MiniMagick.source(original)
 
     {
       large:  magick.resize_to_limit!(800, 800),
@@ -477,8 +482,8 @@ For default URLs you can use the `default_url` plugin:
 class ImageUploader < Shrine
   plugin :default_url
 
-  Attacher.default_url do |options|
-    "/attachments/#{name}/default.jpg"
+  Attacher.default_url do |derivative: nil, **|
+    "/images/placeholders/#{derivative || "original"}.jpg"
   end
 end
 ```
@@ -516,6 +521,60 @@ end
 
 Shrine has this functionality in the `determine_mime_type` plugin.
 
+### `validates_attachment`
+
+#### `:presence`
+
+For presence validation you can use your ORM's presence validator:
+
+```rb
+class Photo < ActiveRecord::Base
+  include ImageUploader::Attachment(:image)
+  validates_presence_of :image
+end
+```
+
+#### `:content_type`
+
+You can do MIME type validation with Shrine's `validation_helpers` plugin:
+
+```rb
+class ImageUploader < Shrine
+  plugin :validation_helpers
+
+  Attacher.validate do
+    validate_mime_type %w[image/jpeg image/png image/webp]
+  end
+end
+```
+
+Make sure to also load the `determine_mime_type` plugin to detect MIME type
+from file content.
+
+```rb
+# Gemfile
+gem "mimemagic"
+```
+```rb
+Shrine.plugin :determine_mime_type, analyzer: -> (io, analyzers) do
+  analyzers[:mimemagic].call(io) || analyzers[:file].call(io)
+end
+```
+
+#### `:size`
+
+You can do filesize validation with Shrine's `validation_helpers` plugin:
+
+```rb
+class ImageUploader < Shrine
+  plugin :validation_helpers
+
+  Attacher.validate do
+    validate_max_size 10*1024*1024
+  end
+end
+```
+
 ### `Paperclip::Attachment`
 
 This section explains the equivalent of Paperclip attachment's methods, in

data/doc/plugins/activerecord.md

@@ -158,7 +158,7 @@ end
 ```
 ```yml
 en:
-  activerecord
+  activerecord:
     errors:
       models:
         photo:

data/doc/plugins/data_uri.md

@@ -123,7 +123,7 @@ payload:
 
 A default log subscriber is added as well which logs these events:
 
-```plaintext
+```
 Data URI (5ms) – {:uploader=>Shrine}
 ```
 
@@ -134,7 +134,7 @@ plugin :data_uri, log_subscriber: -> (event) {
   Shrine.logger.info JSON.generate(name: event.name, duration: event.duration, uploader: event[:uploader])
 }
 ```
-```plaintext
+```
 {"name":"data_uri","duration":5,"uploader":"Shrine"}
 ```
 

data/doc/plugins/derivation_endpoint.md

@@ -68,7 +68,7 @@ generates an URL consisting of the configured [path prefix](#prefix),
 derivation name and arguments, serialized uploaded file, and an URL signature
 generated using the configured secret key:
 
-```plaintext
+```
 /  derivations/image  /  thumbnail  /  600/400  /  eyJmZvbyIb3JhZ2UiOiJzdG9yZSJ9  ?  signature=...
   └──── prefix ─────┘  └── name ──┘  └─ args ─┘  └─── serialized source file ───┘
 ```
@@ -197,7 +197,8 @@ Rails.application.routes.draw do
     end
   end
 end
-
+```
+```rb
 # app/controllers/photos_controller.rb
 class PhotosController < ApplicationController
   def thumbnail
@@ -483,32 +484,27 @@ such as AWS S3 or Google Cloud Storage.
 ### Deleting derivatives
 
 When the original attachment is deleted, its uploaded derivatives will not be
-automatically deleted, you will need to do the deletion manually. To ensure
-this gets called both on destroying and replacing, you can add that code to
-`Attacher#destroy`.
+automatically deleted, you will need to do the deletion manually. If you're
+using [backgrounding], you can do this in your `DestroyJob`.
 
-The easiest way is to delete the directory containing your derivatives:
+If your storage implements `#delete_prefixed`, and you're using the default
+[`:upload_location`](#upload-location), you can delete the directory containing
+derivatives:
 
 ```rb
-class ImageUploader < Shrine
-  class Attacher
-    def destroy(*args)
-      super
+class DestroyJob < ActiveJob::Base
+  def perform(attacher_class, data)
+    # ... destroy attached file ...
 
-      derivatives_directory = file.id
-      storage               = store.storage
+    derivatives_directory = attacher.file.id + "/"
+    storage               = attacher.store.storage
 
-      storage.delete_prefixed(derivatives_directory)
-    end
+    storage.delete_prefixed(derivatives_directory)
   end
 end
 ```
 
-This is under the assumption that your storage implements `#delete_prefixed`
-and that you're using default [`:upload_location`](#upload-location).
-
-Alternatively, you can delete each derivative individually using
-`Derivation#delete`:
+Alternatively, you can delete each derivative individually:
 
 ```rb
 class ImageUploader < Shrine
@@ -518,14 +514,15 @@ class ImageUploader < Shrine
     [:thumbnail, 400, 300],
     ...
   ]
+end
+```
+```rb
+class DestroyJob < ActiveJob::Base
+  def perform(attacher_class, data)
+    # ... destroy attached file ...
 
-  class Attacher
-    def destroy(*args)
-      super
-
-      DERIVATIONS.each do |args|
-        file.derivation(*args).delete
-      end
+    attacher.shrine_class::DERIVATIONS.each do |args|
+      attacher.file.derivation(*args).delete
     end
   end
 end
@@ -830,7 +827,7 @@ following payload:
 
 A default log subscriber is added as well which logs these events:
 
-```plaintext
+```
 Derivation (492ms) – {:name=>:thumbnail, :args=>[600, 600], :uploader=>Shrine}
 ```
 
@@ -846,7 +843,7 @@ plugin :derivation_endpoint, log_subscriber: -> (event) {
   )
 }
 ```
-```plaintext
+```
 {"name":"derivation","duration":492,"name":"thumbnail","args":[600,600],"uploader":"Shrine"}
 ```
 
@@ -861,3 +858,4 @@ plugin :derivation_endpoint, log_subscriber: nil
 [`Content-Type`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
 [`Content-Disposition`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition
 [`Cache-Control`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control
+[backgrounding]: https://shrinerb.com/docs/plugins/backgrounding

data/doc/plugins/derivatives.md

@@ -10,12 +10,11 @@ main attachment data in the same record attribute.
 Shrine.plugin :derivatives
 ```
 
-## Creating derivatives
+## Quick start
 
-When you have a file attached, you can generate derivatives from it and save
-them alongside the attached file. The simplest way to do this is to define a
-processor which returns the processed files, and then trigger it when you want
-to create derivatives.
+You'll usually want to create derivatives from an attached file. The simplest
+way to do this is to define a processor which returns the processed files, and
+then trigger it when you want to create derivatives.
 
 Here is an example of generating image thumbnails:
 
@@ -27,7 +26,7 @@ gem "image_processing", "~> 1.8"
 require "image_processing/mini_magick"
 
 class ImageUploader < Shrine
-  Attacher.derivatives_processor do |original|
+  Attacher.derivatives do |original|
     magick = ImageProcessing::MiniMagick.source(original)
 
     {
@@ -56,8 +55,17 @@ route make sure to create derivatives for new attachments:
 photo.image_derivatives! if photo.image_changed?
 ```
 
-Once derivatives have been created, their data is stored in the `#<name>_data`
-record attribute alongside the main file data:
+You can then retrieve created derivatives as follows:
+
+```rb
+photo.image(:large)           #=> #<Shrine::UploadedFile ...>
+photo.image(:large).url       #=> "https://s3.amazonaws.com/path/to/large.jpg"
+photo.image(:large).size      #=> 43843
+photo.image(:large).mime_type #=> "image/jpeg"
+```
+
+The derivatives data is stored in the `#<name>_data` record attribute, alongside
+the main file data:
 
 ```rb
 photo.image_data #=>
@@ -73,22 +81,112 @@ photo.image_data #=>
 # }
 ```
 
-You can then retrieve derivatives as follows:
+## Retrieving derivatives
+
+The list of stored derivatives can be retrieved with `#<name>_derivatives`:
 
 ```rb
-photo.image(:large)           #=> #<Shrine::UploadedFile>
-photo.image(:large).url       #=> "https://s3.amazonaws.com/path/to/large.jpg"
-photo.image(:large).size      #=> 43843
-photo.image(:large).mime_type #=> "image/jpeg"
+photo.image_derivatives #=>
+# {
+#   small:  #<Shrine::UploadedFile ...>,
+#   medium: #<Shrine::UploadedFile ...>,
+#   large:  #<Shrine::UploadedFile ...>,
+# }
+```
+
+A specific derivative can be retrieved in any of the following ways:
+
+```rb
+photo.image_derivatives[:small] #=> #<Shrine::UploadedFile ...>
+photo.image_derivatives(:small) #=> #<Shrine::UploadedFile ...>
+photo.image(:small)             #=> #<Shrine::UploadedFile ...>
+```
+
+Or with nested derivatives:
+
+```rb
+photo.image_derivatives #=> { thumbnail: { small: ..., medium: ..., large: ... } }
+
+photo.image_derivatives.dig(:thumbnail, :small) #=> #<Shrine::UploadedFile ...>
+photo.image_derivatives(:thumbnail, :small)     #=> #<Shrine::UploadedFile ...>
+photo.image(:thumbnails, :small)                #=> #<Shrine::UploadedFile ...>
+```
+
+### Derivative URL
+
+You can retrieve the URL of a derivative URL with `#<name>_url`:
+
+```rb
+photo.image_url(:small)  #=> "https://example.com/small.jpg"
+photo.image_url(:medium) #=> "https://example.com/medium.jpg"
+photo.image_url(:large)  #=> "https://example.com/large.jpg"
+```
+
+For nested derivatives you can pass multiple keys:
+
+```rb
+photo.image_derivatives #=> { thumbnail: { small: ..., medium: ..., large: ... } }
+
+photo.image_url(:thumbnail, :medium) #=> "https://example.com/medium.jpg"
+```
+
+By default, `#<name>_url` method will return `nil` if derivative is not found.
+You can use the [`default_url`][default_url] plugin to set up URL fallbacks:
+
+```rb
+Attacher.default_url do |derivative: nil, **|
+  "https://my-app.com/fallbacks/#{derivative}.jpg" if derivative
+end
+```
+```rb
+photo.image_url(:medium) #=> "https://example.com/fallbacks.com/medium.jpg"
 ```
 
-The `#<name>_derivatives!` model method delegates to
-`Attacher#create_derivatives`, which you can use if you're using
-`Shrine::Attacher` directly:
+Any additional URL options passed to `#<name>_url` will be forwarded to the
+storage:
+
+```rb
+photo.image_url(:small, response_content_disposition: "attachment")
+```
+
+You can also retrieve the derivative URL via `UploadedFile#url`:
+
+```rb
+photo.image_derivatives[:large].url
+```
+
+## Attacher API
+
+The derivatives API is primarily defined on the `Shrine::Attacher` class, with
+some important methods also being exposed through the `Shrine::Attachment`
+module.
+
+Here is a model example with equivalent attacher code:
+
+```rb
+photo.image_derivatives!(:thumbnails)
+photo.image_derivatives #=> { ... }
+
+photo.image_url(:large) #=> "https://..."
+photo.image(:large)     #=> #<Shrine::UploadedFile ...>
+```
+```rb
+attacher.create_derivatives(:thumbnails)
+attacher.get_derivatives #=> { ... }
+
+attacher.url(:large) #=> "https://..."
+attacher.get(:large) #=> "#<Shrine::UploadedFile>"
+```
+
+## Creating derivatives
+
+By default, the `Attacher#create_derivatives` method downloads the attached
+file, calls the processor, uploads results to attacher's permanent storage, and
+saves uploaded files on the attacher.
 
 ```rb
 attacher.file               #=> #<Shrine::UploadedFile id="original.jpg" storage=:store ...>
-attacher.create_derivatives # calls registered processor and uploads results
+attacher.create_derivatives # calls default processor and uploads results
 attacher.derivatives        #=>
 # {
 #   small:  #<Shrine::UploadedFile id="small.jpg" storage=:store ...>,
@@ -97,9 +195,7 @@ attacher.derivatives        #=>
 # }
 ```
 
-By default, the `Attacher#create_derivatives` method downloads the attached
-file, calls the processor, uploads results to attacher's permanent storage, and
-saves uploaded files on the attacher. Any additional arguments are forwarded to
+Any additional arguments are forwarded to
 [`Attacher#process_derivatives`](#processing-derivatives):
 
 ```rb
@@ -110,32 +206,43 @@ attacher.create_derivatives(foo: "bar")       # pass custom options to the proce
 ### Naming processors
 
 If you want to have multiple processors for an uploader, you can assign each
-processor a name. Then when creating derivatives you can specify the name of
-the desired processor.
+processor a name:
 
 ```rb
 class ImageUploader < Shrine
-  Attacher.derivatives_processor :thumbnails do |original|
-    # ...
+  Attacher.derivatives :thumbnails do |original|
+    { large: ..., medium: ..., small: ... }
   end
 
-  Attacher.derivatives_processor :crop do |original|
-    # ...
+  Attacher.derivatives :crop do |original|
+    { cropped: ... }
   end
-
-  # ...
 end
 ```
+
+Then when creating derivatives you can specify the name of the desired
+processor. New derivatives will be merged with any existing ones.
+
 ```rb
-photo.image_derivatives!(:thumbnails)
-# or
 attacher.create_derivatives(:thumbnails)
+attacher.derivatives #=> { large: ..., medium: ..., small: ... }
+
+attacher.create_derivatives(:crop)
+attacher.derivatives #=> { large: ..., medium: ..., small: ..., cropped: ... }
 ```
 
 ### Derivatives storage
 
 By default, derivatives are uploaded to the permanent storage of the attacher.
-You can change the default destination storage with the `:storage` plugin
+You can change the destination storage by passing `:storage` to the creation
+call:
+
+```rb
+attacher.create_derivatives(storage: :cache) # will be promoted together with main file
+attacher.create_derivatives(storage: :other_store)
+```
+
+You can also change the default destination storage with the `:storage` plugin
 option:
 
 ```rb
@@ -186,7 +293,7 @@ Derivatives can be nested to any level, using both hashes and arrays, but the
 top-level object must be a hash.
 
 ```rb
-Attacher.derivatives_processor :tiff do |original|
+Attacher.derivatives :tiff do |original|
   {
     thumbnail: {
       small:  small,
@@ -201,114 +308,29 @@ Attacher.derivatives_processor :tiff do |original|
   }
 end
 ```
-
-## Retrieving derivatives
-
-If you're using the `Shrine::Attachment` module, you can retrieve stored
-derivatives by calling `#<name>_derivatives` on your model/entity.
-
-```rb
-class Photo < Model(:image_data)
-  include ImageUploader::Attachment(:image)
-end
-```
-```rb
-photo.image_derivatives #=>
-# {
-#   small:  #<Shrine::UploadedFile>,
-#   medium: #<Shrine::UploadedFile>,
-#   large:  #<Shrine::UploadedFile>,
-# }
-```
-
-A specific derivative can be retrieved in any of the following ways:
-
-```rb
-photo.image_derivatives[:small] #=> #<Shrine::UploadedFile>
-photo.image_derivatives(:small) #=> #<Shrine::UploadedFile>
-photo.image(:small)             #=> #<Shrine::UploadedFile>
-```
-
-And with nested derivatives:
-
-```rb
-photo.image_derivatives #=> { thumbnail: { small: ..., medium: ..., large: ... } }
-
-photo.image_derivatives.dig(:thumbnail, :small) #=> #<Shrine::UploadedFile>
-photo.image_derivatives(:thumbnail, :small)     #=> #<Shrine::UploadedFile>
-photo.image(:thumbnails, :small)                #=> #<Shrine::UploadedFile>
-```
-
-When using `Shrine::Attacher` directly, you can retrieve derivatives using
-`Attacher#derivatives`:
-
 ```rb
 attacher.derivatives #=>
 # {
-#   small:  #<Shrine::UploadedFile>,
-#   medium: #<Shrine::UploadedFile>,
-#   large:  #<Shrine::UploadedFile>,
+#   thumbnail: {
+#     small:  #<Shrine::UploadedFile ...>,
+#     medium: #<Shrine::UploadedFile ...>,
+#     large:  #<Shrine::UploadedFile ...>,
+#   },
+#   layers: [
+#     #<Shrine::UploadedFile ...>,
+#     #<Shrine::UploadedFile ...>,
+#     # ...
+#   ]
 # }
 ```
 
-## Derivative URL
-
-If you're using the `Shrine::Attachment` module, you can use the `#<name>_url`
-method to retrieve the URL of a derivative.
-
-```rb
-class Photo < Model(:image_data)
-  include ImageUploader::Attachment(:image)
-end
-```
-```rb
-photo.image_url(:small)  #=> "https://example.com/small.jpg"
-photo.image_url(:medium) #=> "https://example.com/medium.jpg"
-photo.image_url(:large)  #=> "https://example.com/large.jpg"
-```
-
-For nested derivatives you can pass multiple keys:
-
-```rb
-photo.image_derivatives #=> { thumbnail: { small: ..., medium: ..., large: ... } }
-
-photo.image_url(:thumbnail, :medium) #=> "https://example.com/medium.jpg"
-```
-
-By default, `#<name>_url` method will return `nil` if derivative is not found.
-You can use the [`default_url`][default_url] plugin to set up URL fallbacks:
-
-```rb
-Attacher.default_url do |derivative: nil, **|
-  "https://my-app.com/fallbacks/#{derivative}.jpg" if derivative
-end
-```
-```rb
-photo.image_url(:medium) #=> "https://example.com/fallbacks.com/medium.jpg"
-```
-
-Any additional URL options passed to `#<name>_url` will be forwarded to the
-storage:
-
-```rb
-photo.image_url(:small, response_content_disposition: "attachment")
-```
-
-You can also retrieve the derivative URL via `UploadedFile#url`:
-
-```rb
-photo.image_derivatives[:large].url
-# or
-attacher.derivatives[:large].url
-```
-
 ## Processing derivatives
 
 A derivatives processor block takes the original file, and is expected to
 return a hash of processed files (it can be [nested](#nesting-derivatives)).
 
 ```rb
-Attacher.derivatives_processor :my_processor do |original|
+Attacher.derivatives :my_processor do |original|
   # return a hash of processed files
 end
 ```
@@ -327,7 +349,7 @@ The processor block is evaluated in context of the `Shrine::Attacher` instance,
 which allows you to change your processing logic based on the record data.
 
 ```rb
-Attacher.derivatives_processor :my_processor do |original|
+Attacher.derivatives :my_processor do |original|
   self    #=> #<Shrine::Attacher>
 
   record  #=> #<Photo>
@@ -345,7 +367,7 @@ forwarded to the processor:
 attacher.process_derivatives(:my_processor, foo: "bar")
 ```
 ```rb
-Attacher.derivatives_processor :my_processor do |original, **options|
+Attacher.derivatives :my_processor do |original, **options|
   options #=> { :foo => "bar" }
   # ...
 end
@@ -357,7 +379,7 @@ By default, the `Attacher#process_derivatives` method will download the
 attached file and pass it to the processor:
 
 ```rb
-Attacher.derivatives_processor :my_processor do |original|
+Attacher.derivatives :my_processor do |original|
   original #=> #<File:...>
   # ...
 end
@@ -366,12 +388,22 @@ end
 attacher.process_derivatives(:my_processor) # downloads attached file and passes it to the processor
 ```
 
-If you want to use a different source file, or if you're calling multiple
-processors in a row and want to avoid re-downloading the same source file each
-time, you can pass the source file as the second argument:
+If you want to use a different source file, you can pass it in to the process
+call. Typically you'd pass a local file on disk. If you pass a
+`Shrine::UploadedFile` object, it will be automatically downloaded to disk.
+
+```rb
+# named processor:
+attacher.process_derivatives(:my_processor, source_file)
+
+# default processor:
+attacher.process_derivatives(source_file)
+```
+
+If you want to call multiple processors in a row with the same source file, you
+can use this to avoid re-downloading the same source file each time:
 
 ```rb
-# this way the source file is downloaded only once
 attacher.file.download do |original|
   attacher.process_derivatives(:thumbnails, original)
   attacher.process_derivatives(:colors,     original)
@@ -479,9 +511,7 @@ attacher.upload_derivative :thumb, thumbnail_file,
   location: "path/to/derivative"
 ```
 
-A `:derivative` option is automatically passed to the uploader and holds the
-name of the derivative, which you can use when extracting metadata, generating
-location or generating upload options:
+The `:derivative` name is automatically passed to the uploader:
 
 ```rb
 class MyUploader < Shrine
@@ -510,8 +540,6 @@ If you want to disable this behaviour, pass `delete: false`:
 
 ```rb
 attacher.upload_derivative(:thumb, thumbnail_file, delete: false)
-
-File.exist?(thumbnail_file.path) #=> true
 ```
 
 ## Merging derivatives
@@ -736,7 +764,7 @@ following payload:
 
 A default log subscriber is added as well which logs these events:
 
-```plaintext
+```
 Derivatives (2133ms) – {:processor=>:thumbnails, :processor_options=>{}, :uploader=>ImageUploader}
 ```
 
@@ -747,7 +775,7 @@ plugin :derivatives, log_subscriber: -> (event) {
   Shrine.logger.info JSON.generate(name: event.name, duration: event.duration, **event.payload)
 }
 ```
-```plaintext
+```
 {"name":"derivatives","duration":2133,"processor":"thumbnails","processor_options":{},"uploader":"ImageUploader"}
 ```