README.rdoc in icu_name-1.1.1 vs README.rdoc in icu_name-1.2.0

@@ -49,14 +49,15 @@
 
 The method <tt>alternatives</tt> can be used to list alternatives to a given first or last name:
 
   Name.new('Stephen', 'Orr').alternatives(:first)             # => ["Steve"]
   Name.new('Michael Stephen', 'Orr').alternatives(:first)     # => ["Steve", "Mike", "Mick", "Mikey"],
+  Name.new('Oissine', 'Murphy').alternatives(:last)           # => ["Murchadha"],
   Name.new('Mark', 'Orr').alternatives(:first)                # => []
   
-By default the class is only aware of a few common alternatives for first names (e.g. _Bobby_ and _Robert_,
-_Bill_ and _William_, etc). However, this can be customized (see below).
+By default the class uses a set of first and last name alternatives curated for the ICU.
+However, this can be customized (see below).
 
 Supplying the <tt>match</tt> method with strings is equivalent to instantiating an instance with the same
 strings and then matching it. So, for example the following are equivalent:
 
   robert.match('R.', 'Fischer')                               # => true
@@ -107,69 +108,44 @@
 == Customization of Alternative Names
 
 We saw above how _Bobby_ and _Robert_ were able to match because, by default, the
 matcher is aware of some common English nicknames. These name alternatives can be
 customised to handle additional nicknames and other types of alternative names
-such as common spelling error and player name changes.
+such as common spelling errors and player name changes.
 
 The alternative names consist of two arrays, one for first names and
 one for last names. Each array element is itself an array of strings
 representing a set of equivalent names. Here, for example, are some
 of the default first name alternatives:
 
   ["Anthony", "Tony"]
-  ["James", "Jim", "Jimmy"]
-  ["Michael", "Mike", "Mick", "Mikey"]
+  ["James", "Jim", "Jimmy", "Jamie"]
   ["Robert", "Bob", "Bobby"]
-  ["Stephen", "Steve"]
-  ["Steven", "Steve"]
+  ["Stephen", "Steve", "Steven"]
   ["Thomas", "Tom", "Tommy"]
-  ["William", "Will", "Willy", "Willie", "Bill"]
 
 The first of these means that _Anthony_ and _Tony_ are considered equivalent and can match.
 
-  Name.new("Tony", "Miles").match("Anthony", "Miles")         # => true
+  ICU::Name.new("Tony", "Miles").match("Anthony", "Miles")    # => true
 
-Note that both _Steven_ and _Stephen_ match _Steve_ but, because they don't occur in the
-same group, they don't match each other.
-
-  Name.new("Steven", "Hanly").match("Steve", "Hanly")         # => true
-  Name.new("Stephen", "Hanly").match("Steve", "Hanly")        # => true
-  Name.new("Stephen", "Hanly").match("Steven", "Hanly")       # => false
-
 To change alternative name behaviour, you can replace the default alternatives
 with a customized set perhaps stored in a database or a YAML file, as illustrated below:
 
+  ICU::Name.reset_alternatives
   data = YAML.load(File open "my_last_name_alternatives.yaml")
-  Name.load_alternatives(:last, data)
+  ICU::Name.load_alternatives(:last, data)
   data = YAML.load(File open "my_first_name_alternatives.yaml")
-  Name.load_alternatives(:first, data)
+  ICU::Name.load_alternatives(:first, data)
 
-An example of one way in which you might want to customize the alternatives is to
-cater for common spelling mistakes such as _Steven_ and _Stephen_. These two names
-don't match by default, but you can make them so by replacing the two default rules:
+Note that without the call to <tt>reset_alternatives</tt>, the new loaded alternatives
+add to, rather than replace, the defaults.
 
-  ["Stephen", "Steve"]
-  ["Steven", "Steve"]
+Other uses of alternatives is to cater for English and Irish versions of the same name,
+for example (last names):
 
-with the following single rule:
-
-  ["Stephen", "Steven", "Steve"]
-
-so that now:
-
-  Name.new("Stephen", "Hanly").match("Steven", "Hanly")       # => true
-
-This kind of rule risks producing false positives - you must judge
-whether that risk is outweighed by the benefits of being able to overcome
-spelling mistakes in the context of your application.
-
-Another use is to cater for English and Irish versions of the same name.
-For example, for last names:
-
   [Murphy, Murchadha]
 
-or for first names, including spelling variations:
+or for variations including spelling variations, for example (first names):
 
   [Patrick, Pat, Paddy, Padraig, Padraic, Padhraig, Padhraic]
 
 == Conditional Alternatives