activeldap 5.2.4 → 6.0.0

data/doc/text/{rails.textile → rails.md}

@@ -1,26 +1,26 @@
-h1. Rails
+# Rails
 
 ActiveLdap supports Rails 4.0 or later.
 
-h2. Install
+## Install
 
 To install, simply add the following code to your Gemfile:
 
-<pre>
+```ruby
 gem 'activeldap', :require => 'active_ldap/railtie'
-</pre>
+```
 
 You should also depend on an LDAP adapter such as Net::LDAP
 or Ruby/LDAP. The following example uses Ruby/LDAP:
 
-<pre>
+```ruby
 gem 'ruby-ldap'
-</pre>
+```
 
 Bundler will install the gems automatically when you run
-'bundle install'.
+`bundle install`.
 
-h2. Configuration
+## Configuration
 
 You can use a LDAP configuration per environment. They are in
 a file named 'ldap.yml' in the config directory of your
@@ -32,54 +32,56 @@ development, test, and production environments.
 
 You can generate 'config/ldap.yml' by the following command:
 
-<pre class="command">
+```console
 % script/rails generate active_ldap:scaffold
-</pre>
+```
 
 You need to modify 'config/ldap.yml' generated by
-active_ldap:scaffold. For instance, the development entry
+`active_ldap:scaffold`. For instance, the development entry
 would look something like the following:
 
-<pre>
-!!!plain
+```yaml
 development:
   host: 127.0.0.1
   port: 389
   base: dc=localhost
   bind_dn: cn=admin,dc=localhost
   password: secret
-</pre>
+```
 
 When your application starts up,
 ActiveLdap::Base.setup_connection will be called with the
 parameters specified for your current environment.
 
 You can replace default orm generators with gems one
-to skip active_ldap prefix in 'config/application.rb':
-<pre>config.app_generators.orm :active_ldap</pre>
+to skip `active_ldap prefix` in `config/application.rb`:
 
-h2. Model
+```ruby
+config.app_generators.orm :active_ldap
+```
+
+## Model
 
 You can generate a User model that represents entries under
 ou=Users by the following command:
 
-<pre class="command">
+```console
 % script/rails generate active_ldap:model User --dn-attribute uid --classes person PosixAccount
-</pre>
+```
 
 It generates the following app/model/user.rb:
 
-<pre>
+```ruby
 class User < ActiveLdap::Base
   ldap_mapping :dn_attribute => "uid",
                :prefix => "ou=Users",
                :classes => ["person", "PosixAccount"]
 end
-</pre>
+```
 
 You can add relationships by modifying app/model/user.rb:
 
-<pre>
+```ruby
 class User < ActiveLdap::Base
   ldap_mapping :dn_attribute => 'uid',
                :prefix => "ou=Users",
@@ -91,27 +93,27 @@ class User < ActiveLdap::Base
   belongs_to :groups,
              :many => 'memberUid'
 end
-</pre>
+```
 
 You can also generate a Group model by the following command:
 
-<pre class="command">
+```console
 % script/rails generate active_ldap:model Group --classes PosixGroup
-</pre>
+```
 
 app/model/group.rb:
 
-<pre>
+```ruby
 class Group < ActiveLdap::Base
   ldap_mapping :dn_attribute => "cn",
                :prefix => "ou=Groups",
                :classes => ["PosixGroup"]
 end
-</pre>
+```
 
 You can add relationships by modifying app/model/group.rb:
 
-<pre>
+```ruby
 class Group < ActiveLdap::Base
   ldap_mapping :dn_attribute => "cn",
                :prefix => "ou=Groups",
@@ -124,18 +126,18 @@ class Group < ActiveLdap::Base
            :foreign_key => "gidNumber",
            :primary_key => "gidNumber"
 end
-</pre>
+```
 
 You can also generate a Ou model by the following command:
 
-<pre class="command">
+```console
 % script/rails generate active_ldap:model Ou --prefix '' --classes organizationalUnit
-</pre>
+```
 
-<pre>
+```ruby
 class Ou < ActiveLdap::Base
   ldap_mapping :dn_attribute => "cn",
                :prefix => "",
                :classes => ["organizationalUnit"]
 end
-</pre>
+```

data/doc/text/{tutorial.textile → tutorial.md}

@@ -1,17 +1,18 @@
-h1. Tutorial
+# Tutorial
 
-h2. Introduction
+## Introduction
 
