copland 0.8.0 → 1.0.0

data/doc/manual-html/tutorial-4.html

@@ -14,8 +14,8 @@
           </div>
         </td><td valign='middle' align='right'>
           <div class="info">
-            Copland Version: <strong>0.8.0</strong><br />
-            Manual Last Updated: <strong>2004-09-27 03:37 GMT</strong>
+            Copland Version: <strong>1.0.0</strong><br />
+            Manual Last Updated: <strong>2004-10-12 02:22 GMT</strong>
           </div>
         </td></tr>
       </table>
@@ -39,13 +39,21 @@
                 
                   <li><a href="chapter-1.html#s1">What is Copland?</a></li>
                 
-                  <li><a href="chapter-1.html#s2">Features</a></li>
+                  <li><a href="chapter-1.html#s2">What Can Copland Do For Me?</a></li>
                 
-                  <li><a href="chapter-1.html#s3">Getting Copland</a></li>
+                  <li><a href="chapter-1.html#s3">Copland <em>sans</em> Buzzwords</a></li>
                 
-                  <li><a href="chapter-1.html#s4">License Information</a></li>
+                  <li><a href="chapter-1.html#s4">Copland <em>avec</em> Buzzwords</a></li>
                 
-                  <li><a href="chapter-1.html#s5">Support</a></li>
+                  <li><a href="chapter-1.html#s5">The Buzzwords Themselves</a></li>
+                
+                  <li><a href="chapter-1.html#s6">Features</a></li>
+                
+                  <li><a href="chapter-1.html#s7">Getting Copland</a></li>
+                
+                  <li><a href="chapter-1.html#s8">License Information</a></li>
+                
+                  <li><a href="chapter-1.html#s9">Support</a></li>
                 
               </ol>
             </li>
@@ -149,7 +157,9 @@
                 
                   <li><a href="chapter-8.html#s1">Descriptor Syntax</a></li>
                 
-                  <li><a href="chapter-8.html#s2">DefaultSymbolSource</a></li>
+                  <li><a href="chapter-8.html#s2">FactoryDefaults</a></li>
+                
+                  <li><a href="chapter-8.html#s3">ApplicationDefaults</a></li>
                 
               </ol>
             </li>
@@ -166,54 +176,68 @@
           
             <li>
                 <a href="chapter-10.html">
+                Logging
+                </a>
+                
+              <ol type="1">
+                
+                  <li><a href="chapter-10.html#s1">Log Factory</a></li>
+                
+                  <li><a href="chapter-10.html#s2">Configuration</a></li>
+                
+              </ol>
+            </li>
+          
+            <li>
+                <a href="chapter-11.html">
                 Service Factories
                 </a>
                 
               <ol type="1">
                 
-                  <li><a href="chapter-10.html#s1">Schemas</a></li>
+                  <li><a href="chapter-11.html#s1">Schemas</a></li>
                 
-                  <li><a href="chapter-10.html#s2">How do they work?</a></li>
+                  <li><a href="chapter-11.html#s2">How do they work?</a></li>
                 
-                  <li><a href="chapter-10.html#s3">BuilderFactory</a></li>
+                  <li><a href="chapter-11.html#s3">BuilderFactory</a></li>
                 
               </ol>
             </li>
           
             <li>
-                <a href="chapter-11.html">
+                <a href="chapter-12.html">
                 Schemas
                 </a>
                 
               <ol type="1">
                 
-                  <li><a href="chapter-11.html#s1">Basic Format</a></li>
+                  <li><a href="chapter-12.html#s1">Basic Format</a></li>
                 
-                  <li><a href="chapter-11.html#s2">Subschemas</a></li>
+                  <li><a href="chapter-12.html#s2">Subschemas</a></li>
                 
-                  <li><a href="chapter-11.html#s3">Arrays</a></li>
+                  <li><a href="chapter-12.html#s3">Arrays</a></li>
                 
-                  <li><a href="chapter-11.html#s4">Named vs. Anonymous Schemas</a></li>
+                  <li><a href="chapter-12.html#s4">Named vs. Anonymous Schemas</a></li>
                 
-                  <li><a href="chapter-11.html#s5">Extending Schemas</a></li>
+                  <li><a href="chapter-12.html#s5">Extending Schemas</a></li>
                 
