[slf4j-dev] svn commit: r756 - in slf4j/trunk/slf4j-site/src/site/resources: . css
ceki at slf4j.org
ceki at slf4j.org
Sat Feb 24 16:00:14 CET 2007
Author: ceki
Date: Sat Feb 24 16:00:14 2007
New Revision: 756
Modified:
slf4j/trunk/slf4j-site/src/site/resources/css/site.css
slf4j/trunk/slf4j-site/src/site/resources/docs.html
slf4j/trunk/slf4j-site/src/site/resources/download.html
slf4j/trunk/slf4j-site/src/site/resources/faq.html
slf4j/trunk/slf4j-site/src/site/resources/mailing-lists.html
Log:
- improving documentation
Modified: slf4j/trunk/slf4j-site/src/site/resources/css/site.css
==============================================================================
--- slf4j/trunk/slf4j-site/src/site/resources/css/site.css (original)
+++ slf4j/trunk/slf4j-site/src/site/resources/css/site.css Sat Feb 24 16:00:14 2007
@@ -145,7 +145,7 @@
}
#content {
- margin: 0px 15em 0px 16em;
+ margin: 0px 17em 0px 17em;
padding: 0px;
background-color: #ffffff;
}
@@ -215,6 +215,10 @@
font-weight: bold;
}
+.big {
+ font-size: 130%;
+}
+
.green {
color: green;
}
Modified: slf4j/trunk/slf4j-site/src/site/resources/docs.html
==============================================================================
--- slf4j/trunk/slf4j-site/src/site/resources/docs.html (original)
+++ slf4j/trunk/slf4j-site/src/site/resources/docs.html Sat Feb 24 16:00:14 2007
@@ -31,6 +31,15 @@
<li><a href="faq.html">FAQ</a></li>
</ul>
+ <h2>Articles</h2>
+
+ <ul>
+ <li><a
+ href="http://eclipsezone.com/articles/franey-logging/?source=archives">Universal
+ Logger Plug-ins for RCP Applications</a>, by John J. Franey
+ </li>
+ </ul>
+</h2>
</div>
</body>
Modified: slf4j/trunk/slf4j-site/src/site/resources/download.html
==============================================================================
--- slf4j/trunk/slf4j-site/src/site/resources/download.html (original)
+++ slf4j/trunk/slf4j-site/src/site/resources/download.html Sat Feb 24 16:00:14 2007
@@ -23,12 +23,12 @@
<h2>Latest official SLF4J version</h2>
- <p>Download version 1.2 including <i>full source code</i>,
+ <p>Download version 1.3 including <i>full source code</i>,
class files and documentation in ZIP or TAR.GZ format: </p>
<ul>
- <li><a href="dist/slf4j-1.2.tar.gz"><b>slf4j-1.2.tar.gz</b></a> </li>
- <li><a href="dist/slf4j-1.2.zip"><b>slf4j-1.2.zip</b></a> </li>
+ <li><a href="dist/slf4j-1.3.tar.gz"><b>slf4j-1.3.tar.gz</b></a> </li>
+ <li><a href="dist/slf4j-1.3.zip"><b>slf4j-1.3.zip</b></a> </li>
</ul>
Modified: slf4j/trunk/slf4j-site/src/site/resources/faq.html
==============================================================================
--- slf4j/trunk/slf4j-site/src/site/resources/faq.html (original)
+++ slf4j/trunk/slf4j-site/src/site/resources/faq.html Sat Feb 24 16:00:14 2007
@@ -18,60 +18,117 @@
<script src="templates/right.js"></script>
</div>
<div id="content">
- <div class="section"><h2><a name="top">Frequently Asked Questions about SLF4J</a></h2><p><b>Generalities</b></p><ol type="1"><li><a href="#what_is">
- What is SLF4J?
- </a></li><li><a href="#when">
- When should SLF4J be used?
- </a></li><li><a href="#yet_another_facade">
- Is SLF4J yet another logging facade?
- </a></li><li><a href="#why_new_project">
- If SLF4J fixes JCL, then why wasn't the fix made in JCL
- instead of creating a new project?
- </a></li><li><a href="#need_to_recompile">
- When using SLF4J, do I have to recompile my application
- to switch to a different logging system?
- </a></li><li><a href="#license">
- Why is SLF4J licensed under X11 type license instead of the
- Apache Software License?
- </a></li><li><a href="#where_is_binding">
- Where can I get a particular SLF4J binding?
- </a></li><li><a href="#configure_logging">
- Should my library attempt to configure logging?
- </a></li></ol><b>About the SLF4J API</b><ol type="1"><li><a href="#string_or_object">
- Why don't the printing methods in the Logger interface
- accept message of type Object, but only messages of type
- String?
- </a></li><li><a href="#exception_message">
+
+ <div class="section">
+
+ <h2><a name="top">Frequently Asked Questions about SLF4J</a></h2><p><b>Generalities</b></p>
+
+ <ol type="1">
+ <li><a href="#what_is">What is SLF4J?</a></li>
+ <li><a href="#when">When should SLF4J be used?</a></li>
+
+ <li><a href="#yet_another_facade"> Is SLF4J yet another loggingfacade?</a></li>
+
+ <li><a href="#why_new_project"> If SLF4J fixes JCL, then why
+ wasn't the fix made in JCL instead of creating a new project?
+ </a></li>
+
+ <li><a href="#need_to_recompile"> When using SLF4J, do I have to
+ recompile my application to switch to a different logging
+ system? </a></li>
+
+ <li><a href="#license"> Why is SLF4J licensed under X11 type
+ license instead of the Apache Software License? </a></li>
+
+ <li><a href="#where_is_binding"> Where can I get a particular
+ SLF4J binding? </a></li>
+
+ <li><a href="#configure_logging"> Should my library attempt to
+ configure logging?
+ </a>
+ </li>
+ </ol>
+
+
+ <b>About the SLF4J API</b>
+
+ <ol type="1">
+
+ <li><a href="#string_or_object"> Why don't the printing methods
+ in the Logger interface accept message of type Object, but only
+ messages of type String? </a></li>
+
+ <li><a href="#exception_message">
Can I log an exception without an accompanying message?
- </a></li><li><a href="#logging_performance">
- What is the fastest way of (not) logging?
- </a></li><li><a href="#string_contents">
- How can I log the string contents of a single (possibly
- complex) object?
- </a></li><li><a href="#fatal">
- Why doesn't the <code>org.slf4j.Logger</code> interface
- have methods for the FATAL level?
- </a></li><li><a href="#trace">
- Why doesn't the <code>org.slf4j.Logger</code> interface
- have methods for the TRACE level?
- </a></li></ol><b>Implementing the SLF4J API</b><ol type="1"><li><a href="#slf4j_compatible">
- How do I make my logging framework SLF4J
- compatible?
- </a></li><li><a href="#marker_interface">
- How can my logging system add support for
- the <code>Marker</code> interface?
- </a></li></ol><b>General questions about logging</b><ol type="1"><li><a href="#declared_static">
- Should Logger members of a class be declared as static?
- </a></li></ol></div><div class="section"><h2>Generalities</h2><dl><dt><a name="what_is">
- What is SLF4J?
- </a></dt><dd>
+ </a></li>
+
+
+ <li><a href="#logging_performance"> What is the fastest way of
+ (not) logging? </a></li>
+
+ <li><a href="#string_contents"> How can I log the string
+ contents of a single (possibly complex) object? </a></li>
+
+
+ <li><a href="#fatal"> Why doesn't the
+ <code>org.slf4j.Logger</code> interface have methods for the
+ FATAL level? </a></li>
+
+ <li><a href="#trace"> Why doesn't the
+ <code>org.slf4j.Logger</code> interface have methods for the
+ TRACE level? </a></li></ol>
+
+
+ <b>Implementing the SLF4J API</b>
+
+ <ol type="1">
+
+ <li><a href="#slf4j_compatible"> How do I make my logging
+ framework SLF4J compatible? </a></li>
+
+ <li><a href="#marker_interface"> How can my logging system add
+ support for the <code>Marker</code> interface? </a></li>
+
+ </ol>
+
+
+ <b>General questions about logging</b>
+
+
+ <ol type="1">
+
+ <li><a href="#declared_static"> Should Logger members of a class
+ be declared as static? </a></li>
+
+ </ol>
+
+ </div>
+
+
+ <div class="section">
+
+ <h2>Generalities</h2>
+
+ <dl>
+ <dt><a name="what_is">What is SLF4J?</a></dt>
+ <dd>
<p>SLF4J is a simple facade for logging systems allowing the
end-user to plug-in the desired logging system at deployment
time.
</p>
- <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /></dd><dt><a name="when">
- When should SLF4J be used?
- </a></dt><dd>
+
+
+ <table border="0">
+ <tr><td align="right"><a href="#top">[top]</a></td></tr>
+ </table>
+ <hr />
+ </dd>
+
+ <dt><a name="when">
+ When should SLF4J be used?
+ </a></dt>
+
+ <dd>
<p>In short, libraries and other embedded components should
consider SLF4J for their logging needs because libraries
cannot afford to impose their choice of logging system on the
@@ -107,24 +164,39 @@
to be made.
</p>
- <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /></dd><dt><a name="yet_another_facade">
- Is SLF4J yet another logging facade?
- </a></dt><dd>
- <p>SLF4J is conceptually similar to JCL. As such, it can be
- thought of as yet another logging facade. However, SLF4J is
- orders of magnitude simpler in design and arguably more
- robust.
- </p>
- <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /></dd><dt><a name="why_new_project">
- If SLF4J fixes JCL, then why wasn't the fix made in JCL
- instead of creating a new project?
- </a></dt><dd>
- <p>This is a very good question. First, SLF4J static binding
- approach is very simple, perhaps even laughably so. It was not
- easy to convince developers of the validity of the
- approach. It is only after SLF4J was released and started to
- become accepted did the approach gain respectability in the
- relevant community.
+ <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr>
+ </table><hr />
+
+ </dd>
+
+ <dt>
+ <a name="yet_another_facade">
+ Is SLF4J yet another logging facade? </a></dt>
+
+ <dd>
+ <p>SLF4J is conceptually similar to JCL. As such, it can be
+ thought of as yet another logging facade. However, SLF4J is
+ orders of magnitude simpler in design and arguably more
+ robust.
+ </p>
+
+ <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
+
+ </dd>
+ <dt>
+ <a name="why_new_project">
+ If SLF4J fixes JCL, then why wasn't the fix made in JCL
+ instead of creating a new project?
+ </a>
+ </dt>
+
+ <dd>
+ <p>This is a very good question. First, SLF4J static binding
+ approach is very simple, perhaps even laughably so. It was
+ not easy to convince developers of the validity of the
+ approach. It is only after SLF4J was released and started to
+ become accepted did the approach gain respectability in the
+ relevant community.
</p>
<p>Second, SLF4J offers two enhancements which developers
@@ -136,14 +208,18 @@
open to switching back to more traditional logging systems if
need be.
</p>
- <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /></dd><dt><a name="need_to_recompile">
- When using SLF4J, do I have to recompile my application
- to switch to a different logging system?
- </a></dt><dd>
- No, you do not need to recompile your application. You can
- switch to a different logging system by removing the previous
- SLF4J binding and replacing it with the binding of your
- choice.
+
+ <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /></dd>
+
+ <dt><a name="need_to_recompile">
+ When using SLF4J, do I have to recompile my application
+ to switch to a different logging system?
+ </a></dt>
+
+ <dd>
+ No, you do not need to recompile your application. You can
+ switch to a different logging system by removing the previous
+ SLF4J binding and replacing it with the binding of your choice.
<p>For example, if you were using the NOP implementation and
would like to switch to log4j version 1.2, simply replace
@@ -152,37 +228,64 @@
well. Want to switch to JDK 1.4 logging? Just replace
<em>slf4j-log4j12.jar</em> with <em>slf4j-jdk14.jar</em>.
</p>
- <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /></dd><dt><a name="license">
- Why is SLF4J licensed under X11 type license instead of the
- Apache Software License?
- </a></dt><dd>
- <p>SLF4J is licensed under a permissive X11 type license
- instead of the <a href="http://www.apache.org/licenses/">ASL</a> or the <a href="http://www.gnu.org/copyleft/lesser.html">LGPL</a>
- because the X11 license is deemed by both the Apache Software
- Foundation as well as the Free Software Foundation as
- compatible with their respective licenses.
- </p>
- <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /></dd><dt><a name="where_is_binding">
- Where can I get a particular SLF4J binding?
- </a></dt><dd>
- <p>SLF4J bindings for <a href="api/org/slf4j/impl/SimpleLogger.html">SimpleLogger</a>,
- <a href="api/org/slf4j/impl/NOPLogger.html">NOPLogger</a>, <a href="api/org/slf4j/impl/Log4jLoggerAdapter.html">LoggerLoggerAdapter</a>
- and <a href="api/org/slf4j/impl/JDK14LoggerAdapter.html">JDK14LoggerAdapter</a>
+
+ <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr>
+ </table><hr />
+ </dd>
+ <dt>
+ <a name="license">
+ Why is SLF4J licensed under X11 type license instead of the
+ Apache Software License?
+ </a>
+ </dt>
+
+ <dd>
+ <p>SLF4J is licensed under a permissive X11 type license
+ instead of the <a
+ href="http://www.apache.org/licenses/">ASL</a> or the <a
+ href="http://www.gnu.org/copyleft/lesser.html">LGPL</a>
+ because the X11 license is deemed by both the Apache Software
+ Foundation as well as the Free Software Foundation as
+ compatible with their respective licenses.
+ </p>
+
+ <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr>
+ </table><hr />
+ </dd>
+ <dt>
+ <a name="where_is_binding">
+ Where can I get a particular SLF4J binding?
+ </a>
+ </dt>
+
+ <dd>
+
+ <p>SLF4J bindings for <a
+ href="api/org/slf4j/impl/SimpleLogger.html">SimpleLogger</a>,
+ <a href="api/org/slf4j/impl/NOPLogger.html">NOPLogger</a>, <a
+ href="api/org/slf4j/impl/Log4jLoggerAdapter.html">LoggerLoggerAdapter</a>
+ and <a
+ href="api/org/slf4j/impl/JDK14LoggerAdapter.html">JDK14LoggerAdapter</a>
are contained within the files <em>slf4j-nop.jar</em>,
- <em>slf4j-simple.jar</em>, <em>slf4j-log4j12.jar</em>,
- <em>slf4j-log4j13.jar</em> and <em>slf4j-jdk14.jar</em>. These
- files ship with the <a href="download.html">official SLF4J
- distribution</a>. Please note that all binding depend on
- <em>slf4j-api.jar</em>.
+ <em>slf4j-simple.jar</em>, <em>slf4j-log4j12.jar</em>, and
+ <em>slf4j-jdk14.jar</em>. These files ship with the <a
+ href="download.html">official SLF4J distribution</a>. Please
+ note that all binding depend on <em>slf4j-api.jar</em>.
</p>
- <p>The binding for logback-classic ships with the <a href="http://logback.qos.ch/download.html">logback
+ <p>The binding for logback-classic ships with the <a
+ href="http://logback.qos.ch/download.html">logback
distribution</a>. However, as with all other bindings, the
logback-classic binding requires <em>slf4j-api.jar</em>.
</p>
- <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /></dd><dt><a name="configure_logging">
- Should my library attempt to configure logging?
- </a></dt><dd>
+
+ <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /></dd>
+
+ <dt><a name="configure_logging"> Should my library attempt to
+ configure logging? </a>
+ </dt>
+
+ <dd>
<p>Embedded components such as libraries do not need and
should not configure the logging system. They invoke SLF4J to
log but should let the end-user configure the logging
@@ -192,20 +295,37 @@
logs and process them. She should be the person to decide how
she wants her logging configured.
</p>
- <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table></dd></dl></div><div class="section"><h2>About the SLF4J API</h2><dl><dt><a name="string_or_object">
- Why don't the printing methods in the Logger interface
- accept message of type Object, but only messages of type
- String?
- </a></dt><dd>
+
+ <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr>
+ </table>
+ </dd>
+ </dl>
+ </div>
+
+ <div class="section">
+
+
+ <h2>About the SLF4J API</h2>
+
+ <dl>
+
+ <dt><a name="string_or_object"> Why don't the printing methods
+ in the Logger interface accept message of type Object, but only
+ messages of type String? </a>
+ </dt>
+
+ <dd>
<p>In SLF4J 1.0beta4, the printing methods such as debug(),
- info(), warn(), error() in the <a href="api/org/slf4j/Logger.html">Logger interface</a> were
+ info(), warn(), error() in the <a
+ href="api/org/slf4j/Logger.html">Logger interface</a> were
modified so as to accept only messages of type String instead
of Object.
</p>
<p>Thus, the set of printing methods for the DEBUG level
became:</p>
+
<p class="source">debug(String msg);
debug(String format, Object arg);
debug(String format, Object arg1, Object arg2);
@@ -234,22 +354,30 @@
information could be lost. When the first parameter is
restricted to be of type String, then only the method
</p>
- <p class="source">debug(String msg, Throwable t)</p>
-
- <p>can be used to log exceptions. Note that this method
- ensures that every logged exception is accompanied with a
- descriptive message.</p>
- <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /></dd><dt><a name="exception_message">
- Can I log an exception without an accompanying message?
- </a></dt><dd>
- <p>In short, no.</p>
-
- <p>If <code>e</code> is an <code>Exception</code>, and you
- would like to log an exception at the ERROR level, you must
- add an accompanying message. For example,</p>
-
- <p class="source">logger.error("some accompanying message", e);</p>
+ <p class="source">debug(String msg, Throwable t)</p>
+
+ <p>can be used to log exceptions. Note that this method
+ ensures that every logged exception is accompanied with a
+ descriptive message.</p>
+
+ <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
+ </dd>
+
+ <dt>
+
+ <a name="exception_message">
+ Can I log an exception without an accompanying message?
+ </a>
+ </dt>
+ <dd>
+ <p>In short, no.</p>
+
+ <p>If <code>e</code> is an <code>Exception</code>, and you
+ would like to log an exception at the ERROR level, you must
+ add an accompanying message. For example,</p>
+ <p class="source">logger.error("some accompanying message", e);</p>
+
<p>You might correctly observe that not all exceptions have a
meaningful message to accompany them. Moreover, a good
exception should already contain a self explanatory
@@ -291,9 +419,16 @@
accompanying message as a good a thing (TM).
</p>
- <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /></dd><dt><a name="logging_performance">
- What is the fastest way of (not) logging?
- </a></dt><dd>
+ <table border="0">
+
+ <tr>
+ <td align="right">
+ <a href="#top">[top]</a></td></tr></table><hr />
+ </dd>
+
+ <dt><a name="logging_performance"> What is the fastest way of
+ (not) logging?</a></dt><dd>
+
<p> For some Logger <code>logger</code>, writing,</p>
<p class="source">logger.debug("Entry number: " + i + " is " + String.valueOf(entry[i]));</p>
@@ -302,9 +437,7 @@
<code>entry[i]</code> to a String, and concatenating
intermediate strings. This, regardless of whether the message
will be logged or not.
- </p>
-
-
+ </p>
<p>One possible way to avoid the cost of parameter
construction is by surrounding the log statement with a
@@ -315,16 +448,14 @@
}</p>
- <p>
- This way you will not incur the cost of parameter
- construction if debugging is disabled for
- <code>logger</code>. On the other hand, if the logger is
- enabled for the DEBUG level, you will incur the cost of
- evaluating whether the logger is enabled or not, twice: once
- in <code>debugEnabled</code> and once in <code>debug</code>.
- This is an insignificant overhead because evaluating a
- logger takes less than 1% of the time it takes to actually
- log a statement.
+ <p>This way you will not incur the cost of parameter
+ construction if debugging is disabled for
+ <code>logger</code>. On the other hand, if the logger is
+ enabled for the DEBUG level, you will incur the cost of
+ evaluating whether the logger is enabled or not, twice: once in
+ <code>debugEnabled</code> and once in <code>debug</code>. This
+ is an insignificant overhead because evaluating a logger takes
+ less than 1% of the time it takes to actually log a statement.
</p>
Modified: slf4j/trunk/slf4j-site/src/site/resources/mailing-lists.html
==============================================================================
--- slf4j/trunk/slf4j-site/src/site/resources/mailing-lists.html (original)
+++ slf4j/trunk/slf4j-site/src/site/resources/mailing-lists.html Sat Feb 24 16:00:14 2007
@@ -75,8 +75,8 @@
<a href="http://www.slf4j.org/pipermail/announce/">Pipermail</a> |
<a href="http://marc.theaimsgroup.com/?l=slf4j-announce">MARC</a>
</p>
- <p>The announcements list is reserved for important SLF4J API or
- NLOG4J related announcements. As such, the traffic on this list is
+ <p>The announcements list is reserved for important SLF4J API
+ related announcements. As such, the traffic on this list is
guaranteed to be very low.
</p>
@@ -118,9 +118,14 @@
<a href="http://marc.theaimsgroup.com/?l=slf4j-dev">MARC</a> |
<a href="http://www.mail-archive.com/dev%40slf4j.org/">MailArchive</a> </p>
<p> </p>
+
<h2>On IRC</h2>
- <p>We can also be reached by IRC at irc.freenode.net#slf4j. </p>
+
+ <p>We can also be reached by IRC at <span
+ class="big"><code>irc.freenode.net#slf4j</code></span>. </p>
+
<p> </p>
+
</div>
</body>
</html>
More information about the slf4j-dev
mailing list