Author: ceki Date: Wed Feb 28 22:30:52 2007 New Revision: 1372 Modified: logback/trunk/logback-site/src/site/pages/css/site.css logback/trunk/logback-site/src/site/pages/manual/index.html logback/trunk/logback-site/src/site/pages/manual/introduction.html logback/trunk/logback-site/src/site/pages/manual/layouts.html Log: ongoing work on the documentaiton Modified: logback/trunk/logback-site/src/site/pages/css/site.css ============================================================================== --- logback/trunk/logback-site/src/site/pages/css/site.css (original) +++ logback/trunk/logback-site/src/site/pages/css/site.css Wed Feb 28 22:30:52 2007 @@ -24,6 +24,7 @@ div.source { margin-top: 1em; } + .source { border-top: 1px solid #DDDDDD; border-bottom: 1px solid #DDDDDD; @@ -35,6 +36,17 @@ white-space: pre; } +.command { + border-top: 1px solid #DDDDDD; + border-bottom: 1px solid #DDDDDD; + background:#eee; + font-family: Courier, "MS Courier New", Prestige, Everson Monocourrier, monospace; + padding-bottom: 0ex; + padding-top: 0ex; + padding-left: 1ex; + white-space: pre; +} + pre { padding: 0px; margin: 0px; Modified: logback/trunk/logback-site/src/site/pages/manual/index.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/index.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/index.html Wed Feb 28 22:30:52 2007 @@ -21,7 +21,7 @@ <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 + logback framework. In over 140 pages and dozens of concrete examples, it covers both basic and advanced logback features: </p> Modified: logback/trunk/logback-site/src/site/pages/manual/introduction.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/introduction.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/introduction.html Wed Feb 28 22:30:52 2007 @@ -57,20 +57,20 @@ <p> Logback is intended as a successor to the popular log4j project. - It was designed by Ceki Gülcü, the log4j founder. - It builds upon a decade long experience gained in - designing industrial-strength logging systems. The resulting - product, logback is faster with a smaller footprint than all - existing logging systems, sometimes by a wide margin. Logback - also offers unique and rather useful features such as Markers, - parameterized logging statements, conditional stack tracing and - powerful event filtering. These are only few examples of useful - features logback has to offer. For its own error reporting, - logback relies on <code>Status</code> objects, which greatly - facilitate troubleshooting. You may wish to rely on Status - objects in contexts other than logging. Logback-core bundles - Joran, a powerful and generic configuration system, which can be - put to use in your own projects to great effect. + It was designed by Ceki Gülcü, log4j's founder. It + builds upon a decade long experience gained in designing + industrial-strength logging systems. The resulting product, + logback is faster with a smaller footprint than all existing + logging systems, sometimes by a wide margin. Logback also offers + unique and rather useful features such as Markers, parameterized + logging statements, conditional stack tracing and powerful event + filtering. These are only few examples of useful features + logback has to offer. For its own error reporting, logback + relies on <code>Status</code> objects, which greatly facilitate + troubleshooting. You may wish to rely on Status objects in + contexts other than logging. Logback-core bundles Joran, a + powerful and generic configuration system, which can be put to + use in your own projects to great effect. </p> <h2>First Baby Step</h2> @@ -239,30 +239,27 @@ <a name="BuildingLogback"></a> <h3>Building logback</h3> -<p> -Like many java applications today, logback relies on <a href="http://maven.apache.org"> -Maven 2</a> as its build tool. Maven 2 is a free open source build tool that requires -one or more build files names <em>pom.xml</em> which already ship with logback -distributions. -</p> - -<p> -Building all logback components is mostly done by issuing the <em>mvn compile</em> -line in a terminal or command window. Maven 2 will automatically download the required -external libraries and use them. However, a library cannot be downloaded from -the Maven 2 repository. Libraries such as <code>JMS</code> -from sun require a separate download and to issue a command to install their -jars into your local repository. The required command will be presented -by Maven 2 in your console when trying to compile logback. -</p> - -<p> -Logback distributions contain complete source code such that you can modify parts -of logback library and build your own version of it. You may even -redistribute the modified version, as long as you adhere to the conditions -of the LGPL License. In particular you may not call the modified version <em>logback</em> -or claim that it is endorsed by the QOS.ch. -</p> + <p>Like many java applications today, logback relies on <a + href="http://maven.apache.org"> Maven 2</a> as its build tool. Maven + 2 is a free open source build tool that requires one or more build + files names <em>pom.xml</em> which already ship with logback + distributions. + </p> + + <p>Building all logback modules is mostly done by issuing the + <em>mvn package</em> line in a terminal or command window. Maven + will automatically download the required external libraries and use + them. However, certain artefacts cannot be downloaded from the + Maven2 repository. Libraries such as <code>JMS</code> from SUN Inc. + need to be downloaded and installed separately into your local + repository. + </p> + + <p>Logback distributions contain complete source code such that you + can modify parts of logback library and build your own version of + it. You may even redistribute the modified version, as long as you + adhere to the conditions of the LGPL License. + </p> Modified: logback/trunk/logback-site/src/site/pages/manual/layouts.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/layouts.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/layouts.html Wed Feb 28 22:30:52 2007 @@ -143,42 +143,49 @@ }</pre></div> <p> - Note that - <code>MySampleLayout</code> - extends <a href="../xref/ch/qos/logback/core/LayoutBase.html"> - <code>LayoutBase</code></a>. - This class manages trivial components of a <code>Layout</code> - such as started or stopped status, header, footer and - content type access or logging context awareness. It allows - the developer to concentrate on the formatting she expects - from her <code>Layout</code>. Note that the <code>LayoutBase</code> - class is generic. By extending it, we precise the type that it will - have to handle, by adding <em><LoggingEvent></em> after its declaration. - </p> - - <p>The marginally more interesting <code>doLayout(LoggingEvent event)</code> - method begins by instantiating a StringBuffer. It proceeds by adding various - fields of the event parameter. The Texan from Texas was careful to print - the formatted form of the message and not its object form. - This allows for logging requests which are passed object arrays to - build the message in its proper form. - </p> - <p> - In the above listing of the <code>Layout</code> class, - we had omitted the class static <code>LINE_SEP</code> - field which is simply assigned the value returned by - <code>System.getProperty("line.separator")</code> - method. After adding system dependent line separator - character(s), the format method returns the string buffer as - a String. - </p> - <p> - The <code>doLayout</code> method ignores any eventual exceptions contained - in the event. In a real world layout implementation, you would probably not want - to silently ignore exceptions. + Note that <code>MySampleLayout</code> extends <a + href="../xref/ch/qos/logback/core/LayoutBase.html"> + <code>LayoutBase</code></a>. This class manages state shared by + all <code>Layout</code> classes, such as whether the layout is + started or stopped, header, footer and content type data. It + allows the developer to concentrate on the formatting she + expects from her <code>Layout</code>. Note that the + <code>LayoutBase</code> class is generic. In its class + declaration, <code>MySampleLayout</code> extends a typed + <code>LayoutBase</code>, + <code>LayoutBase<LoggingEvent></code>, instead of generic + one. + </p> + + <p>The <code>doLayout(LoggingEvent event)</code> method, i.e. the + only method in <code>MySampleLayout</code>, begins by + instantiating a <code>StringBuffer</code>. It proceeds by adding + various fields of the event parameter. The Texan from Texas was + careful to print the formatted form of the message. This is + important when there are one or more parameters passed along with + the logging request. + </p> + + <p>In the above listing of the <code>Layout</code> class, the + <code>LINE_SEP</code> field is inherited from the + <code>Layout</code> interface. It refers to the value returned by + <code>System.getProperty("line.separator")</code> method, that is + system dependent line separator character(s). After adding these + system dependent character(s), the <code>doLayout()</code> method + converts <code>sbuf</code> to <code>String</code> and returns the + resulting value. + </p> + + <p>In the above example, the <code>doLayout</code> method ignores + any eventual exceptions contained in the event. In a real world + layout implementation, you would most probably want to print the + contents of exceptions as well. </p> - <p>Custom layouts are configured as any other layout, as shown below:</p> + <h3>Configuringyour custom layout</h3> + + <p>Custom layouts are configured as any other layout. Here is as + example:</p> <em>Example 5.0: Configuration of MySampleLayout (logback-examples/src/main/java/chapter5/sampleLayoutConfig.xml)</em> @@ -201,23 +208,26 @@ followed by an error message. </p> <p> - To run this example execute the command - <em>java chapter5.SampleLogging src/main/java/chapter5/sampleLayoutConfig.xml</em> - once in the <em>logback-examples</em> directory. This will produce the following - output: - </p> + To run this example issue the following command from within the + <em>logback-examples</em> directory. + </p> + + <p class="command">java chapter5.SampleLogging src/main/java/chapter5/sampleLayoutConfig.xml</p> + + <p> This will produce:</p> <div class="source"><pre>0 DEBUG [main] chapter5.SampleLogging - Everything's going well -0 ERROR [main] chapter5.SampleLogging - ... not quite</pre></div> +0 ERROR [main] chapter5.SampleLogging - maybe not quite...</pre></div> - <p>That was simple enough. - The skeptic Pyrrho of Elea, who insists that nothing is certain except - perhaps uncertainty itself, which is by no means certain either, - might ask: how about a layout with options? - The reader shall find a slightly modified version of our - custom layout in <code>MySampleLayout2.java</code>. She will discover that adding an option - to a layout is as simple as declaring a setter method for the option. + <p>That was simple enough. The skeptic Pyrrho of Elea, who + insists that nothing is certain except perhaps uncertainty itself, + which is by no means certain either, might ask: how about a layout + with options? The reader shall find a slightly modified version + of our custom layout in <code>MySampleLayout2.java</code>. She + will discover that adding an option to a layout is as simple as + declaring a setter method for the option. </p> + <p> The <a href="../xref/chapter5/MySampleLayout2.html"><code>MySampleLayout2</code> @@ -269,17 +279,26 @@ } }</pre></div> - <p>Appart from the actual use of the two attributes, in the <code>doLayout</code> method, - the two setter methods are the only addition to the original class. Yet, it is sufficient - to allow the user to configure these attributes, as shown in the configuration file below:</p> + + <!-- ====================== XXXXXXXXXXXXx --> + <p>The addition of the corresponding setter method is all that is + needed to enable the configuration of an option. Note that the + <code>PrintThreadName</code> attribute is a boolean and not a + <code>String</code>. It can be configured anyway by writing + <em>true</em> of <em>false</em> in the configuration + file.Configuration of logback components was covered in detail in + <a href="chapter3.html">"Chapter 3: Logback configuration with + Joran"</a>. Here is a configuration file adapted for + <code>MySampleLayout2</code>. + </p> <div class="source"><pre><configuration> <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <layout class="chapter5.MySampleLayout2"> - <b><prefix>MyPrefix</prefix> - <printThreadName>false</printThreadName></b> + <b><prefix>MyPrefix</prefix></b> + <b><printThreadName>false</printThreadName></b> </layout> </appender> @@ -290,9 +309,7 @@ </configuration></pre></div> <p> - Note that the <code>PrintThreadName</code> attribute is a boolean - and not a <code>String</code>. It can be configured anyway by writing <em>true</em> - of <em>false</em> in the configuration file. + </p>