%description
Log::Log4perl lets you remote-control and fine-tune the logging behaviour
-of your system from the outside. It implements the widely popular (Java-
-based) Log4j logging package in pure Perl.
+of your system from the outside. It implements the widely popular
+(Java-based) Log4j logging package in pure Perl.
+
+*For a detailed tutorial on Log::Log4perl usage, please read*
+
+ http://www.perl.com/pub/a/2002/09/11/log4perl.html
+
+Logging beats a debugger if you want to know what's going on in your code
+during runtime. However, traditional logging packages are too static and
+generate a flood of log messages in your log files that won't help you.

-Authors:
---------
- Mike Schilli <m@xxxxxxxxxxxxxxx>
- Kevin Goess <cpan@xxxxxxxxx>
+'Log::Log4perl' is different. It allows you to control the number of
+logging messages generated at three different levels:
+
+* *
+
+ At a central location in your system (either in a configuration file or
+ in the startup code) you specify _which components_ (classes, functions)
+ of your system should generate logs.
+
+* *
+
+ You specify how detailed the logging of these components should be by
+ specifying logging _levels_.
+
+* *
+
+ You also specify which so-called _appenders_ you want to feed your log
+ messages to ("Print it to the screen and also append it to /tmp/my.log")
+ and which format ("Write the date first, then the file name and line
+ number, and then the log message") they should be in.
+
+This is a very powerful and flexible mechanism. You can turn on and off
+your logs at any time, specify the level of detail and make that dependent
+on the subsystem that's currently executed.
+
+Let me give you an example: You might find out that your system has a
+problem in the 'MySystem::Helpers::ScanDir' component. Turning on detailed
+debugging logs all over the system would generate a flood of useless log
+messages and bog your system down beyond recognition. With 'Log::Log4perl',
+however, you can tell the system: "Continue to log only severe errors to
+the log file. Open a second log file, turn on full debug logs in the
+'MySystem::Helpers::ScanDir' component and dump all messages originating
+from there into the new log file". And all this is possible by just
+changing the parameters in a configuration file, which your system can
+re-read even while it's running!