activeldap 1.2.4 → 3.1.0

data/{CHANGES → doc/text/news.textile}

@@ -1,12 +1,19 @@
-= CHANGES
+h1. News
 
-== 1.2.4: 2011-05-13
+h2(#3-1-0). 3.1.0: 2011-07-09
+
+* Supported Rails 3.1.0.rc4.
+  [Ryan Tandy, Narihiro Nakamura, Hidetoshi Yoshimoto]
+* Removed ActiveRecord dependency and added ActiveModel dependency.
+* Used YARD instead of RDoc as documentation sysytem.
+
+h2. 1.2.4: 2011-05-13
 
 * Splited AL-Admin into other repository: https://github.com/activeldap/al-admin
 * [GitHub:#2] Fixed "path po cound not be found" error by fast_gettext.
   [rbq]
 
-== 1.2.3: 2011-04-30
+h2. 1.2.3: 2011-04-30
 
 * [#40] Ignored nil value attribute.
   [christian.pennafort]
@@ -21,7 +28,7 @@
 * Fixed wrong assertion in test.
   [Ryan Tandy]
 
-=== Thanks
+h3. Thanks
 
 * christian.pennafort
 * planetmcd
@@ -30,7 +37,7 @@
 * Kris Wehner
 * Ryan Tandy
 
-== 1.2.2: 2010-07-04
+h2. 1.2.2: 2010-07-04
 
 * Supported ActiveRecord 2.3.8 and Rails 2.3.8.
 * [#37] Fixed gem dependencies in Rakefile. [zachwily]
@@ -47,7 +54,7 @@
 * Supported DN attribute value for assosiation replacement.
   [Jörg Herzinger]
 
-== 1.2.1: 2009-12-15
+h2. 1.2.1: 2009-12-15
 
 * Supported ActiveRecord 2.3.5 and Rails 2.3.5.
 * Supported GetText 2.1.0 and Locale 2.0.5.
@@ -58,7 +65,7 @@
 * [#35] fix has_many association is broken. [culturespy]
 * Supported nested attribute options. [Hideyuki Yasuda]
 
-== 1.2.0: 2009-09-22
+h2. 1.2.0: 2009-09-22
 
 * Supported ActiveRecord 2.3.4 and Rails 2.3.4.
 * [IMCOMPATIBLE]
@@ -73,60 +80,60 @@
 * Supported renaming an entry. Renaming other DTI is only supported by
   JNDI backend.
 
-== 1.1.0: 2009-07-18
+h2. 1.1.0: 2009-07-18
 
 * Improved tutorial. [Kazuaki Takase]
 * Improvements:
-  * API:
-    * [#26] Supported to_xml for associations. [achemze]
-    * ActiveLdap::Base.delete_all(filter=nil, options={}) ->
-      ActiveLdap::Base.delete_all(filter_or_options={}).
-      Sure, old method signature is also still supported.
-    * belongs_to(:many) with :foreign_key is deprecated.
-      Use :primary_key instead of :foreign_key. [Kazuaki Takase]
-    * Means of has_many's :primary_key and :foreign_key are inverted.
-      [Kazuaki Takase]
-    * [experimental] Added ldap_field ActionView helper to
-      generate form fileds for a LDAP entry.
-  * Suppressed needless attributes updating.
+** API:
+*** [#26] Supported to_xml for associations. [achemze]
+*** ActiveLdap::Base.delete_all(filter=nil, options={}) ->
+    ActiveLdap::Base.delete_all(filter_or_options={}).
+    Sure, old method signature is also still supported.
+*** belongs_to(:many) with :foreign_key is deprecated.
+    Use :primary_key instead of :foreign_key. [Kazuaki Takase]
+*** Means of has_many's :primary_key and :foreign_key are inverted.
+    [Kazuaki Takase]
+*** [experimental] Added ldap_field ActionView helper to
+    generate form fileds for a LDAP entry.
+** Suppressed needless attributes updating.
 * Dependencies:
-  * Re-supported GetText.
-  * ActiveRecord 2.3.2 is only supported.
+** Re-supported GetText.
+** ActiveRecord 2.3.2 is only supported.
 
-== 1.0.9
+h2. 1.0.9
 
 * Added documents in Japanese. [Kazuaki Takase]
 * Supported Ruby 1.9.1.
-  * [#20] [Ruby 1.9 Support] :: Running Tests [Alexey.Chebotar]
+** [#20] [Ruby 1.9 Support] :: Running Tests [Alexey.Chebotar]
 * Supported Rails 2.3.2.
-  * [#18] [Rails 2.3 Support] :: Running WEBrick Hangs [Alexey.Chebotar]
+** [#18] [Rails 2.3 Support] :: Running WEBrick Hangs [Alexey.Chebotar]
 * Bug fixes:
-  * Fixed blank values detection. [David Morton]
-  * [#22] Ruby 1.8.6 p287 :: Undefined methods [Alexey.Chebotar]
-  * Fixed gem loading. [Tiago Fernandes]
-  * Fixed DN change via #base=. [David Morton]
-  * Fixed infinite retry on timeout.
-  * Fixed needless reconnection.
+** Fixed blank values detection. [David Morton]
+** [#22] Ruby 1.8.6 p287 :: Undefined methods [Alexey.Chebotar]
+** Fixed gem loading. [Tiago Fernandes]
+** Fixed DN change via #base=. [David Morton]
+** Fixed infinite retry on timeout.
+** Fixed needless reconnection.
 * API improvements:
-  * Removed needless instance methods: #prefix=,
-    #dn_attribute=, #sort_by=, #order=, #required_classes=,
-    #recommended_classes= and #excluded_classes. [David Morton]
-  * Removed obsolete scafoold_al generator.
-  * Reduced default :retry_limit.
-  * Supported association as parameter. [Joe Francis]
-  * Normalized schema attribute name. [Tim Hermans]
-  * Suppressed AuthenticationError -> ConnectionError
-    conversion on reconnection. [Kazuaki Takase]
-  * Added ActiveLdap::Schema#dump.
-  * ActiveLdap::Base.establish_connection ->
-    ActiveLdap::Base.setup_connection.
-  * Supported ActiveLdap::Base.find(:last).
-  * Added convenient methods:
-    * ActiveLdap::Base.first
-    * ActiveLdap::Base.last
-    * ActiveLdap::Base.all
-
-== 1.0.2
+** Removed needless instance methods: #prefix=,
+   #dn_attribute=, #sort_by=, #order=, #required_classes=,
+   #recommended_classes= and #excluded_classes. [David Morton]
+** Removed obsolete scafoold_al generator.
+** Reduced default :retry_limit.
+** Supported association as parameter. [Joe Francis]
+** Normalized schema attribute name. [Tim Hermans]
+** Suppressed AuthenticationError -> ConnectionError
+   conversion on reconnection. [Kazuaki Takase]
+** Added ActiveLdap::Schema#dump.
+** ActiveLdap::Base.establish_connection ->
+   ActiveLdap::Base.setup_connection.
+** Supported ActiveLdap::Base.find(:last).
+** Added convenient methods:
+*** ActiveLdap::Base.first
+*** ActiveLdap::Base.last
+*** ActiveLdap::Base.all
+
+h2. 1.0.2
 
 * Removed Base64 module use.
 * Improved LDIF parser.
@@ -142,26 +149,26 @@
 * Accepted :class_name for belong_to and has_many option.
 * Improved default port guess.
 * Bug fixes:
-  * [#4] ModifyRecord#load doesn't operate atomic. [gwarf12]
-  * [#5] to_xml supports :except option. [baptiste.grenier]
-  * [#6] to_xml uses ActiveResource format. [baptiste.grenier]
-  * Out of ranged GeneralizedTime uses Time.at(0) as fallback value.
-    [Richard Nicholas]
-  * ActiveLdap::Base#to_s uses #to_ldif. [Kazuhiro NISHIYAMA]
-  * Fixed excess prefix extraction. [Grzegorz Marszałek]
-  * Skiped read only attribute validation. [しまさわらさん]
-  * Treated "" as empty value. [Ted Lepich]
-  * [#9][#16] Reduced raising when DN value is invalid.
-    [danger1986][Alexey.Chebotar]
-  * [#10][#12] Fixed needless ',' is appeared. [michael.j.konopka]
-  * [#11] Required missing 'active_ldap/user_password'. [michael.j.konopka]
-  * [#13] Returned entries if has_many :wrap has nonexistent entry.
-    [ingersoll]
-  * [#15] Fixed type error on computing DN. [ery.lee]
-  * ">=" filter operator doesn't work. [id:dicdak]
-  * [#17] ActiveLdap::Base.create doesn't raise exception. [Alexey.Chebotar]
-
-== 1.0.1
+** [#4] ModifyRecord#load doesn't operate atomic. [gwarf12]
+** [#5] to_xml supports :except option. [baptiste.grenier]
+** [#6] to_xml uses ActiveResource format. [baptiste.grenier]
+** Out of ranged GeneralizedTime uses Time.at(0) as fallback value.
+   [Richard Nicholas]
+** ActiveLdap::Base#to_s uses #to_ldif. [Kazuhiro NISHIYAMA]
+** Fixed excess prefix extraction. [Grzegorz Marszałek]
+** Skiped read only attribute validation. [しまさわらさん]
+** Treated "" as empty value. [Ted Lepich]
+** [#9][#16] Reduced raising when DN value is invalid.
+   [danger1986][Alexey.Chebotar]
+** [#10][#12] Fixed needless ',' is appeared. [michael.j.konopka]
+** [#11] Required missing 'active_ldap/user_password'. [michael.j.konopka]
+** [#13] Returned entries if has_many :wrap has nonexistent entry.
+   [ingersoll]
+** [#15] Fixed type error on computing DN. [ery.lee]
+** ">=" filter operator doesn't work. [id:dicdak]
+** [#17] ActiveLdap::Base.create doesn't raise exception. [Alexey.Chebotar]
+
+h2. 1.0.1
 
 * Fixed GetText integration.
 * Fixed ActiveLdap::Base.find with ActiveLdap::DN. (Reported by Jeremy Pruitt)
@@ -172,73 +179,77 @@
 * Improved inspect.
 * Supported ActiveSupport 2.1.0.
 
-== 1.0.0
+h2. 1.0.0
 
 * Fixed GSSAPI auth failure. [#18764] (Reported by Lennon Day-Reynolds)
 * Supported Symbol as :dn_attribute_value. [#18921] (Requested by Nobody)
 * Improved DN attribute detection. (Reported by Iain Pople)
 * Avoided unnecesally modify operation. (Reported by Tilo)
 
-== 0.10.0
+h2. 0.10.0
 
 * Implemented LDIF parser.
 * Improved validation:
-  * Added some validations.
-  * Fixed SINGLE-VALUE validation. [#17763]
-    (Reported by Naoto Morishima)
+** Added some validations.
+** Fixed SINGLE-VALUE validation. [#17763]
+   (Reported by Naoto Morishima)
 * Supported JNDI as backend.
 * Improved auto reconnection.
 * Supported Rails 2.0.2.
 * Improved performance. (4x)
 * [API CHANGE]: removed "'binary' =>" from getter result.
 
+  <pre>
+  !!!plain
   e.g.:
     before:
         user.user_certificate # => {"binary" => "..."}
        now:
         user.user_certificate # => "..."
+  </pre>
+
 * Added :excluded_classed ldap_mapping option.
 * Logged operation time used for LDAP operation.
 * Improved API:
-  * Accepted non String value for find(:value => XXX).
-    (Suggested by Marc Dequèn)
-  * Accepted DN as ActiveLdap::Base.new(XXX).
-    (Reported by Jeremy Pruitt)
-  * Treated empty password for smiple bind as anonymous bind.
-    (Suggested by Bodaniel Jeans)
-  * Ensured adding "objectClass" for find's :attribute value. [#16946]
-    (Suggested by Nobody)
-  * Fixed a GeneralizedTime type casting bug.
-    (Reported by Bodaniel Jeanes)
-  * Supported :base and :prefix search/find option value escaping.
-    (Suggested by David Morton)
-
-== 0.9.0
+** Accepted non String value for find(:value => XXX).
+   (Suggested by Marc Dequèn)
+** Accepted DN as ActiveLdap::Base.new(XXX).
+   (Reported by Jeremy Pruitt)
+** Treated empty password for smiple bind as anonymous bind.
+   (Suggested by Bodaniel Jeans)
+** Ensured adding "objectClass" for find's :attribute value. [#16946]
+   (Suggested by Nobody)
+** Fixed a GeneralizedTime type casting bug.
+   (Reported by Bodaniel Jeanes)
+** Supported :base and :prefix search/find option value escaping.
+   (Suggested by David Morton)
+
+h2. 0.9.0
 
 * Improved DN handling.
 * Supported attribute value validation by LDAP schema.
 * Changed RubyGems name: ruby-activeldap -> activeldap.
 * Removed Log4r dependency.
 * Supported lazy connection establishing.
-  * [API CHANGE]: establish_connection doesn't connect LDAP server.
+** [API CHANGE]: establish_connection doesn't connect LDAP server.
 * [API CHANGE]: Removed ActiveLdap::Base#establish_connection.
 * Added ActiveLdap::Base#bind. (use this instead of #establish_connection)
 * Supported implicit acts_as_tree.
 * [API CHANGE]: Supported type casting.
 * Supported :uri option in configuration.
 * Improved Rails integration:
-  * Followed Rails 2.0 changes.
-  * AL-Admin:
-    * Supported lang parameter in URL.
-    * Improved design a bit. (Please someone help us!)
-    * Supported schema inspection.
-    * Supported objectClass modifiation.
-  * Rails plugin:
-    * Added ActiveLdap::VERSION check.
-    * Added model_active_ldap generator.
-    * Renamed scaffold_al generator to scaffold_active_ldap.
-
-== 0.8.3
+** Followed Rails 2.0 changes.
+** AL-Admin:
+*** Supported lang parameter in URL.
+*** Improved design a bit. (Please someone help us!)
+*** Supported schema inspection.
+*** Supported objectClass modifiation.
+** Rails plugin:
+*** Added ActiveLdap::VERSION check.
+*** Added model_active_ldap generator.
+*** Renamed scaffold_al generator to scaffold_active_ldap.
+
+h2. 0.8.3
 
 * Added AL-Admin Sample Rails app
 * Added Ruby-GetText-Package support
@@ -247,36 +258,36 @@
 * Improved performance
 * Many bug fixes
 
-== 0.8.2
+h2. 0.8.2
 
 * Added Net::LDAP support!
-  * supported SASL Digest-MD5 authentication with Net::LDAP.
+** supported SASL Digest-MD5 authentication with Net::LDAP.
 * improved LDAP server support:
-  * improved Sun DS support.
-  * improved ActiveDirectory support. Thanks to Ernie Miller!
-  * improved Fedora-DS support. Thanks to Daniel Pfile!
+** improved Sun DS support.
+** improved ActiveDirectory support. Thanks to Ernie Miller!
+** improved Fedora-DS support. Thanks to Daniel Pfile!
 * improved existing functions:
-  * improved DN handling. Thanks to James Hughes!
-  * improved SASL bind.
-  * improved old API check.
-  * improved schema handling. Thanks to Christoph Lipp!
-  * improved filter notification.
+** improved DN handling. Thanks to James Hughes!
+** improved SASL bind.
+** improved old API check.
+** improved schema handling. Thanks to Christoph Lipp!
+** improved filter notification.
 * updated documents:
-  * updated Rails realted documenation. Thanks to James Hughes!
-  * updated documentation for the changes between 0.7.1 and 0.8.0.
-    Thanks to Buzz Chopra!
+** updated Rails realted documenation. Thanks to James Hughes!
+** updated documentation for the changes between 0.7.1 and 0.8.0.
+   Thanks to Buzz Chopra!
 * added new features:
-  * added scaffold_al generator for Rails.
-  * added required_classes to default filter value. Thanks to Jeff Hall!
-  * added :recommended_classes option to ldap_mapping.
-  * added :sort_by and :order options to find.
-  * added ActiveLdap::Base#to_param for ActionController.
+** added scaffold_al generator for Rails.
+** added required_classes to default filter value. Thanks to Jeff Hall!
+** added :recommended_classes option to ldap_mapping.
+** added :sort_by and :order options to find.
+** added ActiveLdap::Base#to_param for ActionController.
 * fixed some bugs:
-  * fixed rake install/uninstall.
-  * fixed typos. Thanks to Nobody!
-  * fixed required_classes initialization. Thanks to James Hughes!
+** fixed rake install/uninstall.
+** fixed typos. Thanks to Nobody!
+** fixed required_classes initialization. Thanks to James Hughes!
 
-== 0.8.1
+h2. 0.8.1
 
 * used Dependencies.load_paths.
 * check whether attribute name is available or not.
@@ -294,7 +305,7 @@
 * followed new API.
 * removed a finished task: support Reloadable::Subclasses.
 
-== 0.8.0
+h2. 0.8.0
 
 * Makefile/gemspec system replaced with Rakefile + Hoe
 * Bugfix: Allow base to be empty
@@ -325,30 +336,30 @@
 * make save!() raise EntryNotSaved exception
 * to_xml()
 * clear_active_connections!() -- Conn per class
-  - make @@active_connections and name them by
+** make @@active_connections and name them by
 * base_class() (just return the ancestor)
 * Separate ObjectClass changes to live in ActiveLDAP::ObjectClass
-  - add_objectclass
-  - remove_objectclass
-  - replace_objectclass
-  - disallow direct objectclass access?
+** add_objectclass
+** remove_objectclass
+** replace_objectclass
+** disallow direct objectclass access?
 * support ActiveRecord::Validations.
 * support ActiveRecord::Callbacks.
 * rename to ActiveLdap from ActiveLDAP to integrate RoR easily and enforce
   many API changes.
 
-== 0.7.4
+h2. 0.7.4
 
 * Bugfix: do not base LDAP::PrettyError on RuntimeError due to rescue evaluation.
 * Bugfix: :return_objects was overriding :objects in find and find_all
 * Rollup exception code into smaller space reusing similar code.
 
-== 0.7.3
+h2. 0.7.3
 
 * Made has_many and belongs_to use :return_objects value
 * Force generation of LDAP constants on import - currently broken
 
-== 0.7.2
+h2. 0.7.2
 
 * Stopped overriding Conn.schema in ldap/schema - now use schema2
 * Fix attributes being deleted when changing between objectclasses with shared attributes
@@ -371,14 +382,14 @@
 * Added(*) a forking timeout using SIGALRM to interrupt handling.
 * (*) Only works when RUBY_PLATFORM has "linux" in it
 
-== 0.7.1
+h2. 0.7.1
 
 * Fix broken -W0 arg in activeldap.rb
 * attribute_method=: '' and nil converted to ldap-pleasing [] values
 * Added checks in write and search for connection down (to reconnect)
 * Fixed broken idea of LDAP::err2string exceptions. Instead took errcodes from ldap.c in Ruby/LDAP.
 
-== 0.7.0
+h2. 0.7.0
 
 * ConnectionError thrown from #initialize when there is no connection and retry limit was exceeded
 * ConnectionError thrown when retries exceeded when no connection was created
@@ -399,7 +410,7 @@
 * Added support for Base::connect(.., :password => String, ...) to avoid stupid Proc.new {'foo'} crap
 * Add :store_password option. When this is set, :password is not cleared and :password_block is not re-evaluated on each rebind.
 
-== 0.6.0
+h2. 0.6.0
 
 * Disallow blank DN attribute values on initialization
 * Fix bug reported by Maik Schmidt regarding object creation
@@ -410,7 +421,7 @@
 * Changes examples and tests to use "dc=localdomain"
 * has_many() entries no longer return nil when empty
 
-== 0.5.9
+h2. 0.5.9
 
 * Change default base to dc=localdomain (as per Debian default).
 * schema2.rb:attr() now returns [] instead of '' when empty.
@@ -422,60 +433,60 @@
 * Fixed broken creation of objects from anonymous classes.
 * Fixed broken use of ldap_mapping with anonymous classes.
 
-== 0.5.8: Bugfix galore
+h2. 0.5.8: Bugfix galore
 
 * Allow nil "prefix"
 * Fixed the dup bug with Anonymous patch.
 * (maybe) Fixed stale connection problems by attempting reconn/bind.
 * Hiding redefine warnings (for now)
 
-== 0.5.7
+h2. 0.5.7
 
 * Fixed the @data.default = [] bug that daniel@nightrunner.com pointed out
   (and partially patched).
 
-== 0.5.6
+h2. 0.5.6
 
 * Added support for foreign_key => 'dn' in has_many.
 
-== 0.5.5
+h2. 0.5.5
 
 * Remove @@logger.debug entries during build
 * Building -debug and regular gems and tarballs
 
-== 0.5.4
+h2. 0.5.4
 
 * Added Base#import to streamline the Base.find and Base.find_all methods
-  - Speeds up find and find_all by not accessing LDAP multiple times
-    for data we already have.
+** Speeds up find and find_all by not accessing LDAP multiple times
+   for data we already have.
 * Added tests/benchmark which is a slightly modified version of excellent
   benchmarking code contributed by
   Ollivier Robert <roberto -_-AT-_- keltia.freenix.fr>.
 
-== 0.5.3
+h2. 0.5.3
 
 * Changed attribute_method to send in associations
-  - fixes belongs_to (with local_kay) and inheritance around that
+** fixes belongs_to (with local_kay) and inheritance around that
 
-== 0.5.2
+h2. 0.5.2
 
 * Make sure values are .dup'd when they come from LDAP
 
-== 0.5.1
+h2. 0.5.1
 
-* Changed Schema2#class_attributes to return {:must => [], :may => []}
+* Changed Schema2#class_attributes to return @{:must => [], :may => []}@
 * Fixed Base#must and Base#may to return with full SUPerclass requirements
 
-== 0.5.0
+h2. 0.5.0
 
 * API CHANGE (as with all 0.x.0 changes) (towards ActiveRecord duck typing)
-  - Base#ldapattribute now always returns an array
-  - Base#ldapattribute(true) now returns a dup of an array, string, etc 
-    when appropriate (old default) - This is just for convenience
-  - Base#ldapattribute returns the stored value, not just a .dup
-  - Associations methods return objects by default instead of just names.
-    Group.new('foo').members(false) will return names only.
-  - Base.connect returns true as one might expect
+** Base#ldapattribute now always returns an array
+** Base#ldapattribute(true) now returns a dup of an array, string, etc 
+   when appropriate (old default) - This is just for convenience
+** Base#ldapattribute returns the stored value, not just a .dup
+** Associations methods return objects by default instead of just names.
+   Group.new('foo').members(false) will return names only.
+** Base.connect returns true as one might expect
 * Value validation and changing (binary, etc) occur prior to write, and
   not immediately on attribute_method=(value).
 * Attribute method validity is now determined /on-the-fly/.
@@ -495,122 +506,130 @@
   This also makes it possible to "break" objects by removing the 'top'
   objectclass and therefore the #objectClass method...
 
-== 0.4.4
+h2. 0.4.4
 
 * Fixed binary subtype forcing:
-  - was setting data as subtype ;binary even when not required
+** was setting data as subtype ;binary even when not required
 * Added first set of unit tests.
-  - These will be cleaned up in later releases as more tests are added.
+** These will be cleaned up in later releases as more tests are added.
 * Fixed subtype clobber non-subtype (unittest!)
-  - cn and cn;lang-blah: the last loaded won
+** cn and cn;lang-blah: the last loaded won
 * Fixed multivalued subtypes from being shoved into a string (unittest!)
-  - an error with attribute_input_value
+** an error with attribute_input_value
 
-== 0.4.3
+h2. 0.4.3
 
 * Fixed write (add) bugs introduced with last change
-  - only bug fixes until unittests are in place
+** only bug fixes until unittests are in place
 
-== 0.4.2
+h2. 0.4.2
 
 * Added ruby-activeldap.gemspec
 * Integrated building a gem of 'ruby-activeldap' into Makefile.package
 * Added attr parsing cache to speed up repetitive calls: approx 13x speedup
-  - 100 usermod-binary-add calls
-
-      Without attr parsing cache:
-	real    13m53.129s
-	user    13m11.350s
-	sys     0m7.030s
-      With attr parsing cache:
-	real    1m0.416s
-	user    0m28.390s
-	sys     0m2.380s
-
-== 0.4.1:
+** 100 usermod-binary-add calls
+
+   <pre>
+   !!!plain
+   Without attr parsing cache:
+     real    13m53.129s
+     user    13m11.350s
+     sys     0m7.030s
+   With attr parsing cache:
+     real    1m0.416s
+     user    0m28.390s
+     sys     0m2.380s
+   </pre>
+
+h2. 0.4.1:
 
 * Schema2 was not correctly parsing objectClass entries.
-  - This is fixed for now but must be revisited.
+** This is fixed for now but must be revisited.
 
-== 0.4.0
+h2. 0.4.0
 
 * Added #<attribute>(arrays) argument which when true
   always returns arrays. e.g.
-     irb> user.cn(true)
-     => ['My Common Name']
+
+  <pre>
+  !!!plain
+  irb> user.cn(true)
+  => ['My Common Name']
+  </pre>
+
   This makes things easier for larger programming tasks.
 * Added subtype support:
-  - Uses Hash objects to specify the subtype
-    e.g. user.userCertificate = {'binary' => File.read('mycert.der')}
-  - Added recursive type enforcement along with the subtype handling
-  - This required overhauling the #write method.
-    - Please report any problems ASAP! :^)
+** Uses Hash objects to specify the subtype
+   e.g. @user.userCertificate = {'binary' => File.read('mycert.der')}@
+** Added recursive type enforcement along with the subtype handling
+** This required overhauling the #write method.
+*** Please report any problems ASAP! :^)
 * Added automagic binary support
-  - subtype wrapping done automatically
-  - relies on X-NOT-HUMAN-READABLE flag
+** subtype wrapping done automatically
+** relies on X-NOT-HUMAN-READABLE flag
 * Added LDAP::Schema2 which is an extension of Ruby/LDAP::Schema
-  - made Schema#attr generic for easy type dereferencing
+** made Schema#attr generic for easy type dereferencing
 * Updated rdoc in activeldap.rb
 * Updated examples (poorly) to reflect new functionality
 * Added several private helper functions
 
-== 0.3.6
+h2. 0.3.6
 
 * Fixed dn attribute value extraction on find and find_all
-  - these may have grabbed the wrong value if a DN attr has
-    multiple values.
+** these may have grabbed the wrong value if a DN attr has
+   multiple values.
 * Fixed Base.search to return all values as arrays and update
   multivalued ones correctly
 * Lowered the amount of default logging to FATAL only
 
-== 0.3.5
+h2. 0.3.5
 
 * Moved to rubyforge.org!
 
-== 0.3.4
+h2. 0.3.4
 
 * Changed license to Ruby's
 
-== 0.3.3
+h2. 0.3.3
 
 * Changed Base.search to return an array instead of a hash of hashes
 * Change Base.search to take in a hash as its arguments
 
-== 0.3.2
+h2. 0.3.2
 
 * Bug fix - fixed support for module'd extension classes (again!)
 
-== 0.3.1
+h2. 0.3.1
 
 * Updated the documentation
 * Fixed ignoring of attrs argument in Base.search
 * Fixed mistake in groupls (using dnattr directly)
 * Fixed a mistake with overzealous dup'ing
 
-== 0.3.0
+h2. 0.3.0
 
 * MORE API CHANGES (configuration.rb, etc)
 * Major overhaul to the internals!
-  - removed @@BLAH[@klass] in lieu of defining
-    class methods which contain the required values. This
-    allows for clean inheritance of Base subclasses! Whew!
-  - Added @@config to store the options currently in use
-    after a Base.connect
-  - Now cache passwords for doing reconnects
-  - dnattr now accessible to the outside as a class method only
+** removed @@BLAH[@klass] in lieu of defining
+   class methods which contain the required values. This
+   allows for clean inheritance of Base subclasses! Whew!
+** Added @@config to store the options currently in use
+   after a Base.connect
+** Now cache passwords for doing reconnects
+** dnattr now accessible to the outside as a class method only
 * Added Base.search to wrap normal LDAP search for convenience.
-  - This returns a hash of hashes with the results indexed first by
-    full dn, then by attribute.
+** This returns a hash of hashes with the results indexed first by
+   full dn, then by attribute.
 
-== 0.2.0
+h2. 0.2.0
 
 * API CHANGES:
-  - Extension classes must be defined using map_to_ldap instead of setting
-    random values in initialize
-  - Base#find is now Base.find_all and is a class method
-  - Base.find returns the first match a la Array#find
-  - force_reload is gone in belongs_to and has_many created methods
-  - hiding Base.new, Base.find, and Base.find_all from direct access
+** Extension classes must be defined using map_to_ldap instead of setting
+   random values in initialize
+** Base#find is now Base.find_all and is a class method
+** Base.find returns the first match a la Array#find
+** force_reload is gone in belongs_to and has_many created methods
+** hiding Base.new, Base.find, and Base.find_all from direct access
 * added uniq to setting objectClass to avoid stupid errors
 * fixed new object creation bug where attributes were added before the
   objectclass resulting in a violation (Base#write)
@@ -624,48 +643,48 @@
 * Base.connect(:try_sasl => true) should now work with GSSAPI if you are
   using OpenLDAP >= 2.1.29
 
-== 0.1.8
+h2. 0.1.8
 
 * .dup all returned attribute values to avoid weirdness
 * .dup all assigned values to avoid weirdness
 * Changed default configuration.rb to use example.com
 
-== 0.1.7
+h2. 0.1.7
 
 * Added support for non-unique DN attributes
 * Added authoritative DN retrieval with 'object.dn'
 
-== 0.1.6
+h2. 0.1.6
 
 * Added Base.close method for clearing the existing connection (despite Ruby/LDAP's lack of .close)
 
-== 0.1.5
+h2. 0.1.5
 
 * Fixed incorrect usage of @klass in .find (should .find be a class method?)
 
-== 0.1.4
+h2. 0.1.4
 
 * Change WARN to INFO in associations.rb for has_many
 
-== 0.1.3
+h2. 0.1.3
 
 * Fixed class name mangling
 * Added support for classes to take DNs as the initialization value
 
-== 0.1.2
+h2. 0.1.2
 
 * Patch from Dick Davies: Try SSL before TLS
 * Log4r support
 * Better packaging (automated)
 * Work-around for SSL stupidity
-  - SSLConn doesn't check if the port it connected to is really using SSL!
+** SSLConn doesn't check if the port it connected to is really using SSL!
 
-== 0.1.1
+h2. 0.1.1
 
 * Dynamic table class creation
 * SASL/GSSAPI disabled by default - doesn't work consistently
 
-== 0.1.0
+h2. 0.1.0
 
 * Added foreign_key to has_many
 * Added local_key to belongs_to
@@ -674,48 +693,48 @@
 * Packaged up with setup.rb
 * Added RDocs and better comments
 
-== 0.0.9
+h2. 0.0.9
 
 * Separated extension classes from ActiveLDAP module
 * Cleaned up examples with new requires
 
-== 0.0.8
+h2. 0.0.8
 
 * Added user and group scripting examples
-  - usermod, userls, useradd, userdel
-  - groupmod, groupls
+** usermod, userls, useradd, userdel
+** groupmod, groupls
 
-== 0.0.7
+h2. 0.0.7
 
 * Cleaner authentication loop:
-  - SASL (GSSAPI only), simple, anonymous
+** SASL (GSSAPI only), simple, anonymous
 * Added allow_anonymous option added (default: false)
 
-== 0.0.6
+h2. 0.0.6
 
 * Write support cleaned up
 * Exception classes added
 
-== 0.0.5
+h2. 0.0.5
 
 * LDAP write support added
 
-== 0.0.4
+h2. 0.0.4
 
 * MUST and MAY data validation against schema using objectClasses
 
-== 0.0.3
+h2. 0.0.3
 
 * LDAP attributes alias resolution and data mapping
 
-== 0.0.2
+h2. 0.0.2
 
 * Associations: has_many and belongs_to Class methods added for Base
 
-== 0.0.1
+h2. 0.0.1
 
 * Extension approach in place with example User and Group classes
 
-== 0.0.0
+h2. 0.0.0
 
 * Basic LDAP read support in place with hard-coded OUs