Completed YAML Scanner (closes #34).

YAML Scanner:
* Added another example (multiline).
* Added multiline string recognition.
* This should be enough for most people.

Else:
* New method: Scanner#column (very useful and fast!)
* Added new token type :doctype, used also by HTML scanner.
* coderay_suite: minor output tweaks.

1 files changed, 365 insertions, 365 deletions

diff --git a/test/scanners/yaml/faq.expected.raydebug b/test/scanners/yaml/faq.expected.raydebug
index 77b9b30..96af243 100644
--- a/test/scanners/yaml/faq.expected.raydebug
+++ b/test/scanners/yaml/faq.expected.raydebug
@@ -1,492 +1,492 @@
 head<head(---)>
 operator(-) key<delimiter(")content(What is a...)delimiter(")>operator(:)
-  operator(-) key<delimiter(")content(container?)delimiter(")>operator(:) string(>-)
-      string(A _container_ is collection of service points and other containers. It)
-      string(is used to organize services. Each container has access to all of the)
-      string(service points in its ancestor containers.)
-
-  operator(-) key<delimiter(")content(registry?)delimiter(")>operator(:) string(>-)
-      string(A _registry_ is a special kind of container that has no parent container.)
-      string(It also defines a few services (such as the LoggingInterceptor, and)
-      string(the various service models and pipeline elements\), so that they are)
-      string(available by default to all of the services it contains.)
-
-  operator(-) key<delimiter(")content(service point?)delimiter(")>operator(:) string(>-)
-      string(A _service point_ is the definition of a service. Just as a class is the)
-      string(definition of an object, and you instantiate an object from a class, so)
-      string(do you instantiate services from service points.)
-
-  operator(-) key<delimiter(")content(service?)delimiter(")>operator(:) string(>-)
-      string(A _service_ is the instantiation of a service point.)
-
-  operator(-) key<delimiter(")content(parameterized service?)delimiter(")>operator(:) string(>-)
-      string(A _parameterized_ service is a service that allows contextual parameters)
-      string(to be passed to the service when it is created. Such services are)
-      string(typically used in conjunction with the @multiton@ service model, but)
-      string(the only real requirement is that they _not_ be used with a service model)
-      string(that does not support multiple parameters (like @singleton@ or)
-      string(@threaded@\).)
-
-  operator(-) key<delimiter(")content(service model?)delimiter(")>operator(:) string(>-)
-      string(A _service model_ is a description of the lifecycle of a service. By)
-      string(default, all services are _singletons_, meaning that every time you ask)
-      string(a container for a particular service, you'll get the same object)
-      string(instance back.)
-
-
-      string(There are other service models available, though, including "prototype")
-      string((which returns a new instance for each request of a service\) and)
-      string("deferred" (which returns a proxy, deferring the instatiation of the)
-      string(service itself until a method is invoked on the service\). )
-
-  operator(-) key<delimiter(")content(interceptor?)delimiter(")>operator(:) string(>-)
-      string(An _interceptor_ is an object that may be placed between the client and)
-      string(a service. Every request to the service is thus _intercepted_ by that)
-      string(object, which can do operations on the request (such as logging\) and may)
-      string(even reroute or ignore the request altogether. This provides a kind of)
-      string("poor man's AOP", since you can do "before", "after", and "around" advice)
-      string(on the methods of a service.)
-
-
-      string(Needle comes with one standard interceptor, the LoggingInterceptor. It)
-      string(will log a message on method entry and exit, and also when an exception)
-      string(is raised.)
-
-  operator(-) key<delimiter(")content(pipeline?)delimiter(")>operator(:) string(>-)
-      string(In Needle, the _instantiation pipeline_ is used to control how and when)
-      string(services are instantiated. The _service models_ are implemented as)
-      string(pipelines.)
-
-
-      string(Just as the _interceptors_ are for hooking into method invocations, the)
-      string(pipelines are for hooking into service instantiations. Every time a)
-      string(service is requested, it's instantiation pipeline is executed. By)
-      string(choosing the appropriate kinds of pipeline elements, all of the available)
-      string(service models can be implemented (prototype, prototype_deferred,)
-      string(singleton, singleton_deferred, etc.\).)
+  operator(-) key<delimiter(")content(container?)delimiter(")>operator(:) string<delimiter(>-)content(
+      A _container_ is collection of service points and other containers. It
+      is used to organize services. Each container has access to all of the
+      service points in its ancestor containers.)>
+
+  operator(-) key<delimiter(")content(registry?)delimiter(")>operator(:) string<delimiter(>-)content(
+      A _registry_ is a special kind of container that has no parent container.
+      It also defines a few services (such as the LoggingInterceptor, and
+      the various service models and pipeline elements\), so that they are
+      available by default to all of the services it contains.)>
+
+  operator(-) key<delimiter(")content(service point?)delimiter(")>operator(:) string<delimiter(>-)content(
+      A _service point_ is the definition of a service. Just as a class is the
+      definition of an object, and you instantiate an object from a class, so
+      do you instantiate services from service points.)>
+
+  operator(-) key<delimiter(")content(service?)delimiter(")>operator(:) string<delimiter(>-)content(
+      A _service_ is the instantiation of a service point.)>
+
+  operator(-) key<delimiter(")content(parameterized service?)delimiter(")>operator(:) string<delimiter(>-)content(
+      A _parameterized_ service is a service that allows contextual parameters
+      to be passed to the service when it is created. Such services are
+      typically used in conjunction with the @multiton@ service model, but
+      the only real requirement is that they _not_ be used with a service model
+      that does not support multiple parameters (like @singleton@ or
+      @threaded@\).)>
+
+  operator(-) key<delimiter(")content(service model?)delimiter(")>operator(:) string<delimiter(>-)content(
+      A _service model_ is a description of the lifecycle of a service. By
+      default, all services are _singletons_, meaning that every time you ask
+      a container for a particular service, you'll get the same object
+      instance back.
+
+
+      There are other service models available, though, including "prototype"
+      (which returns a new instance for each request of a service\) and
+      "deferred" (which returns a proxy, deferring the instatiation of the
+      service itself until a method is invoked on the service\). )>
+
+  operator(-) key<delimiter(")content(interceptor?)delimiter(")>operator(:) string<delimiter(>-)content(
+      An _interceptor_ is an object that may be placed between the client and
+      a service. Every request to the service is thus _intercepted_ by that
+      object, which can do operations on the request (such as logging\) and may
+      even reroute or ignore the request altogether. This provides a kind of
+      "poor man's AOP", since you can do "before", "after", and "around" advice
+      on the methods of a service.
+
+
+      Needle comes with one standard interceptor, the LoggingInterceptor. It
+      will log a message on method entry and exit, and also when an exception
+      is raised.)>
+
+  operator(-) key<delimiter(")content(pipeline?)delimiter(")>operator(:) string<delimiter(>-)content(
+      In Needle, the _instantiation pipeline_ is used to control how and when
+      services are instantiated. The _service models_ are implemented as
+      pipelines.
+
+
+      Just as the _interceptors_ are for hooking into method invocations, the
+      pipelines are for hooking into service instantiations. Every time a
+      service is requested, it's instantiation pipeline is executed. By
+      choosing the appropriate kinds of pipeline elements, all of the available
+      service models can be implemented (prototype, prototype_deferred,
+      singleton, singleton_deferred, etc.\).)>
 
 operator(-) key<delimiter(")content(How do I...)delimiter(")>operator(:)
-  operator(-) key<delimiter(")content(create a new registry?)delimiter(")>operator(:) string(>-)
-      string(There are several ways to create a new registry. The simplist is just to)
-      string(invoke Registry#new.)
+  operator(-) key<delimiter(")content(create a new registry?)delimiter(")>operator(:) string<delimiter(>-)content(
+      There are several ways to create a new registry. The simplist is just to
+      invoke Registry#new.
 
 
-      string(<pre>)
-        string(reg = Needle::Registry.new)
-      string(</pre>)
+      <pre>
+        reg = Needle::Registry.new
+      </pre>
 
 
-      string(This will create a new Registry instance. You can also send a block to)
-      comment(#new, in which case the new registry will be yielded to it:)
+      This will create a new Registry instance. You can also send a block to
+      #new, in which case the new registry will be yielded to it:
 
 
-      string(<pre>)
-        string(reg = Needle::Registry.new do |r|)
-          string(...)
-        string(end)
-      string(</pre>)
+      <pre>
+        reg = Needle::Registry.new do |r|
+          ...
+        end
+      </pre>
 
 
-      string(There are two other factory methods you can use for creating a Registry)
-      string(instance. Both require a block.)
+      There are two other factory methods you can use for creating a Registry
+      instance. Both require a block.
 
 
-      string(<pre>)
-        string(r1 = Needle::Registry.define do |builder|)
-          string(...)
-        string(end)
+      <pre>
+        r1 = Needle::Registry.define do |builder|
+          ...
+        end
 
-        string(r2 = Needle::Registry.define! do)
-          string(...)
-        string(end)
-      string(</pre>)
+        r2 = Needle::Registry.define! do
+          ...
+        end
+      </pre>
 
 
-      string(Registry#define creates a "builder" object that you can use define)
-      string(services more conveniently. Register#define! (with a bang\) does the same)
-      string(thing, but evaluates the block within the context of the builder.)
+      Registry#define creates a "builder" object that you can use define
+      services more conveniently. Register#define! (with a bang\) does the same
+      thing, but evaluates the block within the context of the builder.)>
 
-  operator(-) key<delimiter(")content(register a service?)delimiter(")>operator(:) string(>-)
-      string(The first way to register a service is by calling #register on the)
-      key(registry (or a namespace\))operator(:)
+  operator(-) key<delimiter(")content(register a service?)delimiter(")>operator(:) string<delimiter(>-)content(
+      The first way to register a service is by calling #register on the
+      registry (or a namespace\):
 
 
-      string(<pre>)
-        string(reg.register( :foo \) { Foo.new })
-      string(</pre>)
+      <pre>
+        reg.register( :foo \) { Foo.new }
+      </pre>
 
 
-      string(The (first\) parameter to #register is the name of the service, and the)
-      string(block should return the implementation of the service. If needed, the)
-      string(block can accept two parameters--the container that the service is being)
-      string(registered with, and an object that represents the service being defined)
-      string((called a "service point"\):)
+      The (first\) parameter to #register is the name of the service, and the
+      block should return the implementation of the service. If needed, the
+      block can accept two parameters--the container that the service is being
+      registered with, and an object that represents the service being defined
+      (called a "service point"\):
 
 
-      string(<pre>)
-        string(reg.register( :foo \) do |container,point|)
-          string(Foo.new( container[:bar], point.fullname \))
-        string(end)
-      string(</pre>)
+      <pre>
+        reg.register( :foo \) do |container,point|
+          Foo.new( container[:bar], point.fullname \)
+        end
+      </pre>
 
 
-      string(You can also use Container#define and Container#define! to register)
-      string(services.  These approaches are friendlier if you are needing to register)
-      string(several services at once.)
+      You can also use Container#define and Container#define! to register
+      services.  These approaches are friendlier if you are needing to register
+      several services at once.
 
 
-      string(<pre>)
-        string(reg.define do |builder|)
-          string(builder.foo { Foo.new })
-          string(builder.bar { |c,p| Bar.new( c[:foo], p.name \) })
-        string(end)
+      <pre>
+        reg.define do |builder|
+          builder.foo { Foo.new }
+          builder.bar { |c,p| Bar.new( c[:foo], p.name \) }
+        end
 
-        string(reg.define! do)
-          string(baz { |c,p| Baz.new( c[:bar], p.name \) })
-          string(zoom { Buggy.new })
-        string(end)
-      string(</pre>)
+        reg.define! do
+          baz { |c,p| Baz.new( c[:bar], p.name \) }
+          zoom { Buggy.new }
+        end
+      </pre>
 
 
-      string(Container#define yields a new "builder" object to the block. Messages)
-      string(sent to the builder are interpreted as service names, and if a block is)
-      string(sent with the message, a new service is registered under that name.)
+      Container#define yields a new "builder" object to the block. Messages
+      sent to the builder are interpreted as service names, and if a block is
+      sent with the message, a new service is registered under that name.
 
       
-      string(Container#define! does likewise, except it evaluates the block within the)
-      string(context of the builder object.)
+      Container#define! does likewise, except it evaluates the block within the
+      context of the builder object.
 
 
-      string(If you do not pass a block to #define, it will return the builder object,)
-      string(so you could do something like the following if you only need to define)
-      key(one or two services)operator(:)
+      If you do not pass a block to #define, it will return the builder object,
+      so you could do something like the following if you only need to define
+      one or two services:
 
 
-      string(<pre>)
-        string(reg.define.foo { ... })
-      string(</pre>)
+      <pre>
+        reg.define.foo { ... }
+      </pre>
 
 
-      string(Lastly, you can get the builder directly and add services using it:)
+      Lastly, you can get the builder directly and add services using it:
 
 
-      string(<pre>)
-        string(builder = reg.builder)
-        string(builder.baz { ... })
-        string(builder.bar { ... })
-      string(</pre>)
+      <pre>
+        builder = reg.builder
+        builder.baz { ... }
+        builder.bar { ... }
+      </pre>
 
 
-      string((This last is the same as calling #define without arguments, but is more)
-      string(readable if you intend to use the builder object multiple times.\))
-      
-  operator(-) key<delimiter(")content(reference a service?)delimiter(")>operator(:) string(>-)
-      string(Referencing a service can be done in either of two ways. The first is to)
-      string(treat the container (i.e., registry\) as a hash, passing the name of the)
-      string(service as an argument to Container#[]:)
+      (This last is the same as calling #define without arguments, but is more
+      readable if you intend to use the builder object multiple times.\)
+      )>
+  operator(-) key<delimiter(")content(reference a service?)delimiter(")>operator(:) string<delimiter(>-)content(
+      Referencing a service can be done in either of two ways. The first is to
+      treat the container (i.e., registry\) as a hash, passing the name of the
+      service as an argument to Container#[]:
 
 
-      string(<pre>)
-        string(svc = registry[:foo])
-        string(svc.do_something_interesting)
-      string(</pre>)
+      <pre>
+        svc = registry[:foo]
+        svc.do_something_interesting
+      </pre>
 
 
-      string(A more convenient (but slightly more peril-fraught\) approach is to send)
-      key(the name of the method to the registry as a message)operator(:)
+      A more convenient (but slightly more peril-fraught\) approach is to send
+      the name of the method to the registry as a message:
 
 
-      string(<pre>)
-        string(svc = registry.foo)
-      string(</pre>)
+      <pre>
+        svc = registry.foo
+      </pre>
 
 
-      string(Be aware that this latter approach will only work when the service name)
-      string(does not conflict with the name of an existing method on the container.)
-      string(For example, if you were to do:)
+      Be aware that this latter approach will only work when the service name
+      does not conflict with the name of an existing method on the container.
+      For example, if you were to do:
 
 
-      string(<pre>)
-        string(registry.register( :hash \) { "hello, world" })
-        string(p registry.hash)
-      string(</pre>)
+      <pre>
+        registry.register( :hash \) { "hello, world" }
+        p registry.hash
+      </pre>
 
 
-      string(You would get the hash value of the registry object, instead of the value)
-      string(value of the service (which would be "hello, world"\).)
+      You would get the hash value of the registry object, instead of the value
+      value of the service (which would be "hello, world"\).)>
 
-  operator(-) key<delimiter(")content(select a service model for a service (i.e., change the default model of lifecycle management\)?)delimiter(")>operator(:) string(>-)
-      string(By default, a service will be managed as a singleton, i.e., every request)
-      string(of that service will return the same object instance. This is the)
-      string(_singleton_ service model.)
+  operator(-) key<delimiter(")content(select a service model for a service (i.e., change the default model of lifecycle management\)?)delimiter(")>operator(:) string<delimiter(>-)content(
+      By default, a service will be managed as a singleton, i.e., every request
+      of that service will return the same object instance. This is the
+      _singleton_ service model.
 
 
-      string(To select a different service model, pass it as an option when you)
-      key(register the service)operator(:)
+      To select a different service model, pass it as an option when you
+      register the service:
 
 
-      string(<pre>)
-        string(registry.register( :foo, :model => :prototype \) {...})
-        string(registry.define.bar( :model => :threaded \) {...})
-        string(registry.define! do)
-          string(baz( :model => :singleton_deferred \) {...})
-          string(...)
-        string(end)
-        string(...)
-      string(</pre>)
+      <pre>
+        registry.register( :foo, :model => :prototype \) {...}
+        registry.define.bar( :model => :threaded \) {...}
+        registry.define! do
+          baz( :model => :singleton_deferred \) {...}
+          ...
+        end
+        ...
+      </pre>)>
 
-  operator(-) key<delimiter(")content(create a namespace?)delimiter(")>operator(:) string(>-)
-      string(Namespaces allow you to organize your services into hierarchical)
-      string(packages. You can create namespaces in a few ways. The first (and)
-      string(simplest\) is to just call Container#namespace:)
+  operator(-) key<delimiter(")content(create a namespace?)delimiter(")>operator(:) string<delimiter(>-)content(
+      Namespaces allow you to organize your services into hierarchical
+      packages. You can create namespaces in a few ways. The first (and
+      simplest\) is to just call Container#namespace:
 
 
-      string(<pre>)
-        string(registry.namespace( :stuff \))
-      string(</pre>)
+      <pre>
+        registry.namespace( :stuff \)
+      </pre>
 
 
-      string(This will create a namespace in the registry, called stuff. If you send a)
-      string(block as well, the block will be invoked (with the new namespace yielded)
-      key(to it\) the first time the namespace is requested)operator(:)
+      This will create a namespace in the registry, called stuff. If you send a
+      block as well, the block will be invoked (with the new namespace yielded
+      to it\) the first time the namespace is requested:
 
 
-      string(<pre>)
-        string(registry.namespace( :stuff \) do |ns|)
-          string(ns.register( :foo \) {...})
-          string(ns.define.bar {...})
-          string(ns.define! do)
-            string(baz {...})
-            string(buf {...})
-          string(end)
-        string(end)
-      string(</pre>)
+      <pre>
+        registry.namespace( :stuff \) do |ns|
+          ns.register( :foo \) {...}
+          ns.define.bar {...}
+          ns.define! do
+            baz {...}
+            buf {...}
+          end
+        end
+      </pre>
 
-      string(Because it is so common to immediately define services on the new)
-      string(namespace, there are some convenience methods to make this more...)
-      string(convenient.)
+      Because it is so common to immediately define services on the new
+      namespace, there are some convenience methods to make this more...
+      convenient.
 
 
-      string(<pre>)
-        string(registry.namespace_define!( :stuff \) do)
-          string(foo {...})
-          string(bar {...})
-          string(baz {...})
-        string(end)
+      <pre>
+        registry.namespace_define!( :stuff \) do
+          foo {...}
+          bar {...}
+          baz {...}
+        end
 
-        string(registry.namespace_define( :more_stuff \) do |b|)
-          string(b.blah {...})
-          string(b.argh {...})
-          string(b.hack {...})
-        string(end)
-      string(</pre>)
+        registry.namespace_define( :more_stuff \) do |b|
+          b.blah {...}
+          b.argh {...}
+          b.hack {...}
+        end
+      </pre>
 
 
-      string(The first one, above, creates the namespace and calls Container#define!.)
-      string(The second creates the namespace and calls Container#define. In both)
-      string(cases, _the namespace is created immediately_, unlike Container#namespace)
-      string(which only creates the namespace when it is first requested.)
+      The first one, above, creates the namespace and calls Container#define!.
+      The second creates the namespace and calls Container#define. In both
+      cases, _the namespace is created immediately_, unlike Container#namespace
+      which only creates the namespace when it is first requested.
 
 
-      string(Lastly, note that namespace's are just special services. Thus, you can)
-      string(pass options to the namespace methods just as you can with)
-      string(Container#register and friends.)
+      Lastly, note that namespace's are just special services. Thus, you can
+      pass options to the namespace methods just as you can with
+      Container#register and friends.)>
 
-  operator(-) key<delimiter(")content(write log messages?)delimiter(")>operator(:) string(>-)
-      string(You can obtain a new logger instance from the @:logs@ and @:log_for@)
-      string(services. Once you have a logger instance, you can invoke the #debug,)
-      comment(#info, #warn, #error, and #fatal methods on the instance to log messages)
-      string(of the corresponding severity.)
+  operator(-) key<delimiter(")content(write log messages?)delimiter(")>operator(:) string<delimiter(>-)content(
+      You can obtain a new logger instance from the @:logs@ and @:log_for@
+      services. Once you have a logger instance, you can invoke the #debug,
+      #info, #warn, #error, and #fatal methods on the instance to log messages
+      of the corresponding severity.
 
 
-      string(<pre>)
-        string(logger = registry.logs.get( "a name for my logger" \))
-        string(logger.debug "This is a debug message")
-        string(logger.info "This is an informational message")
-        string(...)
-        string(logger2 = registry.log_for( "another logger name" \))
-        string(...)
-      string(</pre>)
+      <pre>
+        logger = registry.logs.get( "a name for my logger" \)
+        logger.debug "This is a debug message"
+        logger.info "This is an informational message"
+        ...
+        logger2 = registry.log_for( "another logger name" \)
+        ...
+      </pre>
 
 
-      string(The two approaches shown above are identical--the second approach (using)
-      string(the @log_for@ service\) is just a convenience for @logs.get@.)
+      The two approaches shown above are identical--the second approach (using
+      the @log_for@ service\) is just a convenience for @logs.get@.
 
 
-      string(Log messages are written, by default, to a file called "needle.log", in)
-      string(the same directory that the application was invoked from.)
+      Log messages are written, by default, to a file called "needle.log", in
+      the same directory that the application was invoked from.
 
 
-      string(You can also use a logging interceptor to automatically log all external)
-      string(method invocations on a service. This includes method entry and exit, as)
-      string(well as any exceptions that are raised inside the method.)
+      You can also use a logging interceptor to automatically log all external
+      method invocations on a service. This includes method entry and exit, as
+      well as any exceptions that are raised inside the method.
 
 
-      string(<pre>)
-        string(registry.register( :foo \) { ... })
-        string(registry.intercept( :foo \).with { |r| r.logging_interceptor })
+      <pre>
+        registry.register( :foo \) { ... }
+        registry.intercept( :foo \).with { |r| r.logging_interceptor }
 
-        string(foo.something)
-        string(foo.another_method( 1, 2, 3 \))
-      string(</pre>)
+        foo.something
+        foo.another_method( 1, 2, 3 \)
+      </pre>
 
 
-      string(See the chapter in the "User's Manual":http://needle.rubyforge.org about)
-      string(logging for more information on how to use and configure loggers.)
+      See the chapter in the "User's Manual":http://needle.rubyforge.org about
+      logging for more information on how to use and configure loggers.)>
 
-  operator(-) key<delimiter(")content(exclude methods from being intercepted?)delimiter(")>operator(:) string(>-)
-      string(Only interceptors that explicitly support exclusion of methods can help)
-      string(you here.  Fortunately, the LoggingInterceptor is one of them. (If you)
-      string(write your own interceptor and would like similar functionality, see the)
-      string(IncludeExclude module.\))
+  operator(-) key<delimiter(")content(exclude methods from being intercepted?)delimiter(")>operator(:) string<delimiter(>-)content(
+      Only interceptors that explicitly support exclusion of methods can help
+      you here.  Fortunately, the LoggingInterceptor is one of them. (If you
+      write your own interceptor and would like similar functionality, see the
+      IncludeExclude module.\)
 
 
-      string(In the case of the LoggingInterceptor, just pass an array of patterns)
-      string((matching method names and/or arities\) as the "exclude" option, when)
-      key(declaring the interceptor)operator(:)
+      In the case of the LoggingInterceptor, just pass an array of patterns
+      (matching method names and/or arities\) as the "exclude" option, when
+      declaring the interceptor:
 
 
-      string(<pre>)
-        string(registry.register( :foo \) { ... })
-        string(registry.intercept( :foo \).)
-          string(with { |r| r.logging_interceptor }.)
-          string(with_options :exclude => [ 'foo', 'bar(>4\)', '*(<2\)' ])
-      string(</pre>)
+      <pre>
+        registry.register( :foo \) { ... }
+        registry.intercept( :foo \).
+          with { |r| r.logging_interceptor }.
+          with_options :exclude => [ 'foo', 'bar(>4\)', '*(<2\)' ]
+      </pre>
 
 
-      string(The above will exclude from interception any method named 'foo', or any)
-      string(invocation of 'bar' with more than 4 arguments, or any method invocation)
-      string(with fewer than two arguments.)
+      The above will exclude from interception any method named 'foo', or any
+      invocation of 'bar' with more than 4 arguments, or any method invocation
+      with fewer than two arguments.
 
 
-      string(You can also give an array of patterns to _include_. These cause methods)
-      key(to be explicitly intercepted even if they match an exclude pattern)operator(:)
+      You can also give an array of patterns to _include_. These cause methods
+      to be explicitly intercepted even if they match an exclude pattern:
 
 
-      string(<pre>)
-        string(registry.register( :foo \) { ... })
-        string(registry.intercept( :foo \).)
-          string(with { |r| r.logging_interceptor }.)
-          string(with_options :exclude => [ 'foo', 'bar(>4\)', '*(<2\)' ],)
-                       symbol(:include) string(=> [ 'baz' ])
+      <pre>
+        registry.register( :foo \) { ... }
+        registry.intercept( :foo \).
+          with { |r| r.logging_interceptor }.
+          with_options :exclude => [ 'foo', 'bar(>4\)', '*(<2\)' ],
+                       :include => [ 'baz' ]
 
-        string(foo = registry.foo)
-        string(foo.baz)
-      string(</pre>)
+        foo = registry.foo
+        foo.baz
+      </pre>
 
 
-      string(This would result in the call to #baz being intercepted, even though it)
-      string(matches an exclude pattern (@*(<2\)@\).)
+      This would result in the call to #baz being intercepted, even though it
+      matches an exclude pattern (@*(<2\)@\).)>
 
-  operator(-) key<delimiter(")content(include services defined in another library?)delimiter(")>operator(:) string(>-)
-      string(This requires that the other library be implemented in such a way that it)
-      string(expects to be "included" by other libraries/applications. For example,)
-      string(Needle encourages the use of a method called @register_services@, which)
-      key(accepts a container as a parameter)operator(:)
+  operator(-) key<delimiter(")content(include services defined in another library?)delimiter(")>operator(:) string<delimiter(>-)content(
+      This requires that the other library be implemented in such a way that it
+      expects to be "included" by other libraries/applications. For example,
+      Needle encourages the use of a method called @register_services@, which
+      accepts a container as a parameter:
 
 
-      string(<pre>)
-        string(module A)
-          string(module B)
-            string(def register_services( container \))
-              string(...)
-            string(end)
-            string(module_function :register_services)
-          string(end)
-        string(end)
-      string(</pre>)
+      <pre>
+        module A
+          module B
+            def register_services( container \)
+              ...
+            end
+            module_function :register_services
+          end
+        end
+      </pre>
 
 
-      string(If the library has been implemented in this way, you can simply do a)
-      string(require of the library and then invoke the @register_services@ method.)
+      If the library has been implemented in this way, you can simply do a
+      require of the library and then invoke the @register_services@ method.
 
 
-      string(There is a convenience method in Container for doing this. Just call)
-      string(Container#require, passing the file to require and a string (or symbol\))
-      string(identifying the name of the module that contains the registration method.)
-      string(You can also pass a symbol as the third parameter naming the registration)
-      string(method, but it defaults to @:register_services@.)
+      There is a convenience method in Container for doing this. Just call
+      Container#require, passing the file to require and a string (or symbol\)
+      identifying the name of the module that contains the registration method.
+      You can also pass a symbol as the third parameter naming the registration
+      method, but it defaults to @:register_services@.
 
 
-      string(<pre>)
-        string(require 'a/b')
-        string(A::B.register_services( container \))
+      <pre>
+        require 'a/b'
+        A::B.register_services( container \)
 
-        comment(# or)
+        # or
 
-        string(container.require( 'a/b', "A::B" \))
-      string(</pre>)
+        container.require( 'a/b', "A::B" \)
+      </pre>
 
 
-      string(The definition context (i.e., the "builder" object\) also supports the)
-      string(require method, so you can do:)
+      The definition context (i.e., the "builder" object\) also supports the
+      require method, so you can do:
 
 
-      string(<pre>)
-        string(container.define do |b|)
-          string(b.require "a/b", "A::B")
-          string(b.foo { ... })
-          string(...)
-        string(end)
-      string(</pre>)
+      <pre>
+        container.define do |b|
+          b.require "a/b", "A::B"
+          b.foo { ... }
+          ...
+        end
+      </pre>)>
 
 operator(-) key<delimiter(")content(When should I...)delimiter(")>operator(:)
   operator(-) key<delimiter(")content(use a different service model?)delimiter(")>operator(:)
-    operator(-) key<delimiter(")content(Like, :prototype?)delimiter(")>operator(:) string(>-)
-        key(The prototype service model is appropriate when the service)operator(:)
+    operator(-) key<delimiter(")content(Like, :prototype?)delimiter(")>operator(:) string<delimiter(>-)content(
+        The prototype service model is appropriate when the service:
 
 
-        string(* has internal state)
+        * has internal state
 
-        string(* will be used multiple times for different situations)
+        * will be used multiple times for different situations
 
 
-        string(For example, if you have a GUI library, a "button" service could be a)
-        string(prototype, because you will likely have many buttons in an application,)
-        string(with each button being an independent instance.)
+        For example, if you have a GUI library, a "button" service could be a
+        prototype, because you will likely have many buttons in an application,
+        with each button being an independent instance.)>
       
-    operator(-) key<delimiter(")content(Like, :singleton?)delimiter(")>operator(:) string(>-)
-        string(The singleton service model is the default, so you should rarely need)
-        string(to explicitly specify it as a model. It is appropriate for services)
-        key(that)operator(:)
-
-
-        string(* guard some specific functionality)
-
-        string(* represent state that is global across an application)
-
-    operator(-) key<delimiter(")content(Like, :threaded?)delimiter(")>operator(:) string(>-)
-        string(Threaded is similar to singleton, but it allows one unique instance of)
-        string(the service _per thread_. Thus, it is appropriate to the same)
-        string(situations as singleton, but specific to a thread, instead of an)
-        string(application. This is useful for web applications that are run in a)
-        string(single virtual machine, and which share a single registry.)
-
-    operator(-) key<delimiter(")content(Like, deferred?)delimiter(")>operator(:) string(>-)
-        string(Deferred models use a proxy to enforce lazy initialization of the)
-        string(service. A service using a deferred service model (ie,)
-        string(@:prototype_deferred@, @:multiton_deferred@, @:singleton_deferred@, or)
-        string(@:threaded_deferred@\) will not be instantiated until the first time a)
-        string(method is invoked on the service.)
-
-
-        string(This makes a deferred model appropriate when a service is expensive to)
-        string(instantiate, since you can wait to do the expensive initialization)
-        string(until it is really needed. Applications will start up faster when their)
-        string(dependences use deferred instantiation.)
-
-    operator(-) key<delimiter(")content(Like, initialize?)delimiter(")>operator(:) string(>-)
-        string(This is useful when you have a method that you want to be invoked)
-        string(automatically after a service has been instantiated. Consider the case)
-        string(where a service is initialized primarily using setters, but requires)
-        string(some logic to be executed to complete the initialization phase. In this)
-        string(case, you could always explicitly invoke the initialization method(s\))
-        string(in the constructor block, but if many services use the same)
-        string(initialization method, it can be more convenient to use an "initialize")
-        string(service model.)
-
-    operator(-) key<delimiter(")content(Like, multiton?)delimiter(")>operator(:) string(>-)
-        string(Multitons are useful for factories, where you have a class that)
-        string(differentiates its instances based on some construction parameters that)
-        string(need to be determined at runtime. Thus, multitons are always used with)
-        string(parameterized services.)
+    operator(-) key<delimiter(")content(Like, :singleton?)delimiter(")>operator(:) string<delimiter(>-)content(
+        The singleton service model is the default, so you should rarely need
+        to explicitly specify it as a model. It is appropriate for services
+        that:
+
+
+        * guard some specific functionality
+
+        * represent state that is global across an application)>
+
+    operator(-) key<delimiter(")content(Like, :threaded?)delimiter(")>operator(:) string<delimiter(>-)content(
+        Threaded is similar to singleton, but it allows one unique instance of
+        the service _per thread_. Thus, it is appropriate to the same
+        situations as singleton, but specific to a thread, instead of an
+        application. This is useful for web applications that are run in a
+        single virtual machine, and which share a single registry.)>
+
+    operator(-) key<delimiter(")content(Like, deferred?)delimiter(")>operator(:) string<delimiter(>-)content(
+        Deferred models use a proxy to enforce lazy initialization of the
+        service. A service using a deferred service model (ie,
+        @:prototype_deferred@, @:multiton_deferred@, @:singleton_deferred@, or
+        @:threaded_deferred@\) will not be instantiated until the first time a
+        method is invoked on the service.
+
+
+        This makes a deferred model appropriate when a service is expensive to
+        instantiate, since you can wait to do the expensive initialization
+        until it is really needed. Applications will start up faster when their
+        dependences use deferred instantiation.)>
+
+    operator(-) key<delimiter(")content(Like, initialize?)delimiter(")>operator(:) string<delimiter(>-)content(
+        This is useful when you have a method that you want to be invoked
+        automatically after a service has been instantiated. Consider the case
+        where a service is initialized primarily using setters, but requires
+        some logic to be executed to complete the initialization phase. In this
+        case, you could always explicitly invoke the initialization method(s\)
+        in the constructor block, but if many services use the same
+        initialization method, it can be more convenient to use an "initialize"
+        service model.)>
+
+    operator(-) key<delimiter(")content(Like, multiton?)delimiter(")>operator(:) string<delimiter(>-)content(
+        Multitons are useful for factories, where you have a class that
+        differentiates its instances based on some construction parameters that
+        need to be determined at runtime. Thus, multitons are always used with
+        parameterized services.)>