-                  <li><a href="chapter-11.html#s6">Limitations</a></li>
+                  <li><a href="chapter-12.html#s6">Limitations</a></li>
                 
               </ol>
             </li>
           
             <li>
-                <a href="chapter-12.html">
+                <a href="chapter-13.html">
                 Listeners and Event Producers
                 </a>
                 
               <ol type="1">
                 
-                  <li><a href="chapter-12.html#s1">Event Producers</a></li>
+                  <li><a href="chapter-13.html#s1">Event Producers</a></li>
                 
-                  <li><a href="chapter-12.html#s2">Listeners</a></li>
+                  <li><a href="chapter-13.html#s2">Listeners</a></li>
                 
-                  <li><a href="chapter-12.html#s3">The Registry as an Event Producer</a></li>
+                  <li><a href="chapter-13.html#s3">The Registry as an Event Producer</a></li>
                 
               </ol>
             </li>

data/doc/manual-html/tutorial-5.html

@@ -14,8 +14,8 @@
           </div>
         </td><td valign='middle' align='right'>
           <div class="info">
-            Copland Version: <strong>0.8.0</strong><br />
-            Manual Last Updated: <strong>2004-09-27 03:37 GMT</strong>
+            Copland Version: <strong>1.0.0</strong><br />
+            Manual Last Updated: <strong>2004-10-12 02:22 GMT</strong>
           </div>
         </td></tr>
       </table>
@@ -39,13 +39,21 @@
                 
                   <li><a href="chapter-1.html#s1">What is Copland?</a></li>
                 
-                  <li><a href="chapter-1.html#s2">Features</a></li>
+                  <li><a href="chapter-1.html#s2">What Can Copland Do For Me?</a></li>
                 
-                  <li><a href="chapter-1.html#s3">Getting Copland</a></li>
+                  <li><a href="chapter-1.html#s3">Copland <em>sans</em> Buzzwords</a></li>
                 
-                  <li><a href="chapter-1.html#s4">License Information</a></li>
+                  <li><a href="chapter-1.html#s4">Copland <em>avec</em> Buzzwords</a></li>
                 
-                  <li><a href="chapter-1.html#s5">Support</a></li>
+                  <li><a href="chapter-1.html#s5">The Buzzwords Themselves</a></li>
+                
+                  <li><a href="chapter-1.html#s6">Features</a></li>
+                
+                  <li><a href="chapter-1.html#s7">Getting Copland</a></li>
+                
+                  <li><a href="chapter-1.html#s8">License Information</a></li>
+                
+                  <li><a href="chapter-1.html#s9">Support</a></li>
                 
               </ol>
             </li>
@@ -149,7 +157,9 @@
                 
                   <li><a href="chapter-8.html#s1">Descriptor Syntax</a></li>
                 
-                  <li><a href="chapter-8.html#s2">DefaultSymbolSource</a></li>
+                  <li><a href="chapter-8.html#s2">FactoryDefaults</a></li>
+                
+                  <li><a href="chapter-8.html#s3">ApplicationDefaults</a></li>
                 
               </ol>
             </li>
@@ -166,54 +176,68 @@
           
             <li>
                 <a href="chapter-10.html">
+                Logging
+                </a>
+                
+              <ol type="1">
+                
+                  <li><a href="chapter-10.html#s1">Log Factory</a></li>
+                
+                  <li><a href="chapter-10.html#s2">Configuration</a></li>
+                
+              </ol>
+            </li>
+          
+            <li>
+                <a href="chapter-11.html">
                 Service Factories
                 </a>
                 
               <ol type="1">
                 
-                  <li><a href="chapter-10.html#s1">Schemas</a></li>
+                  <li><a href="chapter-11.html#s1">Schemas</a></li>
                 
-                  <li><a href="chapter-10.html#s2">How do they work?</a></li>
+                  <li><a href="chapter-11.html#s2">How do they work?</a></li>
                 
-                  <li><a href="chapter-10.html#s3">BuilderFactory</a></li>
+                  <li><a href="chapter-11.html#s3">BuilderFactory</a></li>
                 
               </ol>
             </li>
           
             <li>
-                <a href="chapter-11.html">
+                <a href="chapter-12.html">
                 Schemas
                 </a>
                 
               <ol type="1">
                 
