Author: seb Date: Thu Jan 11 11:45:53 2007 New Revision: 1193 Modified: logback/trunk/logback-site/src/site/xdocTemplates/shortIntro.xml Log: Modifications to short intro 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 Thu Jan 11 11:45:53 2007 @@ -956,12 +956,12 @@ <p>The logback environment is fully configurable programmatically. However, it is far more flexible to configure logback using - configuration files. In logback, configuration files are expressed - in XML. + configuration files. In logback, configuration files are written + in XML format. </p> <p>Existing log4j users can convert their - <em>log4j.properties</em> files to <em>logback.xml</em> using <a + <em>log4j.properties</em> files to <em>logback.xml</em> using our <a href="http://logback.qos.ch/translator/">PropertiesTranslator</a> web-application. </p> @@ -970,7 +970,7 @@ the help of a trivial application named <em>MyApp</em>. </p> - <em>Example 1.4: Basic configuration (<a href="xref/chapter1/MyApp.html">logback-examples/src/main/java/chapter1/MyApp.java</a>)</em> + <em>Example 1.3: BasicConfigurator sample usage (<a href="xref/chapter1/MyApp.html">logback-examples/src/main/java/chapter1/MyApp.java</a>)</em> <div class="source"><pre>package chapter1; // Import SLF4J classes. @@ -1000,7 +1000,7 @@ object. The <code>Bar</code> class is listed below: </p> - <em>Example 1.4: Basic configuration (<a href="xref/chapter1/Bar.html">logback-examples/src/main/java/chapter1/Bar.java</a>)</em> + <em>Example 1.3: Sample logging class (<a href="xref/chapter1/Bar.html">logback-examples/src/main/java/chapter1/Bar.java</a>)</em> <div class="source"><pre>package chapter1; import org.slf4j.Logger; @@ -1016,13 +1016,13 @@ }</pre></div> <p>The invocation of the <code>configureDefaultContext()</code> - method in <code>BasicConfigurator</code> creates, as we have seen - previously, a minimal logback setup. Note that, by default, the - root Logger is assigned to Level.DEBUG. + method in <code>BasicConfigurator</code> creates a minimal logback setup. + Note that, by default, the root Logger is assigned to <code>Level.DEBUG</code>. </p> <p> - The output of MyApp is: + Running <code>MyApp</code>, by issuing the command <em>java chapter1.MyApp</em>, + will produce the following output: </p> <div class="source"><pre>22:05:21.461 [main] INFO chapter1.MyApp - Entering application. 22:05:21.461 [main] DEBUG chapter1.Bar - doing my job @@ -1047,7 +1047,7 @@ application so that logging environment is configured at runtime. </p> - <em>Example 1.5: Logback configuration from file ((<a + <em>Example 1.4: Logback configuration from file ((<a href="xref/chapter1/MyAppWithConfigFile.html">logback-examples/src/main/java/chapter1/MyAppWithConfigFile.java</a>)</em> <div class="source"><pre>package chapter1; @@ -1079,12 +1079,10 @@ } }</pre></div> - <p>MyApp2 instructs PropertyConfigurator to parse a configuration - file and to set up logging according to the instructions found - therein. The sample configuration file listed below, also - available as examples/chapter3/sample0.properties, configures - log4j (after parsing by PropertyConfigurator) in the same way as - BasicCon-figurator.configure. + <p>MyAppWithConfigFile instructs <code>JoranConfigurator</code> + to parse a configuration file and to set up logging according to + the instructions found + therein. </p> <p>Let us configure logback in the exact same way, @@ -1092,7 +1090,7 @@ configuration file, once executed, will have the same affect as calling <code>BasicConfigrator</code>.</p> - <em>Example 1.4: Basic configuration (logback-examples/src/main/java/chapter1/sample-config-1.xml)</em> + <em>Example 1.5: Basic configuration with a xml file (logback-examples/src/main/java/chapter1/sample-config-1.xml)</em> <div class="source"><pre><?xml version="1.0" encoding="UTF-8" ?> <configuration> @@ -1111,8 +1109,8 @@ </configuration></pre></div> <p>We first created an <code>Appender</code>, named <em>STDOUT</em> - that is of <code>ConsoleAppender</code> tye. Its layout is managed - by a PatternLayout, that uses the value of the "pattern" parameter + that is of <code>ConsoleAppender</code> type. Its layout is managed + by a <code>PatternLayout</code>, that uses the value of the <em>pattern</em> parameter to generate the logging statement. We then configured the root logger, set its level to DEBUG, and linked the newly configured <code>ConsoleAppender</code> to the root logger.</p> @@ -1122,19 +1120,18 @@ <p>To run this examle, use this command:</p> -<div class="source"><pre>java chapter1.MyApp src/main/java/chapter1/sample-config-1.xml</pre></div> +<div class="source"><pre>java chapter1.MyAppWithConfigFile src/main/java/chapter1/sample-config-1.xml</pre></div> <p>The console output will be exactly the same as before. However, - this time, we didn't need to import and call the BasicConfigurator - class, as you can see in the following code section: + this time, we didn't need to import and call the <code>BasicConfigurator</code> + class. </p> - - <p>We used the JoranConfigurator class to parse the configuration + <p>We used the <code>JoranConfigurator</code> class to parse the configuration file we just created. Joran is a XML interpreter, similar to the commons-digester API, but offering several advantages over commons-digester. Here, it parses the xml file and runs actions - depending on the tags it finds. To setup the JoranConfigurator + depending on the tags it finds. To setup the <code>JoranConfigurator</code> properly, we passed the <code>LoggerContext</code>. A <code>LoggerContext</code> is the class that creates and manages Loggers in logback. It is also the class that implements the @@ -1145,7 +1142,7 @@ configure logback so that it logs to the console, but also to a custom file.</p> -<em>Example 1.5: Logback configuration from file (logback-examples/src/main/java/chapter1/sample-config-2.xml)</em> +<em>Example 1.6: Configuring logback with multiple appenders (logback-examples/src/main/java/chapter1/sample-config-2.xml)</em> <div class="source"><pre><?xml version="1.0" encoding="UTF-8" ?> <configuration> @@ -1174,18 +1171,18 @@ <p>Now, all the logging statements are directed to the console and to a file named <em>sample-log.txt</em>. As you can see, the - configuration needed to add an Appender is rather small. The param - element, in either Appender configuration, reads the <em>name</em> - attribute and assigns its value to the corresponding attribute in + configuration needed to add an Appender is rather small. The options + are declared as xml element, in either Appender configuration. They are + read and their value are assigned to the corresponding attribute in the specified java class. </p> <p>Suppose that we do not want to see the DEBUG level statements in the chapter1 package anymore. This is done by adding the following - xml snippet to the configuration file, right before the + bold xml snippet to the configuration file, right before the <code><root></code> element.</p> -<em>Example 1.5: Logback configuration from file (logback-examples/src/main/java/chapter1/sample-config-3.xml)</em> +<em>Example 1.7: Configuring a specific logger (logback-examples/src/main/java/chapter1/sample-config-3.xml)</em> <div class="source"><pre><?xml version="1.0" encoding="UTF-8" ?> <configuration> @@ -1217,7 +1214,7 @@ </configuration> </pre></div> - <p>This done, the output is modified to show only statements of level INFO and higher.</p> + <p>Once done, the output is modified to show only statements of level INFO and higher:</p> <div class="source"><pre>0 [main] INFO chapter1.MyAppWithConfigFile - Entering application. 0 [main] INFO chapter1.MyAppWithConfigFile - Exiting application.</pre></div>