log4r 1.0.6

data/doc/content/contact.html

@@ -0,0 +1,22 @@
+Title: Log4r - Contact
+Template: main.html
+Id: $Id: contact.html,v 1.1.1.1 2004/03/19 03:30:59 fando Exp $
+
+<tr><td width="100%" class="contenttitle">Contact the Developers</td></tr>
+<tr><td width="100%" class="contentbuff">&nbsp;</td></tr>
+<tr><td width="100%" class="content">
+Lead developer:
+<p>
+Leon Torres 
+&lt;leon(at)ugcs dot caltech dot edu</a>&gt;
+<br/>
+Pasadena, CA, USA (UTC-8)
+<p/>
+Contributors:
+<ul>
+  <li>Martain Stannard - for RollingFileOutputter and for caring about maintenance
+  <li>Steve Lumos - for SyslogOutputter
+  <li>Jamis Buck - for making Log4r available as a RubyGems gem
+  <li>Andreas Hund - for YAML configuration with YamlConfigurator
+</ul>
+</td></tr>

data/doc/content/contribute.html

@@ -0,0 +1,21 @@
+Title: Log4r - Contribute
+Template: main.html
+Id: $Id: contribute.html,v 1.1.1.1 2004/03/19 03:30:59 fando Exp $
+
+<tr><td width="100%" class="contenttitle">Contributing to Log4r</td></tr>
+<tr><td width="100%" class="contentbuff">&nbsp;</td></tr>
+<tr><td width="100%" class="content">
+If you wish to contribute something to Log4r or assist in development,
+please drop an email to Leon: leon(at)ugcs dot caltech dot edu</a>. There
+will always be work to do. Some things that come to mind are:
+<p/>
+
+<font size="-1">
+<ul>
+<li> Find bugs and flaws, or areas to improve
+<li> More Outputters that do various nifty things
+<li> More and better documentation
+<li> And, of course, spreading the good word <code>;-)</code>
+</ul>
+</font>
+</td></tr>

data/doc/content/index.html

@@ -0,0 +1,90 @@
+Title: Log4r - Manual
+Template: main.html
+Id: $Id: index.html,v 1.1.1.1 2004/03/19 03:31:00 fando Exp $
+
+<tr><td width="100%" class="contenttitle">A Powerful Logging Library for Ruby
+</td></tr>
+<tr><td width="100%" class="contentbuff">&nbsp;</td></tr>
+<tr><td width="100%" class="content">
+
+<h4 class="header">What Log4r Is</h4>
+Log4r is a comprehensive and flexible logging library written in Ruby
+for use in Ruby programs. It features a hierarchical logging system
+of any number of levels, custom level names, logger inheritance,
+multiple output destinations, execution tracing, custom formatting, thread
+safteyness, XML and YAML configuration, and more.
+<p/>
+Log4r is an adherent to the philosophy of logging using simple print 
+statements. What Log4r adds to this philosophy is a flexible way of 
+controling the information being logged. Log information can be sent to
+any kind of destination and with varying degrees of importance. Log4r is 
+designed so that logging statements can remain in production code with
+almost no extra computational cost.
+<p/>
+Log4r intends to be easy to use and configure, no matter the complexity.
+Casual scripts can use Log4r right away with minimal configuration, while
+more sophisticated applications can set up a structured configuration file 
+in XML or YAML. Comprehensive documentation is provided, with a user's manual,
+a reference API, and over a dozen examples. Log4r attempts to abide by the 
+Principle of Least Surprise, which means that it works as intended at all 
+points.
+<p/>
+Log4r was inspired by and provides much of the features of the
+<a href="http://jakarta.apache.org/log4j/docs/index.html">Apache Log4j</a> 
+project, but is not a direct implementation or clone. Aside from superficial
+similarities, the projects are not related in any way and the code base is 
+completely distinct. Log4r was developed without even looking at the 
+Apache Log4j code.
+<p/>
+Log4r is an Open Source project and intends to remain that way. The Log4r
+license is similar to the Ruby Language license. It resides on
+<a href="license.html">this page</a> and in the distribution in a file
+named LICENSE.
+
+<!--
+<p><hr noshade color="#AA0000">
+<h4 class="header">But Why?</h4>
+
+Why a logging system like Log4r? 
+<p/>
+
+There are many non-obvious reasons. First,
+logging should not be confused with Unit testing. Unit testing and logging are
+complementary rather than exclusive. Second, logging provides a handy way
+for a program to provide useful information about itself to different 
+audiences. With logging, your application's state can be tracked over time and
+not be a complete mystery. With Log4r, you can control the amount and type of
+information that show up without having to comment out the logging statements 
+in your code. This helps reduce noise and maximize the usefulness of log files.
+Finally, logging is extremely useful in applications that are not all in one
+place (distributed). If you want to debug a client and server at the same time,
+a logging system like Log4r becomes critical.
+-->
+
+<p><hr noshade color="#AA0000">
+<h4 class="header">Getting Started with Log4r</h4>
+
+<ol>
+<li> Download the latest version from
+<a href="http://sourceforge.net/project/showfiles.php?group_id=43396">this page</a>
+<li> Try out the examples in the <tt>examples</tt> directory of the distribution
+<li> Install by running <tt>ruby install.rb</tt>
+<li> Read the nice <a href="manual.html">manual</a>
+<li> Use Log4r
+<li> Consult the <a href="rdoc/index.html">Log4r RDoc API</a> for reference
+<li> <a href="http://www.ruby-lang.org/en/raa-list.rhtml?name=REXML">
+Get REXML</a> to take advantage of the XML config
+<li> <a href="contribute.html">Contribute</a>!
+</ol>
+
+<h4 class="header">Install Using RubyGems</h4>
+
+<p>
+If you have <a href="http://rubygems.rubyforge.org/wiki/wiki.pl?RubyGems">RubyGems</a>, install the Log4r gem!
+
+<ul>
+  <li> gem --remote-install log4r
+</ul>
+</p>
+
+</td></tr>