-                  <li><a href="chapter-11.html#s1">Basic Format</a></li>
+                  <li><a href="chapter-12.html#s1">Basic Format</a></li>
                 
-                  <li><a href="chapter-11.html#s2">Subschemas</a></li>
+                  <li><a href="chapter-12.html#s2">Subschemas</a></li>
                 
-                  <li><a href="chapter-11.html#s3">Arrays</a></li>
+                  <li><a href="chapter-12.html#s3">Arrays</a></li>
                 
-                  <li><a href="chapter-11.html#s4">Named vs. Anonymous Schemas</a></li>
+                  <li><a href="chapter-12.html#s4">Named vs. Anonymous Schemas</a></li>
                 
-                  <li><a href="chapter-11.html#s5">Extending Schemas</a></li>
+                  <li><a href="chapter-12.html#s5">Extending Schemas</a></li>
                 
-                  <li><a href="chapter-11.html#s6">Limitations</a></li>
+                  <li><a href="chapter-12.html#s6">Limitations</a></li>
                 
               </ol>
             </li>
           
             <li>
-                <a href="chapter-12.html">
+                <a href="chapter-13.html">
                 Listeners and Event Producers
                 </a>
                 
               <ol type="1">
                 
-                  <li><a href="chapter-12.html#s1">Event Producers</a></li>
+                  <li><a href="chapter-13.html#s1">Event Producers</a></li>
                 
-                  <li><a href="chapter-12.html#s2">Listeners</a></li>
+                  <li><a href="chapter-13.html#s2">Listeners</a></li>
                 
-                  <li><a href="chapter-12.html#s3">The Registry as an Event Producer</a></li>
+                  <li><a href="chapter-13.html#s3">The Registry as an Event Producer</a></li>
                 
               </ol>
             </li>

data/doc/manual/manual.css

@@ -148,6 +148,18 @@ a:hover {
   margin-bottom: 1em;
 }
 
+#content h4 {
+  background: #FFE;
+  color: #000;
+  font-size: normal;
+  font-weight: bold;
+  font-variant: small-caps;
+  padding: 0.25em;
+  padding-left: 0.5em;
+  border: 1px dotted #777;
+  margin-bottom: 1em;
+}
+
 #navigation h1 {
   margin: 0px;
   padding: 1em;

data/doc/manual/manual.rb

@@ -101,7 +101,7 @@ module Copland
 
       def initialize( index, title, content )
         @index = index
-        @title = title
+        @title = RedCloth.new( title ).to_html.gsub( %r{</?p>}, "" ) if title
         @content = RedCloth.new( content )
       end
     end

data/doc/manual/manual.yml

@@ -19,22 +19,248 @@ product: !^product
   project: http://rubyforge.org/projects/copland
 
 recent_updates:
-- described the "initializer block" feature of Registry#service.
+- documented the new "visibility" attribute of service points
+- added chapter about Logging configuration
+- fixed misinformation about symbol sources
+- added discussion about FactoryDefaults vs. ApplicationDefaults
+- added (HiveMind-inspired) section in Introduction describing concrete benefits of Copland
 
 chapters:
 
 - Introduction:
   - What is Copland?: >
       Copland is an _Inversion of Control_ (IoC) container, written in