-ActiveLdap is a novel way of interacting with LDAP.  Most interaction with
-LDAP is done using clunky LDIFs, web interfaces, or with painful APIs that
-required a thick reference manual nearby. ActiveLdap aims to fix that.
-Inspired by "ActiveRecord":http://activerecord.rubyonrails.org, ActiveLdap provides an
-object oriented interface to LDAP entries.
+ActiveLdap is a novel way of interacting with LDAP.  Most interaction
+with LDAP is done using clunky LDIFs, web interfaces, or with painful
+APIs that required a thick reference manual nearby. ActiveLdap aims to
+fix that.  Inspired by [Active
+Record](https://rubygems.org/gems/activerecord), ActiveLdap provides
+an object oriented interface to LDAP entries.
 
 The target audience is system administrators and LDAP users everywhere that
 need quick, clean access to LDAP in Ruby.
 
-h3. What's LDAP?
+### What's LDAP?
 
 LDAP stands for "Lightweight Directory Access Protocol." Basically this means
 that it is the protocol used for accessing LDAP servers.  LDAP servers
@@ -23,10 +24,10 @@ authorization server for Unix systems. (Unfortunately, I've yet to try this
 against Microsoft's ActiveDirectory, despite what the name implies.)
 
 Further reading:
-* "RFC1777":http://www.faqs.org/rfcs/rfc1777.html - Lightweight Directory Access Protocol
-* "OpenLDAP":http://www.openldap.org
+* [RFC1777](https://tools.ietf.org/html/rfc1777) - Lightweight Directory Access Protocol
+* [OpenLDAP](https://www.openldap.org)
 
-h3. So why use ActiveLdap?
+### So why use ActiveLdap?
 
 Using LDAP directly (even with the excellent Ruby/LDAP), leaves you bound to
 the world of the predefined LDAP API.  While this API is important for many
@@ -35,70 +36,68 @@ arrays of LDAP.mod entries make code harder to read, less intuitive, and just
 less fun to write.  Hopefully, ActiveLdap will remedy all of these
 problems!
 
-h2. Getting Started
+## Getting Started
 
-h3. Requirements
+### Requirements
 
-* A Ruby implementation: "Ruby":http://www.ruby-lang.org 1.8.x, 1.9.1 or "JRuby":http://jruby.codehaus.org/
-* A LDAP library: "Ruby/LDAP":http://code.google.com/p/ruby-activeldap/wiki/RubyLDAP (for Ruby), "Net::LDAP":http://rubyforge.org/projects/net-ldap/ (for Ruby or JRuby) or JNDI (for JRuby)
-* A LDAP server: "OpenLDAP":http://www.openldap.org, etc
-** Your LDAP server must allow root_dse queries to allow for schema queries
+* A Ruby implementation: [Ruby](https://www.ruby-lang.org) or [JRuby](https://www.jruby.org/)
+* A LDAP library: [Ruby/LDAP](https://rubygems.org/gems/ruby-ldap) (for Ruby), [Net::LDAP](https://rubygems.org/gems/net-ldap) (for Ruby or JRuby) or JNDI (for JRuby)
+* A LDAP server: [OpenLDAP](https://www.openldap.org/), etc
+  * Your LDAP server must allow `root_dse` queries to allow for schema queries
 
-h3. Installation
+### Installation
 
 Assuming all the requirements are installed, you can install by gem.
 
-<pre>
-!!!plain
+```console
 # gem install activeldap
-</pre>
+```
 
 Now as a quick test, you can run:
 
-<pre>
-$ irb -rubygems
+```console
+$ irb
 irb> require 'active_ldap'
 => true
 irb> exit
-</pre>
+```
 
 If the require returns false or an exception is raised, there has been a
-problem with the installation.  You may need to customize what setup.rb does on
-install.
+problem with the installation.
 
-h2. Usage
+## Usage
 
 This section covers using ActiveLdap from writing extension classes to
 writing applications that use them.
 
 Just to give a taste of what's to come, here is a quick example using irb:
 
-<pre>
+```text
 irb> require 'active_ldap'
-</pre>
+```
 
 Call setup_connection method  for connect to LDAP server. In this case, LDAP server
 is localhost, and base of LDAP tree is "dc=dataspill,dc=org".
 
-<pre>
+```text
 irb> ActiveLdap::Base.setup_connection :host => 'localhost', :base => 'dc=dataspill,dc=org'
-</pre>
+```
 
 Here's an extension class that maps to the LDAP Group objects:
 
-<pre>
+```text
 irb> class Group < ActiveLdap::Base
 irb*   ldap_mapping
 irb* end
-</pre>
+```
 
-In the above code, Group class handles sub tree of ou=Groups
-tha is :base value specified by setup_connection. A instance
-of Group class represents a LDAP object under ou=Gruops.
+In the above code, Group class handles sub tree of `ou=Groups`
+that is `:base` value specified by setup_connection. A instance
+of Group class represents a LDAP object under `ou=Groups`.
 
 Here is the Group class in use:
 
-<pre>
+```text
 # Get all group names
 irb> all_groups = Group.find(:all, '*').collect {|group| group.cn}
 => ["root", "daemon", "bin", "sys", "adm", "tty", ..., "develop"]
@@ -114,48 +113,47 @@ irb> group.cn
 # Get gid_number of the develop group
 irb> group.gid_number
 => "1003"
-</pre>
+```
 
 That's it! No let's get back in to it.
 
-h3. Extension Classes
+### Extension Classes
 
 Extension classes are classes that are subclassed from ActiveLdap::Base.  They
 are used to represent objects in your LDAP server abstractly.
 
-h4. Why do I need them?
+#### Why do I need them?
 
 Extension classes are what make ActiveLdap "active"! They do all the
 background work to make easy-to-use objects by mapping the LDAP object's
 attributes on to a Ruby class.
 
 
-h4. Special Methods
+#### Special Methods
 
 I will briefly talk about each of the methods you can use when defining an
 extension class.  In the above example, I only made one special method call
 inside the Group class. More than likely, you will want to more than that.
 
-h5. ldap_mapping
+##### `ldap_mapping`
 
 ldap_mapping is the only required method to setup an extension class for use
 with ActiveLdap. It must be called inside of a subclass as shown above.
 
 Below is a much more realistic Group class:
 
-<pre>
+```ruby
 class Group < ActiveLdap::Base
   ldap_mapping :dn_attribute => 'cn',
                :prefix => 'ou=Groups', :classes => ['top', 'posixGroup'],
                :scope => :one
 end
-</pre>
+```
 
 As you can see, this method is used for defining how this class maps in to LDAP.  Let's say that
 my LDAP tree looks something like this:
 
-<pre>
-!!!plain
+```text
 * dc=dataspill,dc=org
 |- ou=People,dc=dataspill,dc=org
 |+ ou=Groups,dc=dataspill,dc=org
@@ -163,26 +161,25 @@ my LDAP tree looks something like this:
    |- cn=develop,ou=Groups,dc=dataspill,dc=org
    |- cn=root,ou=Groups,dc=dataspill,dc=org
    |- ...
-</pre>
+```
 
 Under ou=People I store user objects, and under ou=Groups, I store group
-objects.  What |ldap_mapping| has done is mapped the class in to the LDAP tree
-abstractly. With the given :dn_attributes and :prefix, it will only work for
-entries under ou=Groups,dc=dataspill,dc=org using the primary attribute 'cn'
+objects.  What `ldap_mapping` has done is mapped the class in to the LDAP tree
+abstractly. With the given `:dn_attributes` and `:prefix`, it will only work for
+entries under `ou=Groups,dc=dataspill,dc=org` using the primary attribute 'cn'
 as the beginning of the distinguished name.
 
 Just for clarity, here's how the arguments map out:
 
-<pre>
-!!!plain
+```text
  cn=develop,ou=Groups,dc=dataspill,dc=org
  ^^         ^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
 :dn_attribute |         |
             :prefix     |
               :base from setup_connection
-</pre>
+```
 
-:scope tells ActiveLdap to only search under ou=Groups, and not to look deeper
+`:scope` tells ActiveLdap to only search under ou=Groups, and not to look deeper
 for dn_attribute matches.
 (e.g. cn=develop,ou=DevGroups,ou=Groups,dc=dataspill,dc=org)
 You can choose value from between :sub, :one and :base.
@@ -209,46 +206,45 @@ case, it would be 'ou=Groups'.
 :prefix.
 
 
-h5. belongs_to
+##### `belongs_to`
 
 This method allows an extension class to make use of other extension classes
 tying objects together across the LDAP tree. Often, user objects will be
 members of, or belong_to, Group objects.
 
-<pre>
-!!!plain
+```text
 * dc=dataspill,dc=org
 |+ ou=People,dc=dataspill,dc=org
  \
  |- uid=drewry,ou=People,dc=dataspill,dc=org
 |- ou=Groups,dc=dataspill,dc=org
-</pre>
+```
 
 
 In the above tree, one such example would be user 'drewry' who is a part of the
 group 'develop'. You can see this by looking at the 'memberUid' field of 'develop'.
 
-<pre>
+```text
 irb> develop = Group.find('develop')
 => ...
 irb> develop.memberUid
 => ['drewry', 'builder']
-</pre>
+```
 
 If we look at the LDAP entry for 'drewry', we do not see any references to
 group 'develop'. In order to remedy that, we can use belongs_to
 
-<pre>
+```text
 irb> class User < ActiveLdap::Base
 irb*   ldap_mapping :dn_attribute => 'uid', :prefix => 'ou=People', :classes => ['top','account']
 irb*   belongs_to :groups, :class_name => 'Group', :many => 'memberUid', :foreign_key => 'uid'
 irb* end
-</pre>
+```
 
 Now, class User will have a method called 'groups' which will retrieve all
 Group objects that a user is in.
 
-<pre>
+```text
 irb> me = User.find('drewry')
 irb> me.groups
 =>  #<ActiveLdap::Association::BelongsToMany...>    # Enumerable object
@@ -258,22 +254,22 @@ irb> me.groups.each { |group| p group.cn };nil
 "develop"
 => nil
 (Note: nil is just there to make the output cleaner...)
-</pre>
+```
 
 TIP: If you weren't sure what the distinguished name attribute was for Group,
 you could also do the following:
 
-<pre>
+```text
 irb> me.groups.each { |group| p group.id };nil
 "cdrom"
 "audio"
 "develop"
 => nil
-</pre>
+```
 
 Now let's talk about the arguments of belongs_to. We use the following code that extends Group group a bit for explain:
 
-<pre>
+```ruby
 class User < ActiveLdap::Base
   ldap_mapping :dn_attribute => 'uid', :prefix => 'People', :classes => ['top','account']
 
@@ -285,42 +281,42 @@ class User < ActiveLdap::Base
   belongs_to :groups,  :foreign_key => 'uid',
                :class_name => 'Group', :many => 'memberUid',
 end
-</pre>
+```
 
 The first argument is the name of the method you wish to create. In this case, we created a method called primary_group and groups using the symbol :primary_group and :groups. The next collection of arguments are actually a Hash (as with ldap_mapping).
 
-:foreign_key tells belongs_to what attribute Group objects have that match the related object's attribute. If :foreign_key is left off of the argument list, it is assumed to be the dn_attribute.
+`:foreign_key` tells `belongs_to` what attribute Group objects have that match the related object's attribute. If `:foreign_key` is left off of the argument list, it is assumed to be the dn_attribute.
 
 In the example, uid is used for :foreign_key. It may confuse you.
 
-ActiveLdap uses :foreign_key as "own attribute name". So it
-may not be "foreign key". You can consider :foreign_key just
+ActiveLdap uses `:foreign_key` as "own attribute name". So it
+may not be "foreign key". You can consider `:foreign_key` just
 as a relation key.
 
-:primary_key is treated as "related object's attribute name"
+`:primary_key` is treated as "related object's attribute name"
 as we discussed later.
 
-:class_name should be a string that has the name of a class
+`:class_name` should be a string that has the name of a class
 you've already included. If your class is inside of a module,
 be sure to put the whole name, e.g.
-@:class_name => "MyLdapModule::Group"@.
+`:class_name => "MyLdapModule::Group"`.
 
-:many and :primary_key are similar. Both of them specifies attribute name of related object specified by :foreign_key. Those values are attribute name that can be used by object of class specified by :class_name.
+`:many` and `:primary_key` are similar. Both of them specifies attribute name of related object specified by `:foreign_key`. Those values are attribute name that can be used by object of class specified by `:class_name`.
 
-Relation is resolved by searching entries of :class_name class with :foreign_key attribute value. Search target attribute for it is :primary_key or :many. primary_group method in the above example searches Group objects with User object's gidNumber value as Group object's gidNumber value. Matched Group objects are belonged objects.
+Relation is resolved by searching entries of `:class_name` class with `:foreign_key` attribute value. Search target attribute for it is `:primary_key` or `:many`. primary_group method in the above example searches Group objects with User object's gidNumber value as Group object's gidNumber value. Matched Group objects are belonged objects.
 
-:parimary_key is used for an object just belongs to an object. The first matched object is treated as beloned object.
+`:parimary_key` is used for an object just belongs to an object. The first matched object is treated as beloned object.
 
-:many is used for an object belongs to many objects. All of matched objects are treated as belonged objects.
+`:many` is used for an object belongs to many objects. All of matched objects are treated as belonged objects.
 
-h5. has_many
+##### `has_many`
 
 This method is the opposite of belongs_to. Instead of checking other objects in
 other parts of the LDAP tree to see if you belong to them, you have multiple
 objects from other trees listed in your object. To show this, we can just
 invert the example from above:
 
-<pre>
+```ruby
 class Group < ActiveLdap::Base
   ldap_mapping :dn_attribute => 'cn', :prefix => 'ou=Groups', :classes => ['top', 'posixGroup']
 
@@ -332,104 +328,104 @@ class Group < ActiveLdap::Base
   has_many :members,  :wrap => "memberUid",
            :class_name => "User",  :primary_key => 'uid'
 end
-</pre>
+```
 
 Now we can see that group develop has user 'drewry' as a member, and it can
-even return all responses in object form just like belongs_to methods.
+even return all responses in object form just like `belongs_to` methods.
 
-<pre>
+```text
 irb> develop = Group.find('develop')
 => ...
 irb> develop.members
 => #<ActiveLdap::Association::HasManyWrap:..> # Enumerable object
 irb> develop.members.map{|member| member.id}
 => ["drewry", "builder"]
-</pre>
+```
 
-The arguments for has_many follow the exact same idea that belongs_to's
+The arguments for `has_many` follow the exact same idea that `belongs_to`'s
 arguments followed. :wrap's contents are used to search for matching
-:primary_key content.  If :primary_key is not specified, it defaults to the
-dn_attribute of the specified :class_name.
+`:primary_key` content.  If `:primary_key` is not specified, it defaults to the
+dn_attribute of the specified `:class_name`.
 
-h3. Using these new classes
+### Using these new classes
 
 These new classes have many method calls. Many of them are automatically
 generated to provide access to the LDAP object's attributes. Other were defined
-during class creation by special methods like belongs_to. There are a few other
+during class creation by special methods like `belongs_to`. There are a few other
 methods that do not fall in to these categories.
 
-h4. .find
+#### `.find`
 
-.find is a class method that is accessible from
+`.find` is a class method that is accessible from
 any subclass of Base that has 'ldap_mapping' called. When
-called .first(:first) returns the first match of the given class.
+called `.first(:first)` returns the first match of the given class.
 
-<pre>
+```text
 irb> Group.find(:first, 'deve*").cn
 => "develop"
-</pre>
+```
 
 In this simple example, Group.find took the search string of 'deve*' and
 searched for the first match in Group where the dn_attribute matched the
 query. This is the simplest example of .find.
 
-<pre>
+```text
 irb> Group.find(:all).collect {|group| group.cn}
 => ["root", "daemon", "bin", "sys", "adm", "tty", ..., "develop"]
-</pre>
+```
 
 Here .find(:all) returns all matches to the same query.  Both .find(:first) and
 .find(:all) also can take more expressive arguments:
 
-<pre>
+```text
 irb> Group.find(:all, :attribute => 'gidNumber', :value => '1003').collect {|group| group.cn}
 => ["develop"]
-</pre>
+```
 
 So it is pretty clear what :attribute and :value do - they are used to query as
-:attribute=:value.
+`:attribute=:value`.
 
 If :attribute is unspecified, it defaults to the dn_attribute.
 
 It is also possible to override :attribute and :value by specifying :filter. This
 argument allows the direct specification of a LDAP filter to retrieve objects by.
 
-h5. Using the :filter option
+##### Using the :filter option
 
 The filter option lets you pass in an LDAP query string.
 For example retrieving all groups with cn which starts with @'dev'@ and has @guid@ == 1:
 
-<pre>
+```text
 irb> Group.find(:all, :filter => '(&(cn=dev*)(guid=1))').collect {|group| group.cn}
 => ["develop"]
-</pre>
+```
 
 It also allows a hash like sintax (sparing you the need to write the query by hand ):
 
-<pre>
+```text
 irb> Group.find(:all, :filter => {:cn => 'dev*', :guid => 1 }).collect {|group| group.cn}
 => ["develop", "developers", "sys", "sysadmin"]
-</pre>
+```
 
 You can build complex queries combining the hash syntax with arrays and @:or@ and @:and@ operators retrieving all users whose name contains 'john' or cn ends with 'smith' or contains 'liz'
 
-<pre>
+```text
 irb> User.find(:all, filter: [:or, [:or, { :cn => '*smith', :name => '*john*'} ], { cn: '*liz*' }]).collect(&:cn)
 => ['john.smith', 'jane.smith', 'john tha ripper', 'liz.taylor', ...]
-</pre>
+```
 
-h4. .search
+#### .search
 
 .search is a class method that is accessible from any subclass of Base, and Base.
 It lets the user perform an arbitrary search against the current LDAP connection
 irrespetive of LDAP mapping data.  This is meant to be useful as a utility method
 to cover 80% of the cases where a user would want to use Base.connection directly.
 
-<pre>
+```text
 irb> Base.search(:base => 'dc=example,dc=com', :filter => '(uid=roo*)',
                  :scope => :sub, :attributes => ['uid', 'cn'])
 =>  [["uid=root,ou=People,dc=dataspill,dc=org",{"cn"=>["root"], "uidNumber"=>["0"]}]
-</pre>
+```
 
 You can specify the :filter, :base, :scope, and :attributes, but they all have defaults --
 * :filter defaults to objectClass=* - usually this isn't what you want
@@ -437,41 +433,41 @@ You can specify the :filter, :base, :scope, and :attributes, but they all have d
 * :scope defaults to :sub. Usually you won't need to change it (You can choose value also from between :one and :base)
 * :attributes defaults to [] and is the list of attributes you want back. Empty means all of them.
 
-h4. #valid?
+#### #valid?
 
 valid? is a method that verifies that all attributes that are required by the
 objects current objectClasses are populated.
 
-h4. #save
+#### #save
 
 save is a method that writes any changes to an object back to the LDAP server.
 It automatically handles the addition of new objects, and the modification of
 existing ones.
 
-h4. .exists?
+#### .exists?
 
 exists? is a simple method which returns true is the current object exists in
 LDAP, or false if it does not.
 
-<pre>
+```text
 irb> User.exists?("dshadsadsa")
 => false
-</pre>
+```
 
 
-h3. ActiveLdap::Base
+### ActiveLdap::Base
 
 ActiveLdap::Base has come up a number of times in the examples above.  Every
 time, it was being used as the super class for the wrapper objects. While this
 is it's main purpose, it also handles quite a bit more in the background.
 
-h4. What is it?
+#### What is it?
 
 ActiveLdap::Base is the heart of ActiveLdap.  It does all the schema
 parsing for validation and attribute-to-method mangling as well as manage the
 connection to LDAP.
 
-h5. setup_connection
+##### setup_connection
 
 Base.setup_connection takes many (optional) arguments and is used to
 connect to the LDAP server. Sometimes you will want to connect anonymously
@@ -485,7 +481,7 @@ server allows anonymous binding, and you only want to access data in a
 read-only fashion, you won't need to call Base.setup_connection. Here
 is a fully parameterized call:
 
-<pre>
+```ruby
 Base.setup_connection(
   :host => 'ldap.dataspill.org',
   :port => 389,
@@ -496,7 +492,7 @@ Base.setup_connection(
   :allow_anonymous => false,
   :try_sasl => false
 )
-</pre>
+```
 
 There are quite a few arguments, but luckily many of them have safe defaults:
 * :host defaults to "127.0.0.1".
@@ -550,51 +546,51 @@ in an internal class variable which is used to cache the
 information without ditching the defaults passed in from
 configuration.rb
 
-h5. connection
+##### connection
 
 Base.connection returns the ActiveLdap::Connection object.
 
-h3. Exceptions
+### Exceptions
 
 There are a few custom exceptions used in ActiveLdap. They are detailed below.
 
-h4. DeleteError
+#### DeleteError
 
 This exception is raised when #delete fails. It will include LDAP error
 information that was passed up during the error.
 
-h4. SaveError
+#### SaveError
 
 This exception is raised when there is a problem in #save updating or creating
 an LDAP entry.  Often the error messages are cryptic. Looking at the server
 logs or doing an "Wireshark":http://www.wireshark.org dump of the connection will
 often provide better insight.
 
-h4. AuthenticationError
+#### AuthenticationError
 
 This exception is raised during Base.setup_connection if no valid authentication methods
 succeeded.
 
-h4. ConnectionError
+#### ConnectionError
 
 This exception is raised during Base.setup_connection if no valid
 connection to the LDAP server could be created. Check you 
 Base.setup_connection arguments, and network connectivity! Also check
 your LDAP server logs to see if it ever saw the request.
 
-h4. ObjectClassError
+#### ObjectClassError
 
 This exception is raised when an object class is used that is not defined
 in the schema.
 
-h3. Others
+### Others
 
 Other exceptions may be raised by the Ruby/LDAP module, or by other subsystems.
 If you get one of these exceptions and think it should be wrapped, write me an
 email and let me know where it is and what you expected. For faster results,
 email a patch!
 
-h3. Putting it all together
+### Putting it all together
 
 Now that all of the components of ActiveLdap have been covered, it's time
 to put it all together! The rest of this section will show the steps to setup
@@ -603,43 +599,42 @@ above.
 
 All of the scripts here are in the package's examples/ directory.
 
-h4. Setting up
+#### Setting up
 
 Create directory for scripts.
 
-<pre>
-!!!plain
+```console
 % mkdir -p ldapadmin/objects
-</pre>
+```
 
 In ldapadmin/objects/ create the file user.rb:
 
-<pre>
+```ruby
 require 'objects/group'
 
 class User < ActiveLdap::Base
   ldap_mapping :dn_attribute => 'uid', :prefix => 'ou=People', :classes => ['person', 'posixAccount']
   belongs_to :groups, :class_name => 'Group', :many => 'memberUid'
 end
-</pre>
+```
 
 In ldapadmin/objects/ create the file group.rb:
 
-<pre>
+```ruby
 class Group < ActiveLdap::Base
   ldap_mapping :classes => ['top', 'posixGroup'], :prefix => 'ou=Groups'
   has_many :members, :class_name => "User", :wrap => "memberUid"
   has_many :primary_members, :class_name => 'User', :foreign_key => 'gidNumber', :primary_key => 'gidNumber'
 end
-</pre>
+```
 
 Now, we can write some small scripts to do simple management tasks.
 
-h4. Creating LDAP entries
+#### Creating LDAP entries
 
 Now let's create a really dumb script for adding users - ldapadmin/useradd:
 
-<pre>
+```ruby
 #!/usr/bin/ruby -W0
 
 base = File.expand_path(File.join(File.dirname(__FILE__), ".."))
@@ -686,13 +681,13 @@ unless user.save
   puts user.errors.full_messages
   exit 1
 end
-</pre>
+```
 
-h4. Managing LDAP entries
+#### Managing LDAP entries
 
 Now let's create another dumb script for modifying users - ldapadmin/usermod:
 
-<pre>
+```ruby
 #!/usr/bin/ruby -W0
 
 base = File.expand_path(File.join(File.dirname(__FILE__), ".."))
@@ -736,13 +731,13 @@ unless user.save
   puts user.errors.full_messages
   exit 1
 end
-</pre>
+```
 
-h4. Removing LDAP entries
+#### Removing LDAP entries
 
 Now let's create more one for deleting users - ldapadmin/userdel:
 
-<pre>
+```ruby
 #!/usr/bin/ruby -W0
 
 base = File.expand_path(File.join(File.dirname(__FILE__), ".."))
@@ -778,20 +773,20 @@ unless User.exists?(name)
 end
 
 User.destroy(name)
-</pre>
+```
 
-h3. Advanced Topics
+### Advanced Topics
 
 Below are some situation tips and tricks to get the most out of ActiveLdap.
 
 
-h4. Binary data and other subtypes
+#### Binary data and other subtypes
 
 Sometimes, you may want to store attributes with language specifiers, or
 perhaps in binary form.  This is (finally!) fully supported.  To do so,
 follow the examples below:
 
-<pre>
+```text
 irb> user = User.new('drewry')
 => ...
 # This adds a cn entry in lang-en and whatever the server default is.
@@ -803,7 +798,7 @@ irb> user.cn
 irb> user.user_certificate = File.read('example.der')
 => ...
 irb> user.save
-</pre>
+```
 
 So that's a lot to take in. Here's what is going on. I just set the LDAP
 object's cn to "wad" and cn:lang-en-us to ["wad", "Will Drewry"].
@@ -815,9 +810,9 @@ get wrapped in @{'binary' => value}@ if you don't do it. This keeps your #writes
 from breaking, and my code from crying.  For correctness, I could have easily
 done the following:
 
-<pre>
+```text
 irb> user.user_certificate = {'binary' => File.read('example.der')}
-</pre>
+```
 
 You should note that some binary data does not use the binary subtype all the time.
 One example is jpegPhoto. You can use it as jpegPhoto;binary or just as jpegPhoto.
@@ -829,9 +824,9 @@ LDAP site policy and not by any programmatic means.
 The only subtypes defined in LDAPv3 are lang-* and binary.  These can be nested
 though:
 
-<pre>
+```text
 irb> user.cn = [{'lang-ja' => {'binary' => 'some Japanese'}}]
-</pre>
+```
 
 As I understand it, OpenLDAP does not support nested subtypes, but some
 documentation I've read suggests that Netscape's LDAP server does. I only
@@ -841,7 +836,7 @@ goes!
 
 And that pretty much wraps up this section.
 
-h4. Further integration with your environment aka namespacing
+#### Further integration with your environment aka namespacing
 
 If you want this to cleanly integrate into your system-wide Ruby include path,
 you should put your extension classes inside a custom module.
@@ -851,28 +846,28 @@ Example:
 
 ./myldap.rb:
 
-<pre>
+```ruby
 require 'active_ldap'
 require 'myldap/user'
 require 'myldap/group'
 module MyLDAP
 end
-</pre>
+```
 
 ./myldap/user.rb:
 
-<pre>
+```ruby
 module MyLDAP
   class User < ActiveLdap::Base
     ldap_mapping :dn_attribute => 'uid', :prefix => 'ou=People', :classes => ['top', 'account', 'posixAccount']
     belongs_to :groups, :class_name => 'MyLDAP::Group', :many => 'memberUid'
   end
 end
-</pre>
+```
 
 ./myldap/group.rb:
 
-<pre>
+```ruby
 module MyLDAP
   class Group < ActiveLdap::Base
     ldap_mapping :classes => ['top', 'posixGroup'], :prefix => 'ou=Groups'
@@ -880,54 +875,54 @@ module MyLDAP
     has_many :primary_members, :class_name => 'MyLDAP::User', :foreign_key => 'gidNumber', :primary_key => 'gidNumber'
   end
 end
-</pre>
+```
 
 Now in your local applications, you can call
 
-<pre>
+```ruby
 require 'myldap'
 
 MyLDAP::Group.new('foo')
 ...
-</pre>
+```
 
 and everything should work well.
 
 
-h4. force array results for single values
+#### force array results for single values
 
 Even though ActiveLdap attempts to maintain programmatic ease by
 returning Array values only. By specifying 'true' as an argument to
 any attribute method you will get back a Array if it is single value.
 Here's an example:
 
-<pre>
+```text
 irb> user = User.new('drewry')
 => ...
 irb> user.cn(true)
 => ["Will Drewry"]
-</pre>
+```
 
-h4. Dynamic attribute crawling
+#### Dynamic attribute crawling
 
 If you use tab completion in irb, you'll notice that you /can/ tab complete the dynamic
 attribute methods. You can still see which methods are for attributes using
 Base#attribute_names:
 
-<pre>
+```text
 irb> d = Group.new('develop')
 => ...
 irb> d.attribute_names
 => ["gidNumber", "cn", "memberUid", "commonName", "description", "userPassword", "objectClass"]
-</pre>
+```
 
 
-h4. Juggling multiple LDAP connections
+#### Juggling multiple LDAP connections
 
 In the same vein as the last tip, you can use multiple LDAP connections by
 per class as follows:
 
-<pre>
+```text
 irb> anon_class = Class.new(Base)
 => ...
 irb> anon_class.setup_connection
@@ -936,11 +931,11 @@ irb> auth_class = Class.new(Base)
 => ...
 irb> auth_class.setup_connection(:password_block => lambda{'mypass'})
 => ...
-</pre>
+```
 
 This can be useful for doing authentication tests and other such tricks.
 
-h4. :try_sasl
+#### :try_sasl
 
 If you have the Ruby/LDAP package with the SASL/GSSAPI patch from Ian
 MacDonald's web site, you can use Kerberos to bind to your LDAP server. By
@@ -949,7 +944,7 @@ default, :try_sasl is false.
 Also note that you must be using OpenLDAP 2.1.29 or higher to use SASL/GSSAPI
 due to some bugs in older versions of OpenLDAP.
 
-h4. Don't be afraid! [Internals]
+#### Don't be afraid! [Internals]
 
 Don't be afraid to add more methods to the extensions classes and to
 experiment. That's exactly how I ended up with this package. If you come up
@@ -959,7 +954,7 @@ The internal structure of ActiveLdap::Base, and thus all its subclasses, is
 still in flux. I've tried to minimize the changes to the overall API, but
 the internals are still rough around the edges.
 
-h5. Where's ldap_mapping data stored? How can I get to it?
+##### Where's ldap_mapping data stored? How can I get to it?
 
 When you call ldap_mapping, it overwrites several class methods inherited
 from Base:
@@ -974,7 +969,7 @@ from any new instance methods you define:
 * Base#required_classes()
 * Base#dn_attribute()
 
-h5. What else?
+##### What else?
 
 Well if you want to use the LDAP connection for anything, I'd suggest still
 calling Base.connection to get it. There really aren't many other internals
@@ -987,12 +982,12 @@ any methods you write might need to figure it out. I'd suggest just
 calling self[attribname] to get the value, but if that's not good enough,
 you can call look up the stored name by #to_real_attribute_name as follows:
 
-<pre>
+```text
 irb> User.find(:first).instance_eval do
 irb>   to_real_attribute_name('commonName')
 irb> end
 => 'cn'
-</pre>
+```
 
 This tells you the name the attribute is stored in behind the scenes (@data).
 Again, self[attribname] should be enough for most extensions, but if not,
@@ -1001,16 +996,16 @@ it's probably safe to dabble here.
 Also, if you like to look up all aliases for an attribute, you can call the
 following:
 
-<pre>
+```text
 irb> User.schema.attribute_type 'cn', 'NAME'
 => ["cn", "commonName"]
-</pre>
+```
 
 This is discovered automagically from the LDAP server's schema.
 
-h2. Limitations
+## Limitations
 
-h3. Speed
+### Speed
 
 Currently, ActiveLdap could be faster.  I have some recursive type
 checking going on which slows object creation down, and I'm sure there
@@ -1018,7 +1013,7 @@ are many, many other places optimizations can be done.  Feel free
 to send patches, or just hang in there until I can optimize away the
 slowness.
 
-h2. Feedback
+## Feedback
 
 Any and all feedback and patches are welcome. I am very excited about this
 package, and I'd like to see it prove helpful to more people than just myself.