data/doc/content/license.html

@@ -0,0 +1,56 @@
+Title: Log4r License
+Template: main.html
+Id: $Id: license.html,v 1.1.1.1 2004/03/19 03:31:00 fando Exp $
+
+<tr><td width="100%" class="contenttitle">Log4r License</td></tr>
+<tr><td width="100%" class="contentbuff">&nbsp;</td></tr>
+<tr><td width="100%" class="content">
+<pre>
+Log4r is copyrighted free software by Leon Torres &lt;leon@ugcs.caltech.edu&gt;.
+You can redistribute it and/or modify it under either the terms of the GPL, 
+or the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+	  modifications to Usenet or an equivalent medium, or by allowing
+	  the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) rename any non-standard executables so the names do not conflict
+	  with standard executables, which must also be provided.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or executable
+     form, provided that you do at least ONE of the following:
+
+       a) distribute the executables and library files of the software,
+	  together with instructions (in the manual page or equivalent)
+	  on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+	  the software.
+
+       c) give non-standard executables non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).
+
+  5. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.
+</pre>
+</td></tr>

data/doc/content/manual.html

@@ -0,0 +1,449 @@
+Title: #{version} Log4r Manual
+Template: main.html
+Id: $Id: manual.html,v 1.1.1.1 2004/03/19 03:31:02 fando Exp $
+
+<tr><td width="100%" class="contenttitle">#{version} Log4r Manual</td></tr>
+<tr><td width="100%" class="contentbuff">&nbsp;</td></tr>
+<tr><td width="100%" class="content">
+
+<a name="toc">
+<h4 ><a href="#toc">Table of Contents</a></h4>
+
+<ul>
+<li><a href="#scope">Scope of This Manual</a>
+<li><a href="#is">What Log4r Is</a>
+<li><a href="#outofbox">Out of the Box</a>
+<li><a href="#overview">Overview</a>
+  <ul>
+	<li><a href="#levels"> Levels</a>
+	<li><a href="#loggers"> Loggers</a>
+	<li><a href="#outputters"> Outputters</a>
+	<li><a href="#formatters"> Formatters</a>
+	<li><a href="#config"> Configuration</a>
+	<li><a href="#remote"> Remote Logging</a>
+	</ul>
+<li><a href="#art">The Art of Logging</a>
+  <ul>
+	<li><a href="#avoid">Avoiding Parameter Evaluation</a>
+	<li><a href="#howmany">How Many?</a>
+	<li><a href="#whereto">Where To?</a>
+	<li><a href="#tracing">Where From?</a>
+	<li><a href="#who">Who's Talking?</a>
+    <li><a href="#nullobj">The Null Logger</a>
+  </ul>
+<li><a href="#gotchas">Gotchas</a>
+<li><a href="#performance">Performance</a>
+<li><a href="#project">The Project Itself</a>
+</ul>
+
+<hr noshade color="#AA0000">
+
+<a name="scope">
+<h4 ><a href="#toc">Scope of this Manual</a></h4>
+
+Most of the API documentation resides in the 
+<a href="rdoc/index.html">Log4r RDoc API</a>, so this manual will be brief
+and targeted to people starting to learn about Log4r or who want to see 
+what Log4r has to offer.
+<p/>
+Besides the general overview, a section called 
+<a href="#art">The Art of Logging</a> provides tricks and tips in using
+Log4r efficiently.
+<p/>
+Click on the section title to go back to the 
+<a href="#toc">Table of Contents</a> at any time.
+
+<p/><hr noshade color="#AA0000">
+<a name="is">
+<h4 ><a href="#toc">What Log4r Is</a></h4>
+Log4r is a comprehensive and flexible logging library written in Ruby
+for use in Ruby programs. It features a hierarchical logging system
+of any number of levels, custom level names, logger inheritance,
+multiple output destinations, execution tracing, custom formatting, thread
+safteyness, XML and YAML configuration, and more.
+<p/>
+Log4r is an adherent to the philosophy of logging using simple print 
+statements. What Log4r adds to this philosophy is a flexible way of 
+controling the information being logged. Log information can be sent to
+any kind of destination and with varying degrees of importance. Log4r is 
+designed so that logging statements can remain in production code with
+almost no extra computational cost.
+<p/>
+Log4r intends to be easy to use and configure, no matter the complexity.
+Casual scripts can use Log4r right away with minimal configuration, while
+more sophisticated applications can set up a structured configuration file 
+in XML or YAML. Comprehensive documentation is provided, with a user's manual,
+a reference API, and over a dozen examples. Log4r attempts to abide by the 
+Principle of Least Surprise, which means that it works as intended at all 
+points.
+<p/>
+Log4r was inspired by and provides much of the features of the
+<a href="http://jakarta.apache.org/log4j/docs/index.html">Apache Log4j</a> 
+project, but is not a direct implementation or clone. Aside from superficial
+similarities, the projects are not related in any way and the code base is 
+completely distinct. Log4r was developed without even looking at the 
+Apache Log4j code.
+<p/>
+Log4r is an Open Source project and intends to remain that way. The Log4r
+license is similar to the Ruby Language license. It resides on
+<p/>
+While Log4r is interpreted, it attempts to achieve optimal performance and
+scale well. Already, plans are being made to write the performance-critical 
+components as a C extension to Ruby.
+<p/>
+Log4r was inspired by and provides much of the features of the
+<a href="http://jakarta.apache.org/log4j/docs/index.html">Apache Log4j</a> 
+project, but is not a direct implementation or clone. Aside from superficial
+similarities, the projects are not related in any way and the code base is 
+completely distinct. Log4r was developed without even looking at the 
+Apache Log4j code.
+<p/>
+Log4r is an Open Source project and intends to remain that way. The Log4r
+license is similar to the Ruby Language license. It resides on
+<a href="license.html">this page</a> and in the distribution in a file
+
+<p><hr noshade color="#AA0000">
+<a name="outofbox">
+<h4 ><a href="#toc">Out of the Box</a></h4>
+
+Here's an example of how to use Log4r right away.
+<div class="example">
+<pre class="box">require 'log4r'
+include Log4r
+
+# create a logger named 'mylog' that logs to stdout
+mylog = Logger.new 'mylog'
+mylog.outputters = Outputter.stdout
+
+# Now we can log.
+def do_log(log)
+  log.debug "This is a message with level DEBUG"
+  log.info "This is a message with level INFO"
+  log.warn "This is a message with level WARN"
+  log.error "This is a message with level ERROR"
+  log.fatal "This is a message with level FATAL"
+end
+do_log(mylog)
+</pre>
+</div>
+
+The output will look something like this:
+
+<div class="example">
+<pre class="box">DEBUG mylog: This is a message with level DEBUG
+ INFO mylog: This is a message with level INFO
+ WARN mylog: This is a message with level WARN
+ERROR mylog: This is a message with level ERROR
+FATAL mylog: This is a message with level FATAL</pre>
+</div>
+
+For ease of access, the logger is stored in a hashtable keyed to its name:
+
+<div class="example">
+<pre class="box">mylog = Logger['mylog']        # Get our logger back</pre>
+</div>
+
+Suppose we want to turn off <tt>DEBUG</tt>, <tt>INFO</tt>
+and <tt>WARN</tt> messages and see only <tt>ERROR</tt> and <tt>FATAL</tt>.
+To do this, we set the level threshold for mylog to <tt>ERROR</tt>:
+
+<div class="example">
+<pre class="box">mylog.level = ERROR</pre>
+</div>
+
+Running <tt>do_log(mylog)</tt> yields:
+
+<div class="example">
+<pre class="box">ERROR mylog: This is a message with level ERROR
+FATAL mylog: This is a message with level FATAL</pre>
+</div>
+
+<p><hr noshade color="#AA0000">
+<a name="overview">
+<h4 ><a href="#toc">Overview</a></h4>
+
+We will now go over the components of Log4r. A summary of each is provided,
+and links to the
+<a href="rdoc/index.html">Log4r RDoc API</a> are provided for further perusal.
+
+<p><hr noshade color="#AA0000">
+<a name="levels">
+<h4 ><a href="#toc">Levels</a></h4>
+
+Log4r uses a hierarchical system of logging. That is, certain log events
+can have a higher priority than other log events. Hence, one can control
+how much information one wants to log by adjusting the <b>level threshold</b>
+of logging. By default, the logging levels and priorities are:
+
+<div class="example">
+<pre class="box">DEBUG &lt; INFO &lt; WARN &lt; ERROR &lt; FATAL</pre>
+</div>
+In the previous section, we saw how setting the level to <tt>ERROR</tt>
+prevented messages with levels <tt>DEBUG</tt>, <tt>INFO</tt> and <tt>WARN</tt>
+from showing up. The names and numbers of these levels are configurable.
+You can have any number of levels and name them whatever you wish. The
+logging methods we saw in the last section will be named after the custom
+levels. Log4r adjusts itself to suit your needs.
+<p/>
+
+To find out more about levels, please see 
+<a href="rdoc/files/log4r_rb.html">rdoc/files/log4r_rb.html</a>.
+
+<p><hr noshade color="#AA0000">
+<a name="loggers">
+<h4 ><a href="#toc">Loggers</a></h4>
+The principle interface in Log4r is a Logger. Loggers have one logging method
+for each level and any number of output destinations. A logger's level
+threshold and output destinations may be changed dynamically. Loggers are
+stored within a Repository for retrieval at any time. Loggers provide
+all kinds of data for logging: the log message itself, the line number and
+file it was called in, a timestamp, the log priority, and so on.
+<p/>
+Loggers can inherit other Loggers. Inheritance means that a Logger initially
+adopts the characteristics of its parent if none are specified. A Logger's
+level is inherited once, and a Logger will write to its parents output
+destinations as well as its own. This behavior is optional, but allows one
+to structure a powerful, and easily configurable logging system.
+<p/>
+To find out more about loggers, please see
+<a href="rdoc/files/log4r/logger_rb.html">rdoc/files/log4r/logger_rb.html</a>.
+<p><hr noshade color="#AA0000">
+<a name="outputters">
+<h4 ><a href="#toc">Outputters</a></h4>
+
+An output destination (file, raw IO, stdout, etc.) is represented by an 
+Outputter object. An Outputter has a
+particular means of formatting data (Formatter) and has a level threshold
+of its own. Outputters, like Loggers, are stored in a repository and can be 
+retrieved and manipulated at any time. Every outputter is thread-safe, meaning
+that multiple threads can log to the same Outputter without worrying about
+race conditions.
+<p/>
+There is a growing collection of outputters provided: raw IO, to stdout, 
+to stderr, to files (including one that splits and zips up logs periodically),
+to syslog and to an email address. If a specialized Outputter is needed, one
+can be created from scratch in almost no time, thanks to the ease of 
+extending log4r outputters, the well documented code and the open source 
+license.
+<p/>
+To find out more about outputters, please see
+<a href="rdoc/files/log4r/outputter/outputter_rb.html">
+rdoc/files/log4r/outputter/outputter_rb.html</a>.
+<p><hr noshade color="#AA0000">
+<a name="formatters">
+<h4 ><a href="#toc">Formatters</a></h4>
+A Formatter is responsible for rendering a log message into an output format.
+Several Formatters are provided, including the powerful PatternFormatter.
+PatternFormatter uses sprintf-like directives to format log messages and
+eliminates the need for custom Formatters.
+<p/>
+To find out more about formatters, please see
+<a href="rdoc/files/log4r/formatter/formatter_rb.html">
+rdoc/files/log4r/formatter/formatter_rb.html</a>.
+<br/>
+To find out more about PatternFormatter, please see
+<a href="rdoc/files/log4r/formatter/patternformatter_rb.html">
+rdoc/files/log4r/formatter/patternformatter_rb.html</a>.
+<p><hr noshade color="#AA0000">
+<a name="config">
+<h4 ><a href="#toc">Configuration</a></h4>
+Configuring Log4r is accomplished via the Configurator and YamlConfigurator
+classes. They allow one to set custom levels and load up XML or YAML 
+configurations. The XML and YAML grammar used by Log4r is extremely flexible 
+and can accomodate the configuration of custom Outputters and Formatters with 
+no extra work. That is, if a custom Outputter is created, it can immedieately
+be configured without needing to write extra code. This is acomplished by
+taking advantage of Ruby's powerful reflection capabilities.
+<p/>
+To find out more about configuration, please see
+<a href="rdoc/files/log4r/configurator_rb.html">rdoc/files/log4r/configurator_rb.html</a>.
+<br/>
+For YAML configuration, also see
+<a href="rdoc/files/log4r/yamlconfigurator_rb.html">rdoc/files/log4r/yamlconfigurator.html</a>
+
+<p><hr noshade color="#AA0000">
+<a name="remote">
+<h4 ><a href="#toc">Remote Logging</a></h4>
+
+It is possible to send log events from an Outputter to a Logger over a network.
+This is accomplished using the distributed Ruby library ROMP, a subclass of
+Logger called LogServer, and a RemoteOutputter.
+<p/>
+To find out more about remote logging, please see
+<a href="rdoc/files/log4r/logserver_rb.html">
+rdoc/files/log4r/logserver_rb.html</a>
+<p/>
+Alternatively, one can just send log reports via email using EmailOutputter.
+<p/>
+To find out more about EmailOutputter, please see
+<a href="rdoc/classes/Log4r/EmailOutputter.html">
+rdoc/classes/Log4r/EmailOutputter.html</a>
+
+<p><hr noshade color="#AA0000">
+<a name="art">
+<h4 ><a href="#toc">The Art of Logging</a></h4>
+
+Log4r in itself does not automatically enable people to understand logging, 
+however it does provide tools to assist in <i>The Art of Logging</i>. We will 
+now cover some of the techniques in this art and how to use Log4r to 
+accomplish them.
+
+<p><hr noshade color="#AA0000">
+<a name="avoid">
+<h4 ><a href="#toc">Avoiding Parameter Evaluation</a></h4>
+
+Suppose we have a complex structure and don't have the time to
+make a special <tt>to_s</tt> method. When we want to log the contents
+of the object, we end up doing something like this:
+
+<div class="example">
+<pre class="box">log.debug( myobj.collect{|e| e.collect{|p| p.to_s}} )</pre>
+</div>
+
+It is expensive to do this because every time the debug method is called,
+the parameters passed to it will be evaluated. Because this is a feature of
+Ruby, setting the logger to <tt>OFF</tt> will not prevent the evaluation. 
+There are two ways to get around parameter evaluation. The first is to
+perform a simple if condition:
+
+<div class="example">
+<pre class="box">if log.debug?
+  log.debug( myobj.collect{|e| e.collect{|p| p.to_s}} )
+end</pre></div>
+</div>
+
+Here we are introduced to <tt>log.debug?</tt>, which is called a 
+<i>query method</i>. It returns true if <tt>DEBUG</tt> messages are being 
+logged, otherwise it returns false. Query methods are very cheap 
+to invoke and are a great way to encapsulate complext logging statements.
+The query methods, like the logging ones, are named after the levels, but with 
+a question mark at the end. As another example, <tt>log.info?</tt> will find 
+out if <tt>INFO</tt> is being logged and so on.
+<p/>
+The second way around parameter evaluation is to pass a block to the
+logging method:
+
+<div class="example">
+<pre class="box">log.debug { myobj.collect{|e| e.collect{|p| p.to_s} }</pre>
+</div>
+
+The block will be evaluated if and only if the logger is capable of handling
+<tt>DEBUG</tt> log events.
+
+<p><hr noshade color="#AA0000">
+<a name="howmany">
+<h4 ><a href="#toc">How Many?</a></h4>
+How many loggers should one have? Only experience can tell, but
+a general rule of thumb is to create one static logger per class and
+one per service or state. 
+<p/>
+When dealing with a large number of loggers, logger 
+inheritance and additivity can help organize what gets logged and to where.
+<p/>
+The configuration possibilities in Log4r are uncountable and can sometimes 
+be daunting. It's best to start with something simple and evolve it over time. 
+To assist in this task, Log4r can be set up using XML or YAML configuration 
+files.
+<p><hr noshade color="#AA0000">
+<a name="whereto">
+<h4 ><a href="#toc">Where To?</a></h4>
+Log4r lets one associate any number of Outputters to a Logger. Logger
+additivity enables propagation of a log event upwards in the logger hierarchy.
+The outputters themselves can have their own level thresholds. Unlike normal
+loggers, Outputters can log at certain specific log levels. this allows
+one to channel particular data to a particular output. All things considered, 
+log4r offers tremendous flexibility in deciding what gets logged where.
+
+<p><hr noshade color="#AA0000">
+<a name="tracing">
+<h4 ><a href="#toc">Where From?</a></h4>
+
+Want to find out where a particular log statement came from? Loggers have
+tracers which record the call stack when turned on:
+
+<div class="example">
+<pre class="box">Logger['mylog'].trace = true</pre>
+</div>
+
+The trace is then accesible by a Formatter.
+
+<p><hr noshade color="#AA0000">
+<a name="who">
+<h4 ><a href="#toc">Who's Talking?</a></h4>
+
+If there are many loggers that use logger inheritance,
+it's occasionally a good idea to show the full ancestry of a logger in the log 
+statement. Here's how to set up PatternFormatter to show the full ancestry 
+of a logger in a logging statement (in XML):
+
+<div class="example">
+<pre class="box">&lt;formatter type="PatternFormatter"&gt;
+  &lt;!-- %C shows full ancestry --&gt;
+  &lt;pattern&gt;[%l %C] %m&lt;/pattern&gt;
+&lt;/formatter&gt;</pre>
+</div>
+
+For a logger named 'me' with ancestors 'cain::grandpa::pa', it will produce:
+
+<div class="example">
+<pre class="box">[DEBUG cain::grandpa::pa::me] Log message</pre>
+</div>
+
+<p><hr noshade color="#AA0000">
+<a name="nullobj">
+  <h4 ><a href="#toc">The Null Logger</a></h4>
+In addition to being the parent of all loggers, Logger.root is a null
+object. That means that it does absolutely nothing when its log methods are
+invoked. Its query methods always return false and it has no outputters.
+It is useful to turn loggers off from within code:
+
+<div class="example">
+  <pre class="box">noisylog = Logger.root
+noisy.debug "This won't do anything"</pre>
+</div>
+
+<p><hr noshade color="#AA0000">
+<a name="gotchas">
+<h4 ><a href="#toc">Gotchas</a></h4>
+
+If you are using Log4r, there are a few gotchas that you should be aware of:
+
+<ul>
+<li>Logger levels can be dynamically redefined, but the change won't be 
+noticed by any children. That is, if you set <code>root.level=OFF</code> 
+<i>after</i> defining some loggers, none of the loggers will change their level 
+to <code>OFF</code>. There is a good reason for this behavior.
+</li>
+<li>Dynamically redefining levels, tracing or additivity is expensive. It's 
+best to set up all your loggers in a config script and avoid making dynamic
+changes to Log4r objects. The dynamism is most useful for debugging and 
+development, where local control of logging is a great convenience.
+</li>
+<li>When an <code>IOOutputter</code>'s <code>IO</code> is closed,
+the <code>IOOutputter</code> changes its level to <code>OFF</code>
+</li>
+</ul>
+
+<p><hr noshade color="#AA0000">
+<a name="performance">
+<h4 ><a href="#toc">Performance</a></h4>
+
+Profiling has revealed that log4r is typically an order of magnitude or
+two slower than log4j. However, this is still damn fast! In particular,
+if a logger is set to <code>OFF</code>, the overhead of checking to
+see if a log event should be logged nearly vanishes. This was accomplished by
+dynamically redefining the unloggable logging methods to do nothing.
+<p/>
+In the future, Log4r's performance critical features will be written as a C
+extension to Ruby. It will still be optional, but it will be available for
+those who absolutely need to squeeze every last ounce of performance out of
+Log4r. (No longer in the works, unfortunately.)
+<p><hr noshade color="#AA0000">
+<a name="project">
+<h4 ><a href="#toc">The Project Itself</a></h4>
+Log4r was initially developed by one person and is slowly but surely gaining
+popularity and new developers. Please refer to the 
+<a href="contact.html">contact</a> page for more information on the
+developers.
+
+</td></tr>