Title: Log4r - Manual
Template: main.html
Id: $Id$

<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>