-      "Ruby":http://www.ruby-lang.org, for use in Ruby programs.
-      Depending on whether or not the term "IoC" means anything at all to you, 
-      you can read either the next section ("Copland _sans_ Buzzwords"), or the
-      one after it ("Copland _avec_ Buzzwords").
+      "Ruby":http://www.ruby-lang.org, for use in Ruby programs. In a nutshell,
+      it allows you to simplify the instantiation and initialization of your
+      classes.
 
       
-      h3. Copland _sans_ Buzzwords
+  - What Can Copland Do For Me?: >
+      So, what can Copland do for you? Ultimately, it can reduce the amount of code
+      that you have to write, simplifying many common programming tasks for you. This
+      has the two-fold benefit of both decreasing application development time, and of
+      decreasing the effort needed to maintain your application.
 
 
+      But what, _specifically_, can Copland do for you?
+      
+      
+      Try these on for size:
+
+
+      * "Log Method Execution":#logmethods
+
+      * "Reference Another Service":#refsvc
+
+      * "Service Configuration":#svcconfig
+
+      * "Unit Testing":#unittest
+
+      * "Lifecycle Management":#lifecycle
+
+
+      (Thanks to Howard Lewis Ship for his "HiveMind":http://jakarta.apache.org/hivemind
+      documentation, from which most of the above bullet points were adapted.)
+
+
+      h3. A. Log Method Execution
+      <a name="logmethods"></a>
+
+
+      Copland has an integrated logging framework, and the ability to log
+      execution trace information _without modifying a single line of your code_. This
+      means that you can easily see what methods get called, with what arguments,
+      and what the return values are, all without having to add a single line of
+      logging code to your classes.
+
+
+      Consider the following code, demonstrating how this would be done _without_
+      Copland:
+
+
+      <pre>
+        def foo( arg1, arg2 )
+          @log.debug( "in foo with #{arg1} and #{arg2}" ) if @log.debug?
+          ...
+          result = the_result_of_the_method
+          @log.debug( "finishing foo with #{result}" ) if @log.debug
+          return result
+        rescue Exception => e
+          @log.debug( "foo raised exception #{e.message} (#{e.class})" ) if @log.debug?
+          raise
+        end
+      </pre>
+
+
+      Now, multiply that by the number of methods in your class... the logging messages
+      quickly overpower the rest of the code, and detract from the flow of your program.
+      This makes your program harder to debug, test, and maintain.
+
+
+      Now, consider the same method using Copland's integrated logging framework...
+
+
+      <pre>
+        def foo( arg1, arg2 )
+          ...
+          return the_result_of_the_method
+        end
+      </pre>
+
+
+      Uh, huh. That's right. _There's no explicit logging code in there._ Instead, you just
+      tell Copland that the methods of the class should be logged, and away it goes. This has
+      the added benefit of allowing your objects to be unit tested, without spewing log
+      messages everywhere. (Look for the tutorial about "Logging Interceptors" for an actual
+      demonstration of how to do this.)
+
+
+      h3. B. Reference Another Service
+      <a name="refsvc"></a>
+
+
+      Invariably in a large application services will reference other services. This is
+      typically accomplished through something like this:
+
+
+      <pre>
+        def foo( parms )
+          @service ||= lookup_service
+          @service.do_something( parms )
+        end
+      </pre>
+
+
+      Whether the lookup is done lazily, as shown above, or when the class is first
+      instantiated is irrelevant. The point is that you either have to implement a bunch
+      of code to look up a service based on some criteria, or you hard code the class of
+      the service (which creates tight coupling and makes things like unit testing harder).
+
+
+      With Copland, you just declare a setter for the service, and then tell Copland that
+      the class depends on the other service:
+
+
+      <pre>
+        attr_writer :service
+
+        def foo( parms )
+          @service.do_something( parms )
+        end
+      </pre>
+
+
+      Then, when your service is instantiated, Copland will automatically look for,
+      instantiate, and set the dependencies for you. This makes for cleaner code, and
+      looser coupling between services.
+
+
+      h3. C. Service Configuration
+      <a name="svcconfig"></a>
+
+
+      Often, a large application or library will need some way to allow different classes
+      to be configured at runtime. Whether you have a factory class that requires the
+      available producable classes to register themselves with it, or whether you just want
+      to allow third-parties to be able to extend your application, you wind up implementing
+      some form of decentralized configuration.
+
+
+      Copland allows you to define _configuration points_, which any package may then
+      contribute values to. Furthermore, just as services can reference other services,
+      services can reference configuration points, and Copland will manage them just like
+      any other dependency.
+
+
+      See the tutorial about "Configuration Points" for an example of this feature.
+
+
+      h3. D. Unit Testing
+      <a name="unittest"></a>
+
+
+      Large applications can prove troublesome to unit test exhaustively, especially if there
+      is any kind of tight coupling between components. Such coupling of components can make
+      it difficult to test them separately.
+
+
+      Copland, by its very nature, encourages loose coupling of components. Also, because
+      dependencies are never instantiated in code, but are instead accepted via setters or
+      constructor arguments, it is trivial to replace those dependencies with mock objects
+      at unit test time.
+
+
+      Consider this tightly coupled example:
+
+
+      <pre>
+        def foo( args )
+          @some_dependency ||= MyNewDependency.new
+          @some_dependency.do_something(args)
+        end
+      </pre>
+
+
+      It is impossible to test the method @#foo@ without also testing the MyNewDependency
+      class. However, if the @@some_dependency@ object is made a property that is set
+      externally, you can replace it at test time with a blank:
+
+
+      <pre>
+        attr_writer :some_dependency
+
+        def foo( args )
+          @some_dependency.do_something( args )
+        end
+      </pre>
+
+
+      The unit test would become something like this:
+
+
+      <pre>
+        def test_foo
+          @obj.some_dependecy = MyMockDependency.new
+          @obj.foo( args )
+          assert @obj.is_in_some_state
+        end
+      </pre>
+
+
+      h3. E. Lifecycle Management
+      <a name="lifecycle"></a>
+
+
+      Singleton objects are a fact of life in complex systems. The singleton design pattern
+      is powerful and useful. However, using the Singleton mixin, or declaring methods at the
+      class level, can make your code difficult to unit test since the state of such objects
+      cannot be easily reset.
+
+
+      Copland has a solution. You can tell Copland to treat a service as either a _prototype_
+      service (meaning it will be instantiated every time you ask for it, like calling @#new@),
+      or a _singleton_ service (meaning it will only be instantiated once, and the same instance
+      will be returned for subsequent requests).
+
+
+      Your object is still just a plain ol' ordinary Ruby object, but Copland has effectively
+      transformed it into a singleton. This means you can unit test it as if it were nothing
+      special, but when it is used in your application it will act like a singleton.
+
+
+      Lifecycle management also means that you can control _when_ a service is instantiated.
+      The _prototype_ and _singleton_ models will always be instantiated as soon as they are
+      requested. Sometimes, though, you don't want that--you'd like the instantiation to be
+      deferred as long as possible.
+
+
+      With Copland, you can indicate that a service should use deferred instantiation. This will
+      cause the service to not actually be instantiated until a method is actually invoked on it.
+      Using this model, you can have services depend on themselves, or other forms of cyclical
+      dependencies.
+
+
+  - Copland _sans_ Buzzwords: >
       Imagine being able to take all the various pieces of your program and implement
       them in a vacuum. You just assume that all dependencies will be satisfied at runtime,
       by properties being set, or parameters being passed to each object's constructor.
@@ -71,9 +297,7 @@ chapters:
       specify those relationships and dependencies as run-time configuration options.
 
 
-      h3. Copland _avec_ Buzzwords
-
-
+  - Copland _avec_ Buzzwords: >
       If you are already familiar with IoC, then you either love it or hate it. In the first
       case, you probably only want to know what features Copland has compared to other IoC
       containers you've used. In the second case, there's probably not much I can say to
@@ -97,9 +321,7 @@ chapters:
       you've never used YAML, you'll find it surprisingly easy to pick up.
 
 
-      h3. The Buzzwords Themselves
-
-
+  - The Buzzwords Themselves: >
       As "Martin Fowler":http://www.martinfowler.com
       "points out":http://martinfowler.com/articles/injection.html, the term "Inversion of Control"
       is a poorly-chosen one. Still, it is the one that most people know the concept by, so I'll
@@ -823,6 +1045,11 @@ chapters:
       here, to be notified when some service-specific event is triggered. See the chapter on
       "Listeners and Event Producers" for more information.|
 
+      |^. @visibility@|This must be either the value "public" or "private". It defaults to "public".
+      If it is "private", then the service point is not visible outside of its containing package.
+      it is often the case that a particular package will have a few public services that are
+      facades for multiple private services. See the @copland.webrick@ package for an example.|
+
 
       Of these attributes, only @implementor@ is required.
 
@@ -1027,8 +1254,8 @@ chapters:
 
       Of these attributes, only @type@ is required.
 
-  - DefaultSymbolSource: >
-      One of the core pre-defined configuration points is the map @copland.DefaultSymbolSource@.
+  - FactoryDefaults: >
+      One of the core pre-defined configuration points is the map @copland.FactoryDefaults@.
       Although you will rarely access this configuration point directly, it is integrated
       tightly with Copland. Any value you add to it becomes available as a _substitution
       symbol_.
@@ -1038,13 +1265,13 @@ chapters:
       utilities like "ant":http://ant.apache.org and "maven":http://maven.apache.org make
       heavy use of them.  What they are, is this: any time Copland encounters a value that
       contains a certain pattern, it replaces that pattern with the value of the same name
-      from the DefaultSymbolSource.  The pattern is a dollar sign, followed by curly braces
+      from the FactoryDefaults.  The pattern is a dollar sign, followed by curly braces
       that contain the name of the symbol.
 
 
       For example, suppose you want to allow the application to configure which class gets
       used when a particular service point is instantiated. You can do this by pulling the
-      name of the class from the DefaultSymbolSource as a substitution symbol:
+      name of the class from the FactoryDefaults as a substitution symbol:
 
 
       <pre>
@@ -1054,9 +1281,21 @@ chapters:
 
 
       Then, the application would contribute a value named @the.class.to.use@ to 
-      @copland.DefaultSymbolSource@, and when @SomeServicePoint@ is instantiated, it would
+      @copland.FactoryDefaults@, and when @SomeServicePoint@ is instantiated, it would
       use the value thus provided.
 
+  - ApplicationDefaults: >
+      The @copland.ApplicationDefaults@ configuration point works together with the
+      @FactoryDefaults@ configuration point to provide a flexible way to override 
+      default values of substitution symbols.
+
+
+      When a substitution symbol is requested, the @ApplicationDefaults@ configuration
+      point is searched first. If the requested symbol is not found there, the
+      @FactoryDefaults@ configuration point is searched. This allows package developers
+      to define default values (in @FactoryDefaults@), and allow clients of the packages
+      to override those defaults as needed (in @ApplicationDefaults@).
+
 - Contributions:
   - >
     _Contributions_ are the means by which packages may add values to configuration points.
@@ -1070,20 +1309,187 @@ chapters:
     you want to contribute.
 
 
-    For example, to contribute a value to the DefaultSymbolSource configuration point:
+    For example, to contribute a value to the ApplicationDefaults configuration point:
 
 
     <pre>
       contributions:
 
-        copland.DefaultSymbolSource:
+        copland.ApplicationDefaults:
           user.name: fritz
     </pre>
 
 
-    That little snippet just added a value called @user.name@ to the @copland.DefaultSymbolSource@
+    That little snippet just added a value called @user.name@ to the @copland.ApplicationDefaults@
     configuration point!
 
+- Logging:
+  - >
+    Copland has an integrated logging system based on a slight variation of Ruby's own
+    "logger" library. In addition to the features of that library, Copland's logging system
+    provides:
+
+
+    * A logger factory for creating shared logger instances
+
+    * YAML-based configuration of the factory
+
+    * Customizable message formatting
+
+  - Log Factory: >
+      Each registry instance has its own instance of @Copland::LogFactory@. This provides
+      a way to map a name to a logger instance, and allows each service point (for example)
+      to have its own logger instance. This allows various logger settings to be tweaked
+      _per service-point_.
+
+
+      For example, if I want debugging information to be logged for one service point, but
+      not for another, I can specify the logging priority level for the one service point to
+      include debug messages, and have such messages excluded for the other service point.
+
+
+      The log factory allows default values to be set for the priority level, date format
+      string, and message format string, which will be applied to any logger that does not
+      have a specific value set for those values. The log factory also allows configuration
+      of the IO device to log to, the filename to log to, and various other (Logger-specific)
+      data items (see the API documentation for @Copland::LogFactory@ for more information).
+
+
+      If you ever need to access the current log factory instance, you can get it from the
+      registry as the @copland.LogFactory@ service.
+
+  - Configuration: >
+      There are three ways to configure loggers. The first is programmatically, manually
+      tweaking each log instance directly. The second is to pass configuration options to
+      the registry itself when it is built, and the third is to use a configuration file.
+
+
+      h3. Programmatic Configuration
+
+
+      To programmatically configure a logger, just obtain a handle to a logger instance
+      and then tweak it via the accessor methods of the logger:
+
+
+      <pre>
+        factory = registry.service( "copland.LogFactory" )
+        log = factory.get( "some.log.name" )
+
+        # Standard Logger attributes
+        log.level = Logger::INFO
+        log.progname = "different.log.name"
+        log.datetime_format = "%Y%m%d"
+
+        # Extended Logger attributes (provided by Copland)
+        log.message_format = "[%-5p] %d %c: %m"
+      </pre>
+
+
+      _Note:_ programmatically changing the logger @progname@ does not change the name by
+      which the logger is known to the factory!
+
+
+      In general, programmatic tweaking of the logger attributes as demonstrated above is not
+      going to be the best way to do it. First of all, it is tedious, and bug prone. Secondly,
+      it is difficult to know where the best place to do such work is, since you need to set
+      those attributes before any other service tries to access that log.
+
+
+      h3. Configuration via @Registry.build@
+
+
+      The second approach is to pass logger configuration options to @Registry.build@,
+      when you create a registry instance:
+
+
+      <pre>
+        registry = Copland::Registry.build(
+          :log_device => STDOUT,
+          :log_default_level => Logger::INFO,
+          ...
+        )
+      </pre>
+
+
+      This gives you much greater flexibility than the previous approach, since it allows
+      you to specify a greater array of options. The allowed options are:
+
+
+      table(list).
+      
+      |^. @:log_config_file@|This is the name of the configuration file to use to
+      configure the log factory. It defaults to "logger.yml". (See the next section for
+      more information.)|
+
+      |^. @:log_device@|This is the IO (or pseudo-IO) object to write log messages to.
+      If this option is specified, @:log_filename@ must not be specified (and vice versa).
+      This allows you to log messages to arbitrary IO streams.|
+
+      |^. @:log_filename@|This is the name of the file to write log messages to. If this
+      option is specified, @:log_device@ must not be specified (and vice versa). This
+      defaults to "./copland.log".|
+
+      |^. @:log_roll_age@|This specifies the number of days before the log should be
+      rolled. (This option is only useful when used with @:log_filename@.)|
+
+      |^. @:log_roll_frequency@|This should be either @nil@, "daily", "weekly", or
+      "monthly", and specifies how frequently the log should be rolled. This option cannot
+      be used with @:log_roll_age@.|
+
+      |^. @:log_roll_size@|This specifies the maximum size of a log file. Once the log
+      file gets larger than this value, the log will be rolled. (This option is only useful
+      when used with @:log_filename@.)|
+
+      |^. @:log_default_date_format@|This is the default date format string to use for the
+      loggers that are created. It may be any string that is understood by @Time#strftime@.
+      If @nil@ (the default), then the default Logger date format string will be used.|
+
+      |^. @:log_default_message_format@|This is the default message format string to use
+      for the loggers that are created. It is a printf-styled string with special format
+      specifiers--see the API documentation for @Copland::Logger#message_format=@ for the
+      available specifiers.|
+
+      |^. @:log_default_level@|This is the default level for each logger. Messages that
+      are logged below this level (also "priority" or "severity") will not be logged. By
+      default, all messages are logged.|
+
+      |^. @:log_levels@|This is a hash. Each key should be a string containing a regular
+      expression. For every logger whose name matches one of these patterns, the corresponding
+      value will be used to define specific values for that logger. The value for each key
+      must either be a string (in which case it is the name of the severity level to use), or
+      a hash (containing any of the keys "level", "date-format", or "message-format").|
+
+
+      h3. Configuration via YAML
+
+
+      The third option (and the most flexible) is to use a YAML configuration file to
+      define the parameters of the log factory and its loggers. By default, this file
+      is called "logger.yml", but you can specify a different logger configuration file
+      via the @:log_config_file@ option to @Copland::Registry.build@. By default, the
+      configuration file must reside in current working directory, but you can specify
+      an explicit path in the string you give to @:log_config_file@.
+
+
+      The file has options that correspond to the configuration parameters described above:
+
+
+      <pre>
+        ---
+        filename: log/filename.log
+        roll-age: 5
+        default-date-format: %Y%m%d%H%M%S
+        default-message-format: %p %d %t %C: %m (%l)
+        default-level: DEBUG
+        levels:
+          copland.*: WARN
+          project.*:
+            level: INFO
+            date-format: %Y%m%d::%H%M%S
+            message-format: %p %d: %m
+      </pre>
+
+
 - Service Factories:
   - >
     Sometimes it requires a little more effort (or a lot more effort) to instantiate and