Author: ceki Date: Sat Nov 4 00:37:55 2006 New Revision: 870 Modified: logback/trunk/logback-site/src/site/fml/faq.fml logback/trunk/logback-site/src/site/xdocTemplates/documentation.xml logback/trunk/logback-site/src/site/xdocTemplates/manual/index.xml logback/trunk/logback-site/src/site/xdocTemplates/news.xml logback/trunk/logback-site/src/site/xdocTemplates/shortIntro.xml Log: ongoing work Modified: logback/trunk/logback-site/src/site/fml/faq.fml ============================================================================== --- logback/trunk/logback-site/src/site/fml/faq.fml (original) +++ logback/trunk/logback-site/src/site/fml/faq.fml Sat Nov 4 00:37:55 2006 @@ -2,48 +2,47 @@ <document> - <body> + <body> - <faqs title="Logback Frequently Asked Questions"> - <part id="Logback Classic"> - <title>Logback Classic</title> - - <faq id="setup_jetty"> - - <question> - How can I use logback classic with Jetty ? + <faqs title="Logback Frequently Asked Questions"> + <part id="Logback Classic"> + <title>Logback Classic</title> + + <faq id="setup_jetty"> + + <question> + How can I use logback-classic with Jetty ? </question> <answer> - <p> - A few jars must be present in the + <p> + A few jars must be present in the <em>JETTY_HOME/lib</em> directory. </p> - <p> - Logback uses the SLF4J api. Therefore, the - <em>slf4j-api-VERSION.jar</em> - jar must be present. This jar can be found - by <a href="http://www.slf4j.org">downloading SLF4J</a>. + + <p> + Logback-classic is based on the SLF4J api. Therefore, + the <em>slf4j-api-VERSION.jar</em> jar must be + present. This jar can be downloaded from the <a + href="http://www.slf4j.org/">SLF4J</a> project. </p> <p> - Logback's own jars must also be present. - These are - <em>logback-classic-VERSION.jar</em> - and - <em>logback-core-VERSION.jar</em> - . + Logback's own jars must also be present, namely + <em>logback-core-VERSION.jar</em> and + <em>logback-classic-VERSION.jar</em> . </p> + + + <!-- should logback.xml really be placed in JETTY_HOME? --> + <p> - To configure logback classic, a file called - <em>logback-classic.xml</em> - must be placed at the root directory of - Jetty, that is the - <em>JETTY_HOME</em> - directory. You can find configuration - samples in the - <em>examples/src/chapter4/conf/</em> - directory, in the distribution of logback. + To configure logback-classic, a file called + <em>logback.xml</em> should be placed at the root + directory of Jetty, that is the <em>JETTY_HOME</em> + directory. You can find configuration samples in the + <em>examples/src/chapter4/conf/</em> directory, in the + distribution of logback. </p> </answer> </faq> Modified: logback/trunk/logback-site/src/site/xdocTemplates/documentation.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/documentation.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/documentation.xml Sat Nov 4 00:37:55 2006 @@ -10,21 +10,26 @@ <h2>Logback documentation</h2> - <p>Below is a list of documentaiton currently available for the - logback project.</p> + <p>Below is a list of logback-related documentaiton currently + available.</p> <ul> <li> <a href="shortIntro.html"><b>A short introduction to logback-classic</b></a> </li> + + + <li><a href="manual/index.html"><b>The logback manual</b></a></li> + <li> - <a href="access.html"><b>A short introduction to access logging Jetty and Tomcat</b></a> + <a href="access.html">An introduction to access for Jetty + and Tomcat</a> </li> <li> - <a href="joran.html"><b>A introduction to Joran</b></a> + <a href="joran.html">A introduction to Joran</a> </li> <li> - <a href="faq.html"><b>A Frequently Asked Questions list (FAQ)</b></a> + <a href="faq.html">A Frequently Asked Questions list (FAQ)</a> </li> </ul> @@ -35,20 +40,13 @@ <a href="apidocs/index.html"><b>Javadoc</b></a> </li> <li> - <a href="xref/index.html"><b>Source code</b></a> + <a href="xref/index.html">Source code</a> </li> <li> - <a href="xref-test/index.html"><b>Test classes source code</b></a> + <a href="xref-test/index.html">Test classes source code</a> </li> </ul> - <p>A complete manual about logback is in the works at the moment. Each chapter will be - put online as soon as it's complete. You can access the manual page by following the link - below.</p> - - <ul> - <li><a href="manual/index.html"><b>Complete logback manual</b></a></li> - </ul> </body> </document> \ No newline at end of file Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/index.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/manual/index.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/manual/index.xml Sat Nov 4 00:37:55 2006 @@ -8,21 +8,65 @@ <body> - <h2>Logback manual</h2> - - <p>Welcome to the main page of the logback manual.</p> - - <p>At the moment, only one chapter is available. More to come.</p> - - <p>Printing notice: if you want to print this document, you might want to - use <a href="http://www.getfirefox.com">Firefox</a>, with <em>Adapt to page size</em> enabled, - or <a href="http://www.opera.com">Opera</a> for better rendering on paper.</p> - - <ul> - <li> - <a href="layouts.html"><b>Manual Chapter 5: Layout reference</b></a> - </li> - </ul> + <h2>The logback manual</h2> + <p>The complete logback manual documents the latest version of + logback framework. In over 100 pages and dozens of concrete + examples, it covers both basic and advanced logback features: + </p> + + <div> + <ul> + <li><p>the overall logback architecture</p></li> + <li><p>discussion of best logback practices and anti-patterns</p></li> + <li><p>logback configuration scripts in properties format</p></li> + <li><p>logback configuration scripts in XML format</p></li> + <li><p>appenders</p></li> + <li><p>layouts</p></li> + <li><p>filter chains</p></li> + <li><p>logback diagnostic contexts</p></li> + <li><p>logback default initialization</p></li> + <li><p>logback in Servlet Containers</p></li> + </ul> + </div> + + + <div class="highlight"> + <p> + If you wish to print chapters in this document, we recommend + that you do so using <a + href="http://www.getfirefox.com">Firefox</a>, with <em>Adapt to + page size</em> enabled, or <a + href="http://www.opera.com">Opera</a>. + </p> + </div> + + <p>The logback manual describes the logback API in considerable + detail, including its features and design rationale. Authored by + Ceki Ceki Gülcü and Sebastien Pennec, the main + contributors to the logback project, the logback manual is + intended for developers already familiar with the Java language + but new to logback, as much as for experienced logback users. With + the aid of introductory material and many examples, new users + should quickly come up to speed. + </p> + + + + + + <div> + <p>Without further ado, here are the contents of the manual:</p> + + <ul> + <li><p> + <a href="layouts.html"><b>Chapter 4: Appenders</b></a> + </p></li> + + <li><p> + <a href="layouts.html"><b>Chapter 5: Layouts</b></a> + </p></li> + </ul> + </div> </body> </document> \ No newline at end of file Modified: logback/trunk/logback-site/src/site/xdocTemplates/news.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/news.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/news.xml Sat Nov 4 00:37:55 2006 @@ -6,113 +6,113 @@ <title>${pom.name} download</title> </properties> - <body> - <h2>Logback News</h2> - - <p>Here are the last news about the project.</p> + <body> + <h2>Logback News</h2> - <h3>October 26th, 2006 - 0.5 version available</h3> - <p> - Version 0.5 for all three logback modules is now available. - </p> - <p> - This release offers a big improvement in Joran. Joran is now able to - replay configuration elements. + <p>Here are the lastest news about logback.</p> + + <h3>October 26th, 2006 - Release of version 0.5</h3> + + <p> + Version 0.5 of logback has been released. </p> - <p> - Logback's documentation has also been improved. A complete reference on - Layouts is available in the logback manual directory, as well as a FAQ page. + + <p> + This release offers a important improvements in Joran. In + particular, Joran can now replay configuration elements. </p> - <p> - An archive containing source code, binaries and docs is available - at the <a href="download.html">download page</a>. + + <p> + As in the previous released, a major area of work is the + documentation which is being continously improved. </p> - <hr width="50%" align="center" /> + <hr width="80%" align="center" /> - <h3>October 9th, 2006 - 0.4 version available</h3> + <h3>October 9th, 2006 - Release of version 0.4</h3> <p> - Version 0.4 for all three logback modules is now available. + Version 0.3 of logback has been released. </p> - <p> - This release offers a much improved access module, with specific implementations - for the Jetty and Tomcat servers. Documentation was also added to show how - to integrate logback access with Jetty. - </p> - <p> - Outside of the access module, several appenders and layouts have been added or improved. - The error reporting of logback is also improved, prompting the user with - a link to an online page presenting possible reasons for the error. - </p> - <p> - A joran documentation was added, with examples in the core module. - </p> - <p> - An archive containing source code, binaries and docs is available - at the <a href="download.html">download page</a>. + + <p> + This release includes an improved access module, with specific + implementations for the Jetty and Tomcat servers. Documentation + was also added to show how to integrate logback-access with + Jetty. + </p> + + <p> + As for the classic module, several appenders and layouts have + been added or improved. The error reporting of logback has also + been enhanced, presenting the user with a link to an online page + explaining possible reasons for the error. + </p> + + <p> + A joran documentation was added, with examples in the core + module. </p> - - <hr width="50%" align="center" /> + + <hr width="80%" align="center" /> - <h3>September 8th, 2006 - 0.3 version available</h3> + <h3>September 8th, 2006 - Release of version 0.3</h3> <p> - Version 0.3 for all three logback modules is now available. + Version 0.3 of logback has been released. </p> + <p> - This release offers several new Appenders, support for Mapped Diagnostic Context, - improved tests and documentation<br /> - </p> - <p> - In response to a bug report by Rickard Nilsson on the logback mailing list, - a bug affecting parametrized logging was fixed. + This release offers several new Appenders, support for Mapped + Diagnostic Context, improved tests and documentation<br /> </p> - <p> - We also released a <a href="http://logback.qos.ch/translator/">PropertiesTranslator</a> - webapp that converts <em>log4j.properties</em> files to joran configuration files (in XML format).<br /> - </p> - <p> - An archive containing source code, binaries and docs is available - at the <a href="download.html">download page</a>. + + <p> + In response to a bug report by Rickard Nilsson on the logback + mailing list, a bug affecting parametrized logging was fixed. </p> - <hr width="50%" align="center" /> + <p> + We also released a <a + href="http://logback.qos.ch/translator/">PropertiesTranslator</a> + webapp that converts <em>log4j.properties</em> files to joran + configuration files (in XML format).<br /> + </p> + + <hr width="80%" align="center" /> - <h3>August 23th, 2006 - 0.2.5 version available</h3> - <p> - Version 0.2.5 for all three logback modules is now available. + <h3>August 23th, 2006 - Release of version 0.2.5</h3> + + <p> + Version 0.2.5 of logback has been released. </p> + <p> - This release offers a better documentation. The introduction document to logback classic - was corrected and improved. - An archive containing source code, binaries and docs is available - at the <a href="download.html">download page</a>. + This release offers better documentation. With a number of + correction mande in the short introduction to logback-classic. </p> - <hr width="50%" align="center" /> + <hr width="80%" align="center" /> - <h3>August 15th, 2006 - 0.2 version available</h3> - <p> - Version 0.2 for all three logback modules is now available. - </p> + <h3>August 15th, 2006 - Release of version 0.2</h3> <p> - It offers better tests, a few more functionalities, and enhanced documentation. - We also improved the site design to make it simpler and more efficient. + Version 0.2 of logback has been released. </p> - <hr width="50%" align="center" /> - - <h3>July 26th, 2006 - 0.1 version available</h3> - <p> - A first version 0.1 for all three logback modules is now available. + <p> + It offers better tests, a few more functionalities, and enhanced + documentation. We also improved the site design to make it + simpler and more efficient. </p> - <p> - The archives containing source code and binaries of all - modules are downloadable from the download - pages. + + <hr width="80%" align="center" /> + + <h3>July 26th, 2006 - Release of version 0.1</h3> + + <p> + Version 0.1 of logback has been released. </p> - <hr width="50%" align="center" /> + <hr width="80%" align="center" /> <h3>February 9th, 2006 - Logback web-site goes live</h3> <p> Modified: logback/trunk/logback-site/src/site/xdocTemplates/shortIntro.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/shortIntro.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/shortIntro.xml Sat Nov 4 00:37:55 2006 @@ -228,7 +228,7 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; -<b>import ch.qos.logback.BasicConfigurator;</b> +<b>import ch.qos.logback.classic.BasicConfigurator;</b> import ch.qos.logback.classic.util.LoggerStatusPrinter; public class HelloWorld3 { @@ -243,9 +243,11 @@ }</pre></div> <p> - Let's run the <code>HelloWorld3</code> - application. Now, the <code>BasicConfigurator</code> - will create a simple <code>ConsoleAppender</code>. + Let's run the <code>HelloWorld3</code> application. In this + example, the <code><a + href="xref/ch/qos/logback/classic/BasicConfigurator.html">BasicConfigurator</a></code> + class's <code>configureDefaultContext()</code> method is + invoked. It will create a simple <code>ConsoleAppender</code>. The logging request will then be propagated to the <code>Appender</code> and the console will output the following: </p> @@ -253,8 +255,8 @@ <p> This example is rather simple. However, actual logging in a - larger application would not be much different. The general - pattern logging statements will barely change. Only the + larger application would not be any different. The general + pattern logging statements will not change. Only the configuration process will be different since you don't need (nor should) configure the logging context in each and every class that requires logging. As you will see later on in this @@ -267,17 +269,25 @@ <!-- ========= CEKI: STOPPED HERE =================== --> <p> - These are the three steps that are required to enable logging in your application. + Here is a list of the three required steps in order to enable + logging in your application. </p> <ol> - <li>Configure the logback environment. You can do it using several - sophisticated ways. The BasicConfigurator is the simplest but also least flexible. More on this later.</li> - <li>In every class where you wish to perform logging, retrieve a Logger - instance by invoking the LoggerFactory and passing the current class as the parameter.</li> - <li>Use this logger instance by invoking its printing methods, namely - the debug(), info(), warn() and error() methods. Produce logging output on the - configured appenders.</li> + + <li>Configure the logback environment. You can do it using + several sophisticated ways. The BasicConfigurator is the + simplest but also least flexible. More on this later.</li> + + <li>In every class where you wish to perform logging, retrieve a + Logger instance by invoking the + <code>org.slf4j.LoggerFactory</code> class' + <code>getLogger()</code> method, passing the current class' name + or the class itself as parameter.</li> + + <li>Use this logger instance by invoking its printing methods, + namely the debug(), info(), warn() and error() methods. This + will produce logging output on the configured appenders.</li> </ol> @@ -291,26 +301,25 @@ messages are formatted and where they are reported. </p> <p> - Loggers are defined in the classic module. On the other - hand, Appenders and Layouts are defined in the core module - of logback. + The Logger class is part of the classic module. On the other + hand, Appenders and Layouts are part of the core + module. Interestingly enough, the core has no notion of loggers. </p> <h3>Logger context</h3> - <p> - The first and foremost advantage of any logging API over - plain <code>System.out.println</code> resides in its ability to disable - certain log statements while allowing others to print - unhindered. This capability assumes that the logging space, - that is, the space of all possible logging statements, is - categorized according to some developer-chosen criteria. - This categorization is an inherent part of loggers. + <p>The first and foremost advantage of any logging API over plain + <code>System.out.println</code> resides in its ability to disable + certain log statements while allowing others to print + unhindered. This capability assumes that the logging space, that + is, the space of all possible logging statements, is categorized + according to some developer-chosen criteria. This categorization + is an inherent part of loggers. </p> <p> - Loggers are named entities. Their names are case-sensitive and they follow the - hierarchical naming rule: + Loggers are named entities. Their names are case-sensitive and + they follow the hierarchical naming rule: </p> <div class="definition"> <div class="deftitle">Named Hierarchy</div> @@ -1017,7 +1026,7 @@ import org.slf4j.LoggerFactory; import org.slf4j.Logger; -import ch.qos.logback.BasicConfigurator; +import ch.qos.logback.classic.BasicConfigurator; public class MyApp {