cmassimo-friendly_id 3.0.4.2

data/Changelog.md

@@ -0,0 +1,277 @@
+# FriendlyId Changelog
+
+We would like to think our many {file:Contributors contributors} for
+suggestions, ideas and improvements to FriendlyId.
+
+* Table of Contents
+{:toc}
+
+## 3.0.4 (2010-04-27)
+
+* Fixed backwards-compatiblity with ActiveSupport 2.3.4 (Thanks Juergen Fesslmeier).
+
+## 3.0.3 (2010-04-26)
+
+* Fixed scope update when models use polymorphic relations.
+
+## 3.0.2 (2010-04-09)
+
+* Fixed finding non-slugged models by an array of ids.
+* Added backported `tidy_bytes` implementation from [utf8_utils](http://github.com/norman/utf8_utils)
+* Removed dependency on Rubygems 1.3.6; this blocked deploy on Heroku (thanks Steven Noble)
+* Replaced File.dirname calls with File.expand_path, which should allow compatibility with Ruby 1.9.2
+* Cleanups and some improvements to tests.
+
+## 3.0.1 (2010-03-30)
+
+* Fixed bad path in Rails 2.x generator.
+
+## 3.0.0 (2010-03-30)
+
+* Rails 3 support.
+* Removed features deprecated in FriendlyId 2.3.
+* Fixed searching by numeric friendly_id in non-slugged models.
+* Added `:allow_nil` config option (Andre Duffeck and Norman Clarke)
+
+## 2.3.4 (2010-03-22)
+
+* Made slugged status use the slug sequence. This fixes problems with #best?
+  returning false when finding with a sequenced slug.
+* Doc fixes. (Juan Schiwndt)
+* Misc cleanups.
+
+## 2.3.3 (2010-03-10)
+
+* Fixed sequence regexp to grab all trailing digits. (Nash Kabbara)
+* Block param now warns, not raises. (Kamal Fariz Mahyuddin)
+* Misc doc fixes. (Kamal Fariz Mahyuddin)
+
+## 2.3.2 (2010-02-14)
+
+* Fixed finding by old slug when using cached slugs.
+* Sequence separator parsing now correctly handles occurrences of the sequence
+  separator string inside the friendly_id text (Johan Kok).
+* Fixed missing quotes on table names in a few places (Brian Collins).
+
+
+## 2.3.1 (2010-02-09)
+
+* Fixed stack level too deep error on #strip_diacritics.
+
+
+## 2.3.0 (2010-02-04)
+
+This is a major update à la "Snow Leopard" that adds no new major features,
+but significantly improves the underlying code. Most users should be able to
+upgrade with no issues other than new deprecation messages appearing in the
+logs.
+
+If, however, you have monkey-patched FriendlyId, or are maintaining your own
+fork, then this upgrade may causes issues.
+
+**Changes:**
+
+* Sequence separator can now be configured to something other than "--".
+* New option to pass arguments to {FriendlyId::SlugString#approximate_ascii!},
+  allowing custom approximations specific to German or Spanish.
+* FriendlyId now queries against the cached_slug column, which improves performance.
+* {FriendlyId::SlugString} class added, allowing finer-grained control over
+  Unicode friendly_id strings.
+* {FriendlyId::Configuration} class added, offering more flexible/hackable
+  options.
+* FriendlyId now raises subclasses of {FriendlyId::SlugGenerationError}
+  depending on the error context.
+* Simple models now correctly validate friendly_id length.
+* Passing block into FriendlyId deprecated in favor of overriding
+  the model's `normalize_friendly_id` method.
+* Updating only the model's scope now also updates the slug.
+* Major refactorings, cleanups and deprecations en route to the 3.0 release.
+
+## 2.2.7 (2009-12-16)
+
+* Fixed typo in Rake tasks which caused delete_old_slugs to fail. (Diego R.V.)
+
+## 2.2.6 (2009-12-10)
+
+* Made cached_slug automagic configuration occur outside of has_friendly_id.
+  This was causing problems in code where the class is loaded before
+  ActiveRecord has established its connection.
+* Fixes for scope feature with Postgres (Ben Woosley)
+* Migrated away from Hoe/Newgem for gem management.
+* Made tests database-agnostic (Ben Woosley)
+
+## 2.2.5 (2009-11-30)
+
+* Fixed typo in config options (Steven Noble).
+
+## 2.2.4 (2009-11-12)
+
+* Fixed typo in post-install message.
+
+## 2.2.3 (2009-11-12)
+
+* Fixed some issues with gem load order under 1.8.x (closes GH Issue #20)
+* Made sure friendly_id generator makes a lib/tasks directory (Josh Nichols)
+* Finders now accept instances of ActiveRecord::Base, matching AR's behavior
+  (Josh Nichols)
+* SlugGenerationError now raise when a blank value is passed to
+  strip_diacritics
+
+## 2.2.2 (2009-10-26)
+
+* Fixed Rake tasks creating duplicate slugs and not properly clearing cached
+  slugs (closes GH issues #14 and #15)
+
+## 2.2.1 (2009-10-23)
+
+* slug cache now properly caches the slug sequence (closes GH issue #10)
+* attr_protected is now only invoked on the cached_slug column if
+  attr_accessible has not already been invoked. (closes GH issue #11)
+
+## 2.2.0 (2009-10-19)
+
+* Added slug caching, offers huge performance boost (Bruno Michel)
+* Handle Unicode string length correctly (Mikhail Shirkov)
+* Remove alias_method_chain in favor of super (Diego Carrion)
+
+## 2.1.4 (2009-09-01)
+
+* Fixed upgrade generator not installing rake tasks (Harry Love)
+* Fixed handling of very large id's (Nathan Phelps)
+* Fixed long index name on migration (Rob Ingram)
+
+## 2.1.3 (2009-06-03)
+
+* Always call #to_s on slug_text to allow objects such as DateTimes to be used
+  for the friendly_id text. (reported by Jon Ng)
+
+## 2.1.2 (2009-05-21)
+
+* Non-slugged models now validate the friendly_id on save as well as create
+  (Joe Van Dyk).
+* Replaced Shoulda with Contest.
+
+## 2.1.1 (2009-03-25)
+
+* Fixed bug with find_some; if a record has old slugs, find_some will no
+  longer return multiple copies of that record when finding by numerical ID.
+  (Steve Luscher)
+* Fixed bug with find_some: you can now find_some with an array of numerical
+  IDs without an error being thrown. (Steve Luscher)
+
+## 2.1.0 (2009-03-25)
+
+* Ruby 1.9 compatibility.
+* Removed dependency on ancient Unicode gem.
+
+## 2.0.4 (2009-02-12)
+
+* You can now pass in your own custom slug generation blocks while setting up
+  friendly_id.
+
+## 2.0.3 (2009-02-11)
+
+* Fixed to_param returning an empty string for non-slugged models with a null
+  friendly_id.
+
+## 2.0.2 (2009-02-09)
+
+* Made FriendlyId depend only on ActiveRecord. It should now be possible to
+  use FriendlyId with Camping or any other codebase that uses AR.
+* Overhauled creaky testing setup and switched to Shoulda.
+* Made reserved words work for non-slugged models.
+
+## 2.0.1 (2009-01-19)
+
+* Fix infinite redirect bug when using .has_better_id? in your controllers
+  (Sean Abrahams)
+
+
+## 2.0.0 (2009-01-03)
+
+* Support for scoped slugs (Norman Clarke)
+* Support for UTF-8 friendly_ids (Norman Clarke)
+* Can now be installed via Ruby Gems, or as a Rails plugin (Norman Clarke)
+* Improved handling of non-unique slugs (Norman Clarke and Adrian Mugnolo)
+* Shoulda macro (Josh Nichols)
+* Various small bugfixes, cleanups and refactorings
+
+## 1.0 (2008-12-11)
+
+* Fixed bug that may return invalid records having similar id/names and using
+  MySQL. (Emilio Tagua)
+* Fixed slug generation to increment only numeric extension without modifying
+  the name on duplicated slugs. (Emilio Tagua)
+
+## 2008-10-31
+
+* Fixed compatibility with Rails 2.0.x. (Norman Clarke)
+* friendly_id::make_slugs update records in chunks of 1000 to avoid running
+  out of memory with large datasets. (Tim Kadom)
+* Fixed logic error with slug name collisions. Thanks to Tim Kadom for
+  reporting this bug.
+
+## 2008-10-22
+
+* Reverted use of UTF8Handler - was causing errors for some people (Bence Nagy)
+* Corrected find in case if a friendly_id begins with number (Bence Nagy)
+* Added ability to reserve words from slugs (Adam Cigánek)
+
+## 2008-10-09
+
+* Moved "require"" for iconv to init.rb (Florian Aßmann)
+* Removed "require" for Unicode, use Rails' handler instead (Florian Aßmann)
+* Replaced some magic numbers with constants (Florian Aßmann)
+* Don't overwrite find, alias_method_chain find_one and find_some instead
+  (Florian Aßmann)
+* Slugs behave more like ids now (Florian Aßmann)
+* Can find by mixture of ids and slugs (Florian Aßmann)
+* Reformatted code and comments (Florian Aßmann)
+* Added support for Edge Rails' Inflector::parameterize (Norman Clarke)
+
+## 0.5 (2008-08-25)
+
+* Moved strip_diacritics into Slug for easier reuse/better organization.
+* Put class methods inside class << self block. (Norman Clarke)
+
+* Small change to allow friendly_id to work better with STI. (David Ramalho)
+
+## 2008-07-14
+
+* Improved slug generation for friendly id's with apostrophes. (Alistair Holt)
+* Added support for namespaced models in Rakefile. (David Ramalho)
+
+## 2008-06-23
+
+* Cached most recent slug to improve performance (Emilio Tagua).
+
+## 2008-06-10
+
+* Added ability to find friendly_ids by array (Emilio Tagua)
+
+## 2008-05-15
+
+* Made friendly_id raise an error if slug method returns a blank value.
+
+## 2008-05-12
+
+* Added experimental Github gemspec.
+
+## 2008-04-18
+
+* Improved slug name collision avoidance.
+
+## 2008-03-13
+
+* Added :dependent => :destroy to slug relation, as suggested by Emilio Tagua.
+* Fixed error when renaming a slugged item back to a previously used name.
+* Incorporated documentation changes suggested by Jesse Crouch and Chris Nolan.
+
+## 2008-02-07
+
+* Applied patches from blog commenter "suntzu" to fix problem with model
+  values were being overwritten.
+* Applied patch from Dan Blue to make friendly_id no longer ignore options on
+  ActiveRecordBase#find.
+* Added call to options.assert_valid_keys in has_friendly_id. Thanks to W.
+  Andrew Loe III for pointing out that this was missing.

data/Contributors.md

@@ -0,0 +1,39 @@
+We are grateful for many contributions from the Ruby and Rails
+community, in particular from the following people:
+
+* Adam Cigánek
+* Alexander Gräfe
+* Alistair Holt
+* Andre Duffeck
+* Andrew Loe III
+* Ben Woosley
+* Bence Nagy
+* Brian Collins
+* Bruno Michel
+* Chris Nolan
+* David Ramalho
+* Diego Carrion
+* Diego R. V.
+* Eric Lindvall
+* Florian Aßmanqn
+* Harry Love
+* Ian Stewart
+* Jesse Crouch
+* Joe Van Dyk
+* Johan Kok
+* Josh Nichols
+* Juan Schwindt
+* Kamal Fariz Mahyuddin
+* Laurence A. Lee
+* Louis T.
+* Mikhail Shirkov
+* Nash Kabbara
+* Nathan Phelps
+* Ramon Soares
+* Rdavila
+* Rob Ingram
+* Ryan Wood
+* Sean Abrahams
+* Steve Luscher
+* Steven Noble
+* Tim Kadom

data/Guide.md

@@ -0,0 +1,561 @@
+# FriendlyId Guide
+
+* Table of Contents
+{:toc}
+
+## Overview
+
+FriendlyId is a Ruby gem which allows you to work with human-friendly strings
+as if they were numeric ids for ActiveRecord models. This facilitates replacing
+"unfriendly" URL's like
+
+    http://example.com/states/4323454
+
+with "friendly" ones such as:
+
+    http://example.com/states/washington
+
+## Simple Models
+
+The simplest way to use FriendlyId is with a model that has a uniquely indexed
+column with no spaces or special characters, and that is seldom or never
+updated. The most common example of this is a user name or login column:
+
+    class User < ActiveRecord::Base
+      validates_format_of :login, :with => /\A[a-z0-9]+\z/i
+      has_friendly_id :login
+    end
+
+    @user = User.find "joe"   # the old User.find(1) still works, too
+    @user.to_param            # returns "joe"
+    redirect_to @user         # the URL will be /users/joe
+
+In this case, FriendlyId assumes you want to use the column as-is; FriendlyId
+will never modify the value of the column, and your application must ensure
+that the value is admissible in a URL:
+
+    class City < ActiveRecord::Base
+      has_friendly_id :name
+    end
+
+    @city.find "Viña del Mar"
+    redirect_to @city # the URL will be /cities/Viña%20del%20Mar
+
+For this reason, it is often more convenient to use Slugs rather than a single
+column.
+
+## Slugged Models
+
+FriendlyId uses a separate table to store slugs for models which require some
+processing of the friendly_id text. The most common example is a blog post's
+title, which may have spaces, uppercase characters, or other attributes you
+wish to modify to make them more suitable for use in URL's.
+
+    class Post < ActiveRecord::Base
+      has_friendly_id :title, :use_slug => true
+    end
+
+    @post = Post.create(:title => "This is the first post!")
+    @post.friendly_id   # returns "this-is-the-first-post"
+    redirect_to @post   # the URL will be /posts/this-is-the-first-post
+
+If you are unsure whether to use slugs, then your best bet is to use them,
+because FriendlyId provides many useful features that only work with slugs.
+These features are explained in detail {file:Guide.md#features below}.
+
+## Installation
+
+FriendlyId can be installed as a gem, or as a Rails plugin. It is compatible
+with Rails 2.2.x, 2.3.x. and 3.0.
+
+### As a Gem
+
+    gem install friendly_id
+
+#### Rails 2.2.x - 2.3.x
+
+After installing the gem, add an entry in environment.rb:
+
+    config.gem "friendly_id", :version => "~> 2.3"
+
+### Rails 3.0
+
+After installing the gem, add an entry in the Gemfile:
+
+    gem "friendly_id", "~> 3.0"
+
+### As a Plugin
+
+Plugin installation is simple for all supported versions of Rails:
+
+    ./script/plugin install git://github.com/norman/friendly_id.git
+
+However, installing as a gem offers simpler version control than plugin
+installation. Whenever possible, install as a gem instead. Plugin support may
+eventually be removed in a future version.
+
+### Setup
+
+After installing either as a gem or plugin, run:
+
+    ./script/generate friendly_id
+    rake db:migrate
+
+This will install the Rake tasks and slug migration for FriendlyId. If you are
+not going to use slugs, you can do:
+
+    ./script/generate friendly_id --skip-migration
+
+FriendlyId is now set up and ready for you to use.
+
+## Configuration
+
+FriendlyId is configured in your model using the `has_friendly_id` method:
+
+    has_friendly_id :a_column_or_method options_hash
+
+    class Post < ActiveRecord::Base
+      # use the "title" column as the basis of the friendly_id, and use slugs
+      has_friendly_id :title, :use_slug => true,
+        # remove accents and other diacritics from Western characters
+        :approximate_ascii => true,
+        # don't use slugs longer than 50 chars
+        :max_length => 50
+    end
+
+Read on to learn about the various features that can be configured. For the
+full list of valid configuration options, see the instance attribute summary
+for {FriendlyId::Configuration}.
+
+# Features
+
+## FriendlyId Strings
+
+FriendlyId comes with {FriendlyId::SlugString excellent support for Unicode
+strings}. When using slugs, FriendlyId will automatically modify the slug text
+to make it more suitable for use in a URL:
+
+    class City < ActiveRecord::Base
+      has_friendly_id :name, :use_slug => true
+    end
+
+    @city.create :name => "Viña del Mar"
+    @city.friendly_id  # will be "viña-del-mar"
+
+By default, the string is {FriendlyId::SlugString#downcase! downcased} and
+{FriendlyId::SlugString#clean! stripped}, {FriendlyId::SlugString#with_dashes! spaces are replaced with dashes},
+and {FriendlyId::SlugString#word_chars! non-word characters are removed}.
+
+### Replacing Accented Characters
+
+If your strings use Western characters, you can use the `:approximate_ascii` option to remove
+accents and other diacritics:
+
+    class City < ActiveRecord::Base
+      has_friendly_id :name, :use_slug => true, :approximate_ascii => true
+    end
+
+    @city.create :name => "Łódź, Poland"
+    @city.friendly_id  # will be "lodz-poland"
+
+There are special options for some languages:
+
+### German Approximations
+
+    class Person < ActiveRecord::Base
+      has_friendly_id :name, :use_slug => true, :approximate_ascii => true,
+        :ascii_approximation_options => :german
+    end
+
+    @person.create :name => "Jürgen Müller"
+    @person.friendly_id  # will be "juergen-mueller"
+
+### Spanish Approximations
+
+    class Post < ActiveRecord::Base
+      has_friendly_id :title, :use_slug => true, :approximate_ascii => true,
+        :ascii_approximation_options => :spanish
+    end
+
+    @post.create(:title => "¡Feliz año!")
+    @post.title  # will be "feliz-anno"
+
+### Approximations for Other Languages
+
+You can add custom approximations for your language by adding Hash of
+approximations to {FriendlyId::SlugString::APPROXIMATIONS}. The approximations
+must be listed as Unicode decimal numbers, and arrays of numbers.
+
+### Unicode Slugs
+
+By default, any character outside the Unicode Western character sets will be
+passed through untouched, allowing you to have slugs in Arabic, Japanese,
+Greek, etc:
+
+    @post.create :title => "katakana: ゲコゴサザシジ!"
+    @post.friendly_id # will be: "katakana-ゲコゴサザシジ"
+
+### ASCII Slugs
+
+You can also configure FriendlyId using `:strip_non_ascii` to completely delete
+any non-ascii characters:
+
+    class Post < ActiveRecord::Base
+      has_friendly_id :title, :use_slug => true, :strip_non_ascii => true
+    end
+
+    @post.create :title => "katakana: ゲコゴサザシジ!"
+    @post.friendly_id # will be: "katakana"
+
+
+### Using a Custom Method to Generate the Slug Text
+
+FriendlyId can use either a column or a method to generate the slug text for
+your model:
+
+    class City < ActiveRecord::Base
+
+      belongs_to :country
+      has_friendly_id :name_and_country, :use_slug => true
+
+      def name_and_country
+        #{name} #{country.name}
+      end
+
+    end
+
+    @country = Country.create(:name => "Argentina")
+    @city = City.create(:name => "Buenos Aires", :country => @country)
+    @city.friendly_id # will be "buenos-aires-argentina"
+
+One word of caution: in the example above, if the country's name were updated,
+say, to "Argentine Republic", the city's friendly_id would not be
+automatically updated. For this reason, it's a good idea to avoid using
+frequently-updated relations as a part of the friendly_id.
+
+## Using a Custom Method to Process the Slug Text
+
+If the built-in slug text handling options don't work for your application,
+you can override the `normalize_friendly_id` method in your model class in
+order to fine-tune the output:
+
+    class City < ActiveRecord::Base
+
+      def normalize_friendly_id(text)
+        my_text_modifier_method(text)
+      end
+
+    end
+
+The normalize_friendly_id method takes a single argument and receives an
+instance of {FriendlyId::SlugString}, a class which wraps a regular Ruby
+string with some additional formatting options inherits Multibyte support from
+ActiveSupport::Multibyte::Chars.
+
+### Converting non-Western characters to ASCII with Stringex
+
+Stringex is a library which provides some interesting options for transliterating
+non-Western strings to ASCII:
+
+    "你好".to_url => "ni-hao"
+
+Using Stringex with FriendlyId is a simple matter of installing and requiring
+the `stringex` gem, and overriding the `normalize_friendly_id` method in your
+model:
+
+    class City < ActiveRecord::Base
+
+      def normalize_friendly_id(text)
+        text.to_url
+      end
+
+    end
+
+## Redirecting to the Current Friendly URL
+
+FriendlyId maintains a history of your record's older slugs, so if your
+record's friendly_id changes, your URL's won't break. It offers several
+methods to determine whether the model instance was found using the most
+recent friendly_id. This helps you redirect to your "unfriendly" URL's to your
+new "friendly" ones when adding FriendlyId to an existing application:
+
+    class PostsController < ApplicationController
+
+      before_filter ensure_current_post_url, :only => :show
+
+      ...
+
+      def ensure_current_post_url
+        redirect_to @post, :status => :moved_permanently unless @post.friendly_id_status.best?
+      end
+
+    end
+
+For more information, take a look at the documentation for {FriendlyId::Status}.
+
+## Non-unique Slugs
+
+FriendlyId will append a arbitrary number to the end of the id to keep it
+unique if necessary:
+
+    /posts/new-version-released
+    /posts/new-version-released--2
+    /posts/new-version-released--3
+    ...
+    etc.
+
+Note that the number is preceded by "--" to distinguish it from the
+rest of the slug. This is important to enable having slugs like:
+
+    /cars/peugeot-206
+    /cars/peugeot-206--2
+
+You can configure the separator string used by your model by setting the
+`:sequence_separator` option in `has_friendly_id`:
+
+    has_friendly_id :title, :use_slug => true, :sequence_separator => ";"
+
+You can also override the default used in
+{FriendlyId::Configuration::DEFAULTS} to set the value for any model using
+FriendlyId. If you change this value in an existing application, be sure to
+{file:Guide.md#regenerating_slugs regenerate the slugs} afterwards.
+
+## Reserved Words
+
+You can configure a list of strings as reserved so that, for example, you
+don't end up with this problem:
+
+    /users/joe-schmoe # A user chose "joe schmoe" as his user name - no worries.
+    /users/new        # A user chose "new" as his user name, and now no one can sign up.
+
+Reserved words are configured using the `:reserved_words` option:
+
+    class Restaurant < ActiveRecord::Base
+      belongs_to :city
+      has_friendly_id :name, :use_slug => true, :reserved_words => ["my", "values"]
+    end
+
+The strings "new" and "index" are reserved by default. When you attempt to
+store a reserved value, FriendlyId raises a
+{FriendlyId::ReservedError}. You can also override the default
+reserved words in {FriendlyId::Configuration::DEFAULTS} to set the value for any
+model using FriendlyId.
+
+## Caching the FriendlyId Slug for Better Performance
+
+Checking the slugs table all the time has an impact on performance, so as of
+2.2.0, FriendlyId offers slug caching.
+
+### Automatic setup
+
+To enable slug caching, simply add a column named "cached_slug" to your model.
+Is also advised to index this column for performance reason.
+FriendlyId will automatically use this column if it detects it:
+
+    class AddCachedSlugToUsers < ActiveRecord::Migration
+      def self.up
+        add_column :users, :cached_slug, :string
+        add_index  :users, :cached_slug
+      end
+
+      def self.down
+        remove_column :users, :cached_slug
+      end
+    end
+
+Then, redo the slugs:
+
+    rake friendly_id:redo_slugs MODEL=User
+
+FriendlyId will also query against the cache column if it's available, which
+can significantly improve the performance of many queries, particularly when
+passing an array of friendly ids to #find.
+
+A few warnings when using this feature:
+
+* *DO NOT* forget to redo the slugs, or else this feature will not work!
+* This feature uses `attr_protected` to protect the `cached_slug` column,
+  unless you have already invoked `attr_accessible`. If you wish to use
+  `attr_accessible`, you must invoke it BEFORE you invoke `has_friendly_id` in
+  your class.
+* FriendlyId can not query against the slug cache when you pass a :scope
+  argument to #find. Try to avoid passing an array of friendly id's and a
+  scope to #find, as this will result in weak performance.
+
+### Using a custom column name
+
+You can also use a different name for the column if you choose, via the
+`:cache_column` config option:
+
+    class User < ActiveRecord::Base
+      has_friendly_id :name, :use_slug => true, :cache_column => 'my_cached_slug'
+    end
+
+
+## Nil slugs and skipping validations
+
+You can choose to allow `nil` friendly_ids via the `:allow_nil` config option:
+
+    class User < ActiveRecord::Base
+      has_friendly_id :name, :allow_nil => true
+    end
+
+This works whether the model uses slugs or not.
+
+For slugged models, if the friendly_id text is `nil`, no slug will be created. This can be useful, for example, to only create slugs for published articles and avoid creating many slugs with sequences.
+
+For models that don't use slugs, this will make FriendlyId skip all its validations when the friendly_id text is `nil`. This can be useful, for example, if you wish to add the friendly_id value in an `:after_save` callback.
+
+For non-slugged models, if you simply wish to skip friendly_ids's validations
+for some reason, you can override the `skip_friendly_id_validations` method.
+Note that this method is **not** used by slugged models.
+
+## Scoped Slugs
+
+FriendlyId can generate unique slugs within a given scope. For example, assume
+you have an application that displays restaurants. Without scoped slugs, if
+two restaurants are named "Joe's Diner," the second one will end up with
+"joes-diner--2" as its friendly_id. Using scoped allows you to keep the
+slug names unique for each city, so that the second "Joe's Diner" could have
+the slug "joes-diner" if it's located in a different city:
+
+    class Restaurant < ActiveRecord::Base
+      belongs_to :city
+      has_friendly_id :name, :use_slug => true, :scope => :city
+    end
+
+    class City < ActiveRecord::Base
+      has_many :restaurants
+      has_friendly_id :name, :use_slug => true
+    end
+
+    http://example.org/cities/seattle/restaurants/joes-diner
+    http://example.org/cities/chicago/restaurants/joes-diner
+
+    Restaurant.find("joes-diner", :scope => "seattle")  # returns 1 record
+    Restaurant.find("joes-diner", :scope => "chicago")  # returns 1 record
+    Restaurant.find("joes-diner")                       # returns both records
+
+The value for the `:scope` key in your model can be a custom method you
+define, or the name of a relation. If it's the name of a relation, then the
+scope's text value will be the result of calling `to_param` on the related
+model record. In the example above, the city model also uses FriendlyId and so
+its `to_param` method returns its friendly_id: "chicago" or "seattle".
+
+### Updating a Relation's Scoped Slugs
+
+When using a relation as the scope, updating the relation will update the
+slugs, but only if both models have specified the relationship. In the above
+example, updates to City will update the slugs for Restaurant because City
+specifies that it `has_many :restaurants`.
+
+### Routes for Scoped Models
+
+Note that FriendlyId does not set up any routes for scoped models; you must
+do this yourself in your application. Here's an example of one way to set
+this up:
+
+    # in routes.rb
+    map.resources :restaurants
+    map.restaurant "/restaurants/:scope/:id", :controller => "restaurants"
+
+    # in views
+    link_to 'Show', restaurant_path(restaurant.city, restaurant)
+
+    # in controllers
+    @restaurant = Restaurant.find(params[:id], :scope => params[:scope])
+
+
+## FriendlyId Rake Tasks
+
+FriendlyId provides several tasks to help maintain your application.
+
+### Generating New Slugs For the First Time
+
+    friendly_id:make_slugs MODEL=<model name>
+
+Use this task to generate slugs after installing FriendlyId in a new
+application.
+
+### Regenerating Slugs
+
+    friendly_id:redo_slugs MODEL=<model name>
+
+Use this task to regenerate slugs after making any changes to your model's
+FriendlyId configuration options that affect slug generation. For example,
+if you introduce a `cached_slug` column or change the `:seqence_separator`.
+
+### Deleting Old Slugs
+
+    rake friendly_id:remove_old_slugs MODEL=<model name> DAYS=<days>
+
+Use this task if you wish to delete expired slugs; manually or perhaps via
+cron. If you don't specify the days option, the default is to remove unused
+slugs older than 45 days.
+
+# Misc tips
+
+## MySQL 5.0 or less
+
+Currently, the default FriendlyId migration will not work with MySQL 5.0 or less
+because it creates and index that's too large. The easiest way to work around
+this is to change the generated migration to add limits on some column lengths.
+Please see [this issue](http://github.com/norman/friendly_id/issues#issue/50) in
+the FriendlyId issue tracker for more information.
+
+# Hacking FriendlyId
+
+A couple of notes for programmers intending to work on FriendlyId:
+
+If you intend to send a pull request, in general it's best to make minor
+changes in the master branch, and major changes in the edge branch.
+
+Before removing any public or protected methods, FriendlyId will deprecate
+them through one major release cycle. Private methods may, however, change at
+any time.
+
+## Running the Tests
+
+FriendlyId uses [Bundler](http://github.com/carlhuda/bundler) to manage its gem
+dependencies. To run the tests, first make sure you have bundler installed.
+Then, copy Gemfile.default to Gemfile. If you wish to test against different gem
+versions than the ones specified in the Gemfile (for example, to test with
+Postgres or MySQL rather than SQLite3, or to test against different versions of
+ActiveRecord), then simply modify the Gemfile to suit your dependencies.
+
+## Some Benchmarks
+
+These benchmarks can give you an idea of FriendlyId's impact on the
+performance of your application. Of course your results may vary.
+
+Note that much of the performance difference can be attributed to finding an
+SQL record by a text column. Finding a single record by numeric primary key is
+always the fastest operation, and thus the best choice when possible. If you
+decide not to use FriendlyId for performance reasons, keep in mind that your
+own solution is unlikely to be any faster than FriendlyId with cached slugs
+enabled. But if it is, then your patches would be very welcome!
+
+    ruby 1.9.1p378 (2010-01-10 revision 26273) [i386-darwin10.2.0]
+    activerecord (2.3.5)
+    friendly_id (2.3.2)
+    sqlite3 3.6.19 in-memory database
+                                                       | DEFAULT | NO_SLUG |    SLUG | CACHED_SLUG |
+    ------------------------------------------------------------------------------------------------
+    find model by id                             x1000 |   0.274 |   0.426 |   0.780 |       0.489 |
+    find model using array of ids                x1000 |   0.517 |   0.525 |   1.692 |       0.623 |
+    find model using id, then to_param           x1000 |   0.279 |   0.431 |   1.253 |       0.498 |
+    ================================================================================================
+    Total                                              |   1.071 |   1.382 |   3.725 |       1.610 |
+
+    ruby 1.9.1p378 (2010-01-10 revision 26273) [i386-darwin10.2.0]
+    activerecord (3.0.0.beta1)
+    friendly_id (2.3.2)
+    sqlite3 3.6.19 in-memory database
+
+                                                       | DEFAULT | NO_SLUG |    SLUG | CACHED_SLUG |
+    ------------------------------------------------------------------------------------------------
+    find model by id                             x1000 |   0.557 |   1.135 |   6.491 |       1.398 |
+    find model using array of ids                x1000 |   0.862 |   0.882 |   6.152 |       1.919 |
+    find model using id, then to_param           x1000 |   0.658 |   2.200 |   8.398 |       1.539 |
+    ================================================================================================
+    Total                                              |   2.077 |   4.217 |  21.041 |       4.856 |