[logback-dev] svn commit: r1777 - in logback/trunk: logback-examples/src/main/java/chapter4 logback-site/src/site/pages logback-site/src/site/pages/manual

noreply.ceki at qos.ch noreply.ceki at qos.ch
Mon Aug 25 21:54:06 CEST 2008


Author: ceki
Date: Mon Aug 25 21:54:06 2008
New Revision: 1777

Modified:
   logback/trunk/logback-examples/src/main/java/chapter4/ExitWoes1.java
   logback/trunk/logback-site/src/site/pages/jmxConfig.html
   logback/trunk/logback-site/src/site/pages/manual/appenders.html
   logback/trunk/logback-site/src/site/pages/manual/contextSelector.html
   logback/trunk/logback-site/src/site/pages/manual/filters.html
   logback/trunk/logback-site/src/site/pages/manual/joran.html
   logback/trunk/logback-site/src/site/pages/manual/layouts.html
   logback/trunk/logback-site/src/site/pages/manual/mdc.html

Log:
Related to LBSITE-16

Documentation improvements many of which have been proposed by Anton Tagunov.


Modified: logback/trunk/logback-examples/src/main/java/chapter4/ExitWoes1.java
==============================================================================
--- logback/trunk/logback-examples/src/main/java/chapter4/ExitWoes1.java	(original)
+++ logback/trunk/logback-examples/src/main/java/chapter4/ExitWoes1.java	Mon Aug 25 21:54:06 2008
@@ -1,7 +1,7 @@
 /**
- * Logback: the reliable, generic, fast and flexible logging framework.
+ * Logback: the generic, reliable, fast and flexible logging framework.
  * 
- * Copyright (C) 1999-2006, QOS.ch
+ * Copyright (C) 2000-2008, QOS.ch
  * 
  * This library is free software, you can redistribute it and/or modify it under
  * the terms of the GNU Lesser General Public License as published by the Free
@@ -25,7 +25,7 @@
 
   public static void main(String[] args) throws Exception {
     LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory();
-    lc.shutdownAndReset();//this is to cancel default-config.
+    lc.shutdownAndReset(); // we want to override the default-config.
     WriterAppender<LoggingEvent> writerAppender = new WriterAppender<LoggingEvent>();
     writerAppender.setContext(lc);
     writerAppender.setLayout(new EchoLayout<LoggingEvent>());

Modified: logback/trunk/logback-site/src/site/pages/jmxConfig.html
==============================================================================
--- logback/trunk/logback-site/src/site/pages/jmxConfig.html	(original)
+++ logback/trunk/logback-site/src/site/pages/jmxConfig.html	Mon Aug 25 21:54:06 2008
@@ -23,45 +23,45 @@
 	
     <h2>JMX Configurator</h2>
     
-		<p>
-			As of version 0.8, logback ships with a component that allows 
-			configuration via JMX. Basically, it lets you reload the current
-			configuration, load a new one, list loggers and modify logger levels.
+		<p>As of version 0.8, logback ships with a component that allows
+		configuration via JMX. Basically, it lets you reload the current
+		configuration, load a new one, list loggers and modify logger
+		levels.
 		</p>
 		
 		<h3>Configuring your server</h3>
-		<p>
-			The first step is to make sure that your application server will 
-			allow the JMX Configurator to publish itself. In this document,
-			we'll cover the necessary steps in Tomcat and Jetty.
+
+		<p>The first step is to make sure that your application server
+		will allow the JMX Configurator to publish itself. In this
+		document, we'll cover the necessary steps in Tomcat and Jetty.
 		</p>
 		
 		<h4>Configuring Tomcat</h4>
-		<p>
-			Accessing JMX components with Tomcat requires to add the following lines
-			to the <em>$TOMCAT_HOME/bin/catalina.sh</em> configuration file:
+    
+    <p>Accessing JMX components with Tomcat requires to add the
+    following lines to the <em>$TOMCAT_HOME/bin/catalina.sh</em>
+    configuration file:
 		</p>
 		
 <div class="source"><pre>CATALINA_OPTS="-Dcom.sun.management.jmxremote"
 CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.ssl=false"
 CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.authenticate=false"</pre></div>
 
-		<p>
-			Once started with these options, Tomcat's JMX compoenents can be accessed
-			with JConsole by issuing the following command in a shell:
+		<p>Once started with these options, Tomcat's JMX compoenents can
+		be accessed with JConsole by issuing the following command in a
+		shell:
 		</p>
 <div class="source"><pre>jconsole &amp;</pre></div>
 
-		<p>
-			You might prefer to access your components via a web-based solution using MX4J. 
-			In that case, here are the required steps:
+		<p>You might prefer to access your components via a web-based
+		solution using MX4J.  In that case, here are the required steps:
 		</p>
 		
-		<p>
-			First, <a href="http://mx4j.sourceforge.net/">download MX4J</a>. 
-			Place the <em>mx4j-impl.jar</em> file in
-			the <em>$TOMCAT_HOME/bin/</em> directory, and the <em>mx4j-tools.jar</em>
-			in the <em>$TOMCAT_HOME/common/lib/</em> directory.
+		<p>First, <a href="http://mx4j.sourceforge.net/">download
+		MX4J</a>.  Place the <em>mx4j-impl.jar</em> file in the
+		<em>$TOMCAT_HOME/bin/</em> directory, and the
+		<em>mx4j-tools.jar</em> in the <em>$TOMCAT_HOME/common/lib/</em>
+		directory.
 		</p>
 		
 		<p>Then, add the following lines to the
@@ -87,19 +87,17 @@
   mx.httpPort="8082" 
   protocol="AJP/1.3" /></pre></div>
   
-  	<p>
-  		Once Tomcat is started, you should be ableo to reach the JMX components by
-  		pointing a browser to the following URL:
+  	<p>Once Tomcat is started, you should be able to reach the JMX
+  	components by pointing a browser to the following URL:
   	</p>
 
 <div class="source"><pre>http://host_name:8082/</pre></div>
 
 		<h4>Configuring Jetty</h4>
 		
-		<p>
-			Configuring Jetty to publish JMX components requires a few modifications to the
-			<em>$JETTY_HOME/etc/jetty.xml</em> configuration file. Here are the elements that need to be
-			added:
+		<p>Configuring Jetty to publish JMX components requires a few
+		modifications to the <em>$JETTY_HOME/etc/jetty.xml</em>
+		configuration file. Here are the elements that need to be added:
 		</p>
 
 <div class="source"><pre>&lt;Call id="MBeanServer" class="java.lang.management.ManagementFactory" name="getPlatformMBeanServer"/>
@@ -116,18 +114,17 @@
   &lt;/Call>
 &lt;/Get></pre></div>
 
-		<p>
-			Once Jetty is started with this configuration, all available components can be reviewed
-			at this address:
+		<p>Once Jetty is started with this configuration, all available
+		components can be reviewed at this address:
 		</p>
 <div class="source"><pre>http://host_name:8082/</pre></div>
 
 
 		<h3>Using the JMX Configurator</h3>
 		
-		<p>
-			The next step is to declare the JMX Configurator in the logback configuration
-			file. This is done by adding a single element, as shown below:
+		<p>The next step is to declare the JMX Configurator in the logback
+		configuration file. This is done by adding a single element, as
+		shown below:
 		</p>
 
 <div class="source"><pre>&lt;configuration>
@@ -146,58 +143,49 @@
   &lt;/root>  
 &lt;/configuration></pre></div>
 		
-		<p>
-			Once the JMX Configurator is displayed on your screen, there are
-			several operations available.
+		<p>Once the JMX Configurator is displayed on your screen, there
+		are several operations available.
 		</p>
 		
 		<ul>
-      <p>Display the logback Statuses
-      </p>
-			<p>Reload the configuration using the same file that was previously
-			used.
-			</p>
-			<p>Reload the configuration using a file whose path is passed as
-			a parameter.</p>
-			<p>
-				Reload the configuration using a file whose URL is passed as a
-				parameter.
-			</p>
-			<p>
-				Get the level of a logger
-			</p>
-			<p>
-				Change the level setting of a specified logger.
-			</p>
-			<p>
-				Change a list of all declared loggers.
-			</p>
-			<p>
-				Change the level setting of a specified logger.
-			</p>
+      <li>Display the logback Status </li>
+
+      <li>Reload the configuration using the same file that was previously
+			used. </li>
+
+      <li>Reload the configuration using a file whose path is passed
+      as a parameter.</li>
+
+			<li>Reload the configuration using a file whose URL is passed as
+			a parameter.</li>
+
+			<li>Get the level of a logger</li>
+			<li>Change the level setting of a specified logger.</li>
+			<li>Change a list of all declared loggers.</li>
+			<li>Change the level setting of a specified logger.</li>
 		</ul>
 		
-		<p>
-			In the last case, you must specify the name of the logger you wish to
-			alter, and its new level.
+		<p>In the last case, you must specify the name of the logger you
+		wish to alter, and its new level.
 		</p>
-		<p>
-			The level of a logger is a value that can be null, if no specific level
-			has been configured for said logger. Its effective level, on the other
-			hand, is given with respect to the parent loggers' levels. This value cannot
-			be null, since all loggers are direct or indirect children of the root
-			logger, whose level is always set. When trying to get the level or effective 
-			level of a logger, the name of the logger has to be passed as a parameter.
-			Note that trying to get the level or effective level for a nonexistent logger
-			will not return any result.
+
+		<p>The level of a logger is a value that can be null, if no
+		specific level has been configured for said logger. Its effective
+		level, on the other hand, is given with respect to the parent
+		loggers' levels. This value cannot be null, since all loggers are
+		direct or indirect children of the root logger, whose level is
+		always set. When trying to get the level or effective level of a
+		logger, the name of the logger has to be passed as a parameter.
+		Note that trying to get the level or effective level for a
+		nonexistent logger will not return any result.
 		</p>
     
-    <p>
-      Displaying logback Statuses via JMX can help users check the internal state
-      of logback. It shows if anything has gone wrong, if rollovers occured 
-      as expected, and many other useful informations. It is also very useful
-      when reloading a configuration, since the user can immediately see if 
-      the configuration file was successfully processed.
+    <p>Displaying logback status via JMX can help users check the
+    internal state of logback. It shows if anything has gone wrong, if
+    rollovers occured as expected, as well as other useful
+    information. It is also very useful when reloading a
+    configuration, since the user can immediately see if the
+    configuration file has been procsseds successfully.
     </p>
 		
 	

Modified: logback/trunk/logback-site/src/site/pages/manual/appenders.html
==============================================================================
--- logback/trunk/logback-site/src/site/pages/manual/appenders.html	(original)
+++ logback/trunk/logback-site/src/site/pages/manual/appenders.html	Mon Aug 25 21:54:06 2008
@@ -298,9 +298,10 @@
 import java.io.OutputStream;
 import java.io.OutputStreamWriter;
 
-import org.slf4j.Logger;
+
 import org.slf4j.LoggerFactory;
 
+import ch.qos.logback.classic.Logger;
 import ch.qos.logback.classic.LoggerContext;
 import ch.qos.logback.core.WriterAppender;
 import ch.qos.logback.core.layout.EchoLayout;
@@ -309,16 +310,19 @@
 
   public static void main(String[] args) throws Exception {
     LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory();
+    lc.shutdownAndReset(); // we want to override the default-config.
     WriterAppender&lt;LoggingEvent> writerAppender = new WriterAppender&lt;LoggingEvent>();
     writerAppender.setContext(lc);
-    writerAppender.setLayout(new EchoLayout&lt;LoggingEvent>());
+    writerAppender.setLayout(new EchoLayout&lt;&lt;LoggingEvent>());
 
     OutputStream os = new FileOutputStream("exitWoes1.log");
     writerAppender.setWriter(new OutputStreamWriter(os));
     writerAppender.setImmediateFlush(false);
     writerAppender.start();
+    Logger root = lc.getLogger(LoggerContext.ROOT_NAME);
+    root.addAppender(writerAppender);
 
-    Logger logger = LoggerFactory.getLogger(ExitWoes1.class);
+    Logger logger = lc.getLogger(ExitWoes1.class);
 
     logger.debug("Hello world.");
   }
@@ -681,11 +685,10 @@
 	</p>
 
 	<p>The <span class="option">FileNamePattern</span> option represents
-	the file name pattern for the archived (rolled over) log files.  The
-	<span class="option">FileNamePattern</span> option, which is also
-	required, must include an integer token, that is the string
+	the file name pattern for the archived (rolled over) log files.
+	This option is required and must include an integer token
 	<em>%i</em> somewhere within the pattern.
-	</p>
+  </p>
 	
 	<p>Here are the available options for
 	<code>FixedWindowRollingPolicy</code>
@@ -865,14 +868,13 @@
 	</p>
 	
 	<p><span class="option">FileNamePattern</span> option defines the
-	name of the rolled (archived) log files. Its value <span
-	class="option">FileNamePattern</span> should consist of the name of
-	the file, plus a suitably placed <em>%d</em> conversion specifier.
-	The <em>%d</em> conversion specifier may contain a date-and-time
-	pattern as specified by the <code>java.text.SimpleDateFormat</code>
-	class.  If the date-and-time pattern is omitted, then the default
-	pattern <em>yyyy-MM-dd</em> is assumed. The following examples
-	should clarify the point.
+	name of the rolled (archived) log files. Its value should consist of
+	the name of the file, plus a suitably placed <em>%d</em> conversion
+	specifier.  The <em>%d</em> conversion specifier may contain a
+	date-and-time pattern as specified by the
+	<code>java.text.SimpleDateFormat</code> class.  If the date-and-time
+	pattern is omitted, then the default pattern <em>yyyy-MM-dd</em> is
+	assumed. The following examples should clarify the point.
 	</p>
 
 	<table class="bodyTable">

Modified: logback/trunk/logback-site/src/site/pages/manual/contextSelector.html
==============================================================================
--- logback/trunk/logback-site/src/site/pages/manual/contextSelector.html	(original)
+++ logback/trunk/logback-site/src/site/pages/manual/contextSelector.html	Mon Aug 25 21:54:06 2008
@@ -207,7 +207,7 @@
 
 <div class="source"><pre>&lt;listener>
   &lt;listener-class>ch.qos.logback.classic.selector.servlet.ContextDetachingSCL&lt;/listener-class>
-&lt;/listener</pre></div>
+&lt;/listener></pre></div>
 
 
   <p>Using the <code>ContextJNDISelector</code> might slow down your

Modified: logback/trunk/logback-site/src/site/pages/manual/filters.html
==============================================================================
--- logback/trunk/logback-site/src/site/pages/manual/filters.html	(original)
+++ logback/trunk/logback-site/src/site/pages/manual/filters.html	Mon Aug 25 21:54:06 2008
@@ -54,48 +54,55 @@
 		<h2>Logback Classic</h2>
 		
 		<a name="Filter"></a>
-		<p><code>Filter</code> objects all implement the 
-		<a href="../xref/ch/qos/logback/core/filter/Filter.html"><code>Filter</code></a> 
-		abstract class. The <code>decide(Object event)</code> method is passed a
-		newly created <code>LoggingEvent</code> object.
+
+		<p><code>Filter</code> objects all extend the <a
+		href="../xref/ch/qos/logback/core/filter/Filter.html"><code>Filter</code></a>
+		abstract class. The <code>decide(Object event)</code> method is
+		passed a newly created <code>LoggingEvent</code> object.
 		</p>
 		
 		<h3>Filter chains</h3>
-		<p>
-			This abstract class assumes that filters be organized in a linear chain. 
-			Its member field next points to the next filter in the chain, or 
-			<code>null</code> if there are no further filters in the chain. 
-			Figure 6.1 depicts a sample filter chain consisting of three filters.
+
+		<p>This abstract class assumes that filters are organized in a
+		linear chain.  Its member field next points to the next filter in
+		the chain, or <code>null</code> if there are no further filters in
+		the chain.  Figure 6.1 depicts a sample filter chain consisting of
+		three filters.
 		</p>
 		
 		<img src="images/chapter6/filterChain.gif" alt="A sample filter chain"/>
 
-    <p>
-    	Filters are based on ternary logic. The <code>decide(Object event)</code> 
-    	method of each filter is called in sequence. This method returns one of the 
-    	enumerations <code>FilterReply.DENY</code>, <code>FilterReply.NEUTRAL</code> or 
-    	<code>FilterReply.ACCEPT</code>. If the returned value is <code>FilterReply.DENY</code>, 
-    	then the log event is dropped immediately without consulting the 
-    	remaining filters. If the value returned is <code>FilterReply.NEUTRAL</code>, 
-    	then the next filter in the chain is consulted. If there are no further filters 
-    	to consult, then the logging event is processed normally. 
-    	If the returned value is <code>FilterReply.ACCEPT</code>, then the logging 
-    	event is processed immediately skipping the remaining filters.
+    <p>Filters are based on ternary logic. The <code>decide(Object
+    event)</code> method of each filter is called in sequence.  This
+    method returns one of the <a
+    href="../xref/ch/qos/logback/core/spi/FilterReply.html"><code>FilterReply</code></a>
+    enumeration values, i.e. one of <code>FilterReply.DENY</code>,
+    <code>FilterReply.NEUTRAL</code> or
+    <code>FilterReply.ACCEPT</code>.  If the returned value is
+    <code>FilterReply.DENY</code>, then the log event is dropped
+    immediately without consulting the remaining filters. If the value
+    returned is <code>FilterReply.NEUTRAL</code>, then the next filter
+    in the chain is consulted. If there are no further filters to
+    consult, then the logging event is processed normally.  If the
+    returned value is <code>FilterReply.ACCEPT</code>, then the
+    logging event is processed immediately skipping the remaining
+    filters.
     </p>
     
-    <p>
-    	In logback-classic, <code>Filter</code> objects can only be added to <code>Appender</code>
-    	instances. By adding filters to an appender you can filter events by various 
-    	criteria, such as the contents of the log message, the contents of the MDC, 
-    	the time of day or any other part of the logging event.
+    <p>In logback-classic <code>Filter</code> objects can only be
+    added to <code>Appender</code> instances. By adding filters to an
+    appender you can filter events by various criteria, such as the
+    contents of the log message, the contents of the MDC, the time of
+    day or any other part of the logging event.
     </p>
     
 		<h3>Implementing your own Filter</h3>
 		
-		<p>
-			Creating your own filter is not difficult. All you have to do is extend the <code>Filter</code> 
-			abstract class. The only method that you will have to implement is the <code>decide()</code> 
-			method, allowing you to contentrate only on the behaviour of your filter.
+		<p>Creating your own filter is not difficult. All you have to do
+		is extend the <code>Filter</code> abstract class. The only method
+		that you will have to implement is the <code>decide()</code>
+		method, allowing you to contentrate only on the behaviour of your
+		filter.
 		</p>
 		
 		<p>
@@ -168,14 +175,14 @@
 		
 		<h3>Logback Filters</h3>
 		
-		<p>
-			As the moment, there are two filters that ship with logback.
-			<a href="../xref/ch/qos/logback/classic/LevelFilter.html">
-			<code>LevelFilter</code></a> provides event filtering based on a <code>Level</code> value. 
-			It the event's level is equal to the configured level, the filter accepts of denies
-			the event, depending on its configuration. It allows you to choose the
-			behaviour of logback for a precise given level. Here is a sample configuration that
-			uses <code>LevelFilter</code>.
+		<p>At the moment, there are two filters that ship with logback. <a
+		href="../xref/ch/qos/logback/classic/LevelFilter.html">
+		<code>LevelFilter</code></a> provides event filtering based on a
+		<code>Level</code> value.  It the event's level is equal to the
+		configured level, the filter accepts of denies the event,
+		depending on its configuration. It allows you to choose the
+		behaviour of logback for a precise given level. Here is a sample
+		configuration that uses <code>LevelFilter</code>.
 		</p>
 		
 <em>Example 6.3: Sample LevelFilter configuration (logback-examples/src/main/java/chapter6/LevelFilterConfig.xml)</em>				
@@ -227,131 +234,89 @@
   &lt;/root>
 &lt;/configuration></pre></div>
 
-		<h3>Evaluator Filters</h3>
-		    
-		<p>
-			A special category of filters ships with logback. The
-    	<a href="../xref/ch/qos/logback/core/filter/EvaluatorFilter.html">
-    	<code>EvaluatorFilter</code></a> objects use an 
-    	<a href="../xref/ch/qos/logback/core/boolex/EventEvaluator.html">
-    	<code>EventEvaluator</code></a>
-    	to decide wether to accept or deny the request. This allows unprecedented
-    	flexibility in the way that you can affect the logging event's filtering.
-    </p>
-    
-    <p>
-			Creating a customized filter that makes use of <code>EventEvaluator</code> objects
-			works the same way as seen previously, except that one must extend the 
-			<code>EvaluatorFilter</code> class, instead of the <code>Filter</code>
-			or <code>AbstractMatcherFilter</code> classes.
-		</p>
-    
-    <a name="EventEvaluator"></a>
-    <h3>Event Evaluators</h3>
-    
-    <p>
-    	Events evaluators allow the user to enter java expressions, using 
-    	components of a logging event, and to check each logging event
-    	against the compiled expression.
-    </p>
-    
-    <p>
-    	Let's see a sample configuration.
-    </p>
-    
-<em>Example 6.5: Basic event evaluator usage (logback-examples/src/main/java/chapter6/basicEventEvaluator.xml)</em>
-<div class="source"><pre>&lt;configuration>
 
-  &lt;appender name="STDOUT"
-    class="ch.qos.logback.core.ConsoleAppender">
-    <b>&lt;filter class="ch.qos.logback.core.filter.EvaluatorFilter">
-      &lt;evaluator name="myEval">
-        &lt;expression>message.contains("billing")&lt;/expression>
-      &lt;/evaluator>
-      &lt;OnMismatch>NEUTRAL&lt;/OnMismatch>
-      &lt;OnMatch>DENY&lt;/OnMatch>
-    &lt;/filter></b>
-    &lt;layout class="ch.qos.logback.classic.PatternLayout">
-      &lt;pattern>
-        %-4relative [%thread] %-5level %logger - %msg%n
-      &lt;/pattern>
-    &lt;/layout>
-  &lt;/appender>
+    <h3>Evaluator Filters taking Java Expressions</h3>
 
-  &lt;root>
-    &lt;level value="INFO" />
-    &lt;appender-ref ref="STDOUT" />
-  &lt;/root>
-&lt;/configuration></pre></div>
+		    
+    <p>A special category of filters is implemented by the <a
+    href="../xref/ch/qos/logback/core/filter/EvaluatorFilter.html">
+    <code>EvaluatorFilter</code></a> class. These filters use an <a
+    href="../xref/ch/qos/logback/core/boolex/EventEvaluator.html">
+    <code>EventEvaluator</code></a> object to decide wether to accept
+    or deny a request. This allows unprecedented flexibility in the
+    way that you can affect filtering of logging events.
+    </p>
 
-		<p>
-			The bold part in the previous configuration adds an <code>EvaluatorFilter</code>
-			to a <code>ConsoleAppender</code>. An <code>EventEvaluator</code> is then given to
-			the filter. The <em>expression</em> element contains a recognizable java expression.
-			Notice that the <em>message</em> variable is defined implicitly. Logback provides
-			access to the internal components of a logging event and lets the user build her
-			expression at will.
+    <p>As a user, you do not need to worry about the actual
+    plumbing. All you need to do is to give a name to the evaluator
+    and to specify an <em>evaluation expression</em>, that is a
+    boolean expression in regular Java syntax. These evaluation
+    expressions are compiled on-the-fly during the interpretation of
+    the configration file. It is the users reponsibility to ensure
+    that the expression is boolean, that it evaluates to true or
+    false.  In evaluation expressions, logback implicitly exposes
+    various fields of a logging event as variables. The list of these
+    implicit variables is given below. The scope of evaluation
+    expressions is limited to the logging event.
 		</p>
 		
-		<p>
-			The implicit variables available to the <code>EventEvaluator</code> are described below:
-		</p>
 		
-		<table>
-			<tr>
-				<th>Name</th>
-				<th>Type</th>
-				<th>Description</th>
+		<table class="bodyTable">
+      <tr>
+        <th>Name</th>
+        <th>Type</th>
+        <th>Description</th>
 			</tr>
-			<tr>
-				<td>event
-				</td>
+      <tr>
+				<td>event</td>
 				<td><code>LoggingEvent</code></td>
-				<td>The logging event associated with the logging request.
-				All of the following variables are also available from the event. For example, 
-				<code>event.getMessage()</code> returns the same String value as the <em>message</em>
-				variable.
-				</td>
+
+        <td>The raw logging event associated with the logging
+        request. All of the following variables are also available
+        from the event. For example, <code>event.getMessage()</code>
+        returns the same String value as the <em>message</em> variable
+        described next.
+        </td>
 			</tr>
-			<tr>
-				<td>message
-				</td>
-				<td><code>String</code></td>
-				<td>The message created with the logging request.
-				</td>
+
+      <tr class="alt">
+				<td>message</td>
+        <td><code>String</code></td>
+        <td>The message of the logging request.</td>
 			</tr>
 			<tr>
-				<td>logger
-				</td>
+				<td>logger</td>
 				<td><code>LoggerRemoteView</code></td>
-				<td>This object can be treated like a usual logger. In case the logging event
-				is serialized and sent to a remote machine, the usual logger object is
-				dropped and replaced by a <code>LoggerRemoteView</code> object, which
-				performs much better when serialized.
-				</td>
+				<td>This object is a proxy for the logger object where the
+				logging request was issued. It can be viewed as a regular
+				logger object. However, it has some nice performance
+				properties, especially with respect to serialization.
+        </td>
 			</tr>
-			<tr>
-				<td>level
-				</td>
+
+			<tr  class="alt">
+				<td>level</td>
 				<td><code>int</code></td>
-				<td>The int value corresponding to the level. To help create easily
-				expressions involving levels, the default value <em>DEBUG</em>, 
-				<em>INFO</em>, <em>WARN</em> and <em>ERROR</em> are also available. Thus,
-				using <em>level &gt; INFO</em> is a correct expression.
+				<td>The int value corresponding to the level. To help create
+				easily expressions involving levels, the default value
+				<em>DEBUG</em>, <em>INFO</em>, <em>WARN</em> and
+				<em>ERROR</em> are also available. Thus, using <em>level &gt;
+				INFO</em> is a correct expression.
 				</td>
 			</tr>
 			<tr>
 				<td>timeStamp
 				</td>
 				<td><code>long</code></td>
-				<td>The timestamp corresponding to the logging event's creation.
+				<td>The timestamp corresponding to the logging event's
+				creation.
 				</td>
 			</tr>
-			<tr>
-				<td>marker
-				</td>
+			<tr  class="alt">
+				<td>marker</td>
 				<td><code>Marker</code></td>
-				<td>The <code>Marker</code> object associated with the logging request.
+        <td>The <code>Marker</code> object associated with the logging
+        request.
 				</td>
 			</tr>
 			<tr>
@@ -363,43 +328,74 @@
 				following expression: <em>mdc.get("myKey")</em>.
 				</td>
 			</tr>
-			<tr>
-				<td>throwable
-				</td>
+			<tr  class="alt">
+				<td>throwable</td>
 				<td><code>Throwable</code></td>
-				<td>The exception that was passed to the logger when it
-				was requested.
+				<td>The exception associated with the logging event
 				</td>
 			</tr>
 		</table>
+
 		
-		<p>
-			The behaviour of the filter is also defined by its <span class="option">OnMatch</span>
-			and <span class="option">OnMismatch</span> options. The configuration specifies thanks
-			to these elements the replies that the <code>EvaluatorFilter</code> must give once its
-			expression has been evaluated. The example above returns the value <code>FilterReply.ACCEPT</code> 
-			when the message of the logging event contains the String <em>important</em>. 
-			If <em>important</em> is not contained in the message, then the filter lets the next filter 
-			evaluate this logging event.
-		</p>
-		
-		<p>
-			Let us see an example of <code>EvaluatorFilter</code>. The <code>FilterEvents</code>
-			class issues ten logging requests, numbered from 0 to 9.
-		</p>
-		
-		<p>
-			First, let us run the <code>FilterEvents</code> class with a configuration that does
-			not contain any filters. This can be done by issuing the following command:
+		<p>The behaviour of the <code>EvaluatorFilter</code> is also
+		affected by its <span class="option">OnMatch</span> and <span
+		class="option">OnMismatch</span> options taking values of type
+		<code>FilterReply</code>, i.e. DENY, ACCEPT, NEUTRAL.
+    </p>
+    
+    <p>Here is a concrete example.</p>
+
+<em>Example 6.5: Basic event evaluator usage (logback-examples/src/main/java/chapter6/basicEventEvaluator.xml)</em>
+
+<div class="source"><pre>&lt;configuration>
+
+  &lt;appender name="STDOUT"
+    class="ch.qos.logback.core.ConsoleAppender">
+    <b>&lt;filter class="ch.qos.logback.core.filter.EvaluatorFilter">
+      &lt;evaluator name="myEval">
+        &lt;expression><span class="green">message.contains("billing")</span>&lt;/expression>
+      &lt;/evaluator>
+      &lt;OnMismatch>NEUTRAL&lt;/OnMismatch>
+      &lt;OnMatch>DENY&lt;/OnMatch>
+    &lt;/filter></b>
+    &lt;layout class="ch.qos.logback.classic.PatternLayout">
+      &lt;pattern>
+        %-4relative [%thread] %-5level %logger - %msg%n
+      &lt;/pattern>
+    &lt;/layout>
+  &lt;/appender>
+
+  &lt;root>
+    &lt;level value="INFO" />
+    &lt;appender-ref ref="STDOUT" />
+  &lt;/root>
+&lt;/configuration></pre></div>
+
+		<p>The bold part in the previous configuration adds an
+		<code>EvaluatorFilter</code> to a <code>ConsoleAppender</code>. An
+		<code>EventEvaluator</code> is then injected into the
+		<code>EvaluatorFilter</code>. The <em>expression</em> element
+		corresponds to the evaluation expression described previously. The
+		expression <code>message.contains("billing")</code> returns a
+    boolean value. Notice that the <em>message</em> variable is
+		defined implicitly.
+    </p>
+
+		<p>This evalutor filter will drop all logging events whose message
+		contains the string "billing".
+    </p>
+
+    <p>The <a
+    href="../xref/chapter6/FilterEvents.html"><code>FilterEvents</code></a>
+    class issues ten logging requests, numbered from 0 to 9. Let us
+    rist run <code>FilterEvents</code> class without any filters:
 		</p>
 		
 <div class="source"><pre>
 java chapter6.FilterEvents src/main/java/chapter6/basicConfiguration.xml
 </pre></div>
 		
-		<p>
-			All requests will be displayed, as shown below:
-		</p>
+		<p>All requests will be displayed, as shown below:</p>
 
 <div class="source"><pre>0    [main] INFO  chapter6.FilterEvents - logging statement 0
 0    [main] INFO  chapter6.FilterEvents - logging statement 1
@@ -412,27 +408,15 @@
 0    [main] INFO  chapter6.FilterEvents - logging statement 8
 0    [main] INFO  chapter6.FilterEvents - logging statement 9</pre></div>
 
-		<p>
-		Suppose that we want to get rid of the billing information. We
-		can use an <code>EvaluatorFilter</code> configured as follows:
-		</p>
 
-<div class="source"><pre>&lt;configuration>
-  ...
-  &lt;filter class="ch.qos.logback.core.filter.EvaluatorFilter">
-    &lt;evaluator name="myEval">
-      &lt;expression>message.contains("billing")&lt;/expression>
-    &lt;/evaluator>
-    &lt;OnMismatch>NEUTRAL&lt;/OnMismatch>
-    &lt;OnMatch>DENY&lt;/OnMatch>
-  &lt;/filter>
-  ...
-&lt;/configuration></pre></div>
 
-		<p>
-			This filter will deny any logging event whose message
-			contains the String <em>billing</em>. If we run the <code>FilterEvents</code> 
-			class again, we obtain the following output:
+		<p>Suppose that we want to get rid of the billing information.
+		The <em>basicEventEvaluator.xml</em> configuration file just
+		desribed, does exactly what we want.</p>
+
+    <p>Running with filters:</p>
+    <p class="source">java chapter6.FilterEvents src/main/java/chapter6/basicEventEvaluator.xml</p>
+    <p>we obtain:
 		</p>
 		
 <div class="source"><pre>0    [main] INFO  chapter6.FilterEvents - logging statement 0
@@ -468,12 +452,12 @@
    		request is issued. Their scope is wider than appender-attached filters.
    	</p>
    	
-   	<p>
-   		More importantly, they are called before the <code>LoggingEvent</code> object creation. 
-   		Their decision is made based on some of the logging event's components. They require 
-   		no logging event instanciation, nor any other treatement to provide their 
-   		filtering functionnalities. They are much more performant than the usual
-   		<code>Filter</code> objects.
+   	<p>More importantly, they are called before the
+   	<code>LoggingEvent</code> object creation.  Their decision is made
+   	based on some of the logging event's components. They require no
+   	logging event instantiation, nor any other treatement to provide
+   	their filtering functionnalities. They are much more performant
+   	than the usual <code>Filter</code> objects.
    	</p>
    	
    	<h3>Implementing your own TurboFilter</h3>
@@ -663,33 +647,34 @@
 		</p>
 		
 		  
-    <h2>Logback Access</h2>
+    <h2>Logback-access</h2>
     
-    <p>
-    	Logback access benefits from most of the possibilities available
-    	to the classic module. <code>Filter</code> objects are available and work
-    	in the same way as their classic counterpart. They handle access' implementation
-    	of logging events: <code>AccessEvent</code>. 
-    	Thus, a customized filter
-    	for logback access is follows strictly the same rules than one for the 
-    	classic module, except for the event implemenation recieved as a parameter.
-    	On the other hand,
-    	<code>TurboFilter</code> objects are not available to the access module.
+    <p>Logback-access offers most of the features available with
+    logback-classic. <code>Filter</code> objects are available and
+    work in the same way as their logback-classic counterparts. They
+    handle access' implementation of logging events:
+    <code>AccessEvent</code>.  Thus, a customized filter for logback
+    access follows strictly the same rules as those for
+    logback-classic, except for the event type recieved as parameter.
+    On the other hand, <code>TurboFilter</code> objects are supported
+    by logback-access.
     </p>
     
     <h3>Filters</h3>
     
-    <p>
-    	<code>EvaluatorFilter</code> objects, with their expressions, are available to
-    	the access module. However, the variables that one can use to build an expression
-    	are different. Only the <code>AccessEvent</code> object can be used, by inserting the
-    	<em>event</em> variable in the expression. Although less wide than its classic
-    	counterpart, the access evaluation filter is just as powerfull. All the
-    	request and response components are reachable from the <em>event</em> variable.
+    <p><code>EvaluatorFilter</code> objects with java expressions
+    supplied in in <code>evaluator</code> configuration elements are
+    supported by logback-access. However, list implicit variables
+    available for constructing an expression are different. Only the
+    <code>AccessEvent</code> object can be used by inserting the
+    <em>event</em> variable in the expression. Nevertheless the access
+    <code>evaluator</code> is just as powerfull. All the request and
+    response components are reachable from the <em>event</em>
+    variable.
     </p>    
     
-    <p>
-    	Here is a sample configuration that will ensure that any 404 error will be displayed:
+    <p>Here is a sample configuration that will ensure that any 404
+    error will be logged:
     </p>
    	
 <em>Example 6.9: Access Evaluator (logback-examples/src/main/java/chapter6/accessEventEvaluator.xml)</em>
@@ -714,10 +699,9 @@
   &lt;appender-ref ref="STDOUT" />
 &lt;/configuration></pre></div>
 
-		<p>
-			We might imagine a slightly more complex use of filters to ensure the display of 404 errors, but
-			to prevent polluting the output with endless accesses to CSS files. Here is what such a configuration
-			would look like:
+		<p>We might imagine a slightly more complex use of filters to
+		ensure logging of 404 errors, except those returned on access to
+		CSS resources. Here is what such a configuration would look like:
 		</p>	
 
 <em>Example 6.10: Access Evaluator (logback-examples/src/main/java/chapter6/accessEventEvaluator2.xml)</em>

Modified: logback/trunk/logback-site/src/site/pages/manual/joran.html
==============================================================================
--- logback/trunk/logback-site/src/site/pages/manual/joran.html	(original)
+++ logback/trunk/logback-site/src/site/pages/manual/joran.html	Mon Aug 25 21:54:06 2008
@@ -460,7 +460,8 @@
   the root logger is already named, it does not admit a name attribute
   either. The value of the level attribute can be set to one of the
   case-insensitive strings TRACE, DEBUG, INFO, WARN, ERROR, ALL or
-  OFF. Note that the level of the root logger cannot be inherited.
+  OFF. Note that the level of the root logger cannot be set to
+  INHERITED or NULL.
   </p>
 
 
@@ -992,16 +993,15 @@
    <div class="source"><pre>USER_HOME=/home/sebastien</pre></div>
 
    <p>Nested variabled subsitution is also supported. By nested, we
-   mean that the value definition of a variable contains referenced to
-   other variables. Here is an example. Suppose you wish to use
-   variables to specify not only the destination directory but also
-   the file name, and combine those variable in a third variable
-   called "destination". The properties file shown below gives an
-   example.
+   mean that the value definition of a variable contains references to
+   other variables. Suppose you wish to use variables to specify not
+   only the destination directory but also the file name, and combine
+   those two variables in a third variable called "destination". The
+   properties file shown below gives an example.
    </p>
 
 
-   <em>Example 3.<span class="autoEx"/>: Recursive use of variables
+   <em>Example 3.<span class="autoEx"/>: Nested variable references
    (logback-examples/src/main/java/chapter3/variables2.properties)</em>
 
    <div class="source"><pre>USER_HOME=/home/sebastien

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	Mon Aug 25 21:54:06 2008
@@ -1414,12 +1414,16 @@
 
    	<a name="ClassicHTMLLayout"></a>
 
-		<h3>HTMLLayout</h3>
-		
-    <p><a href="../xref/ch/qos/logback/classic/html/HTMLLayout.html">
-    <code>HTMLLayout</code></a> outputs logging events in an HTML
-    table where each row of the table corresponds to a logging
-    event.</p>
+    <h2>Generating logs in HTML format</h2>
+	
+	  <p>Logback provides a special <a
+	  href="../xref/ch/qos/logback/core/Layout.html"><code>Layout</code></a>,
+	  namely <a
+	  href="../xref/ch/qos/logback/classic/html/HTMLLayout.html">
+	  <code>HTMLLayout</code></a>, to generate logs directly in HTML
+	  format. <code>HTMLLayout</code> outputs logging events in an HTML
+	  table where each row of the table corresponds to a logging
+	  event.</p>
 		
 		<p>Here is a sample output produced by <code>HTMLLayout</code>
 		using its default CSS stylesheet:</p>
@@ -1438,11 +1442,11 @@
 		<code>PatternLayout</code> with <code>HTMLLayout</code> is that
 		conversion specifiers should not be separated by space characters
 		or more generally by literal text. Each specifier found in the
-		pattern willa result in a separate column, in particular for each
-		literal text in the pattern, wasting valuable real estate on your
-		screen.
-    </p>
-
+		pattern will result in a separate column.  Likewise a separate
+		column will be generated for each block of literal text found in
+		the pattern potentially wasting valuable real estate on your
+		screen.</p>
+     
     <p>Here is simple but functional configuration file illustrating
     the use of <code>HTMLLayout</code>.
     </p>
@@ -1488,18 +1492,19 @@
 
     <h3>Stack traces</h3>
 
-		<p> If you use the <em>%em</em> conversion word, to display stack
-		traces, a table column will be created to display exception stack
-		traces. In most cases the column will be empty, wasting screen
+		<p> If you use the <em>%em</em> conversion word to display stack
+		traces, a table column will be created to display stack traces. In
+		most cases the column will be empty, wasting screen
 		real-estate. Moreover, printing a stack trace on a separate column
-		does yield very readable results. Fortunately, the <em>%ex</em>
-		conversion word is not the only way to display stack traces.
+		does not yield very readable results. Fortunately, the
+		<em>%ex</em> conversion word is not the only way to display stack
+		traces.
 		</p>
 
 		<p>A better solution is available through implementations of
 		<code>IThrowableRenderer</code> interface.  Such an implementation
-		can assigned to <code>HTMLLayout</code> to manage the display data
-		related to exceptions. By default, a
+		can be assigned to <code>HTMLLayout</code> to manage the display
+		data related to exceptions. By default, a
 		<a href="../xref/ch/qos/logback/classic/html/DefaultThrowableRenderer.html">
 			<code>DefaultThrowableRenderer</code></a> is assigned to each
 			<code>HTMLLayout</code> instance. It writes exceptions on a
@@ -1508,12 +1513,12 @@
 		</p>
 
 		<p>If for some reason, you still wish to use the <em>%ex</em>
-		pattern, then you can specify
-			<a href="../xref/ch/qos/logback/core/html/NOPThrowableRenderer.html">
-			<code>NOPThrowableRenderer</code></a> in the configuration file
-			in order to disable displaying a separate row for the stack
-			trace. We don't have the faintest idea why you would want to do
-			that, but if you did, you could.
+		pattern, then you can specify <a
+		href="../xref/ch/qos/logback/core/html/NOPThrowableRenderer.html">
+		<code>NOPThrowableRenderer</code></a> in the configuration file in
+		order to disable displaying a separate row for the stack trace. We
+		don't have the faintest idea why you would want to do that, but if
+		you wished, you could.
 		</p>
 
     <h3>CSS</h3>
@@ -1522,8 +1527,8 @@
     is controlled through a Cascading Style Sheet (CSS). In the
     absence of specific instructions, <code>HTMLLayout</code> will
     default to its internal CSS. However, your can instruct
-    <code>HTMLLayout</code> you use an external CSS file. For this
-    purpose, a <code>cssBuilder</code> element can be nested within a
+    <code>HTMLLayout</code> to use an external CSS file. For this
+    purpose a <code>cssBuilder</code> element can be nested within a
     <code>&lt;layout&gt;</code> element, as shown below.
 		</p>
 
@@ -1600,268 +1605,249 @@
 		<a name="AccessPatternLayout"></a>
 
 		<h3>PatternLayout</h3>
-		<p> <a href="../xref/ch/qos/logback/access/PatternLayout.html">
+
+		<p><a href="../xref/ch/qos/logback/access/PatternLayout.html">
 		<code>PatternLayout</code></a> in logback-access can be configured
-		in the same way as it's classic counterpart, with the notable
-		exception of the available conversion specifiers, as appropriate
-		for HTTP servlet request and response.
-		</p>
+		much in the same way as its classic counterpart. However it
+		features additional conversion specifiers suited for logging
+		particular bits of information availalbe only in HTTP servlet
+		requests and HTTP servlet responses.
+    </p>
 
 		<p>Below is a list of conversion specifiers for 
 		<code>PatternLayout</code> in logback-access.</p>
 		
 		<table  class="bodyTable" border="0" CELLPADDING="8">
-			<th align="center">Conversion Word</th>
-			<th align="center">Effect</th>
-
-		<tr class="a">
-			<td align="center"><b>a / remoteIP</b></td>
-			<td>
-				<p>
-					Remote IP address.
-				</p>
-			</td>
-		</tr>
-		<tr class="b">
-			<td align="center"><b>A / localIP</b></td>
-			<td>
-				<p>
-					Local IP address.
-				</p>
-			</td>
-		</tr>		
-		<tr class="a">
-			<td align="center"><b>b / B / byteSent</b></td>
-			<td>
-				<p>
-					Response's content length.
-				</p>
-			</td>
-		</tr>				
-		<tr class="b">
-			<td align="center"><b>h / clientHost</b></td>
-			<td>
-				<p>
-					Remote host.
-				</p>
-			</td>
-		</tr>
-		<tr class="a">
-			<td align="center"><b>H / protocol</b></td>
-			<td>
-				<p>
-					Request protocol.
-				</p>
-			</td>
-		</tr>
-    <tr class="b">
-      <td align="center"><b>l</b></td>
-			<td>
-				<p>
-					Remote log name. In logback-access, this converter always
-					returns the value "-".
-				</p>
-			</td>
-		</tr>
-
-		<tr class="a">
-			<td align="center"><b>reqParameter{paramName}</b></td>
-			<td>
-				<p>
-					Parameter of the response.
-				</p>
-				<p>This conversion word takes the first option in braces and looks
-				for the corresponding parameter in the request.</p>
-				<p><b>%reqParameter{input_data}</b> 
-				displays the corresponding parameter.</p>
-			</td>
-		</tr>		
-		<tr class="b">
-			<td align="center"><b>i{header} / header{header}</b></td>
-			<td>
-				<p>
-					Request header.
-				</p>
-				<p>This conversion word takes the first option in braces and looks
-				for the corresponding header in the request.</p>
-				<p><b>%header{Referer}</b> displays the referer of the request.</p>
-        <p>
-        If no option is specified, it displays every available header.
-        </p>
-			</td>
-		</tr>	
-		<tr class="a">
-			<td align="center"><b>m / requestMethod</b></td>
-			<td>
-				<p>
-					Request method.
-				</p>
-			</td>
-		</tr>		
-		<tr class="b">
-			<td align="center"><b>r / requestURL</b></td>
-			<td>
-				<p>
-					URL requested.
-				</p>
-			</td>
-		</tr>
-		<tr class="a">
-			<td align="center"><b>s / statusCode</b></td>
-			<td>
-				<p>
-					Status code of the request.
-				</p>
-			</td>
-		</tr>		
-		<tr class="b">
-			<td align="center"><b>t / date</b></td>
-			<td>
-					<p>
-						Used to output the date of the logging event.
-						The date conversion specifier may be followed by
-						a set of braces containing a date and time
-						pattern strings used by
-						<code>java.text.SimpleDateFormat</code>
-						.
-						<em>ABSOLUTE</em>
-						,
-						<em>DATE</em>
-						or
-						<em>ISO8601</em>
-						can also be used.
+      <tr>
+        <th align="center">Conversion Word</th>
+        <th align="center">Effect</th>
+      </tr>
+      <tr class="a">
+        <td align="center"><b>a / remoteIP</b></td>
+        <td>
+          <p>
+            Remote IP address.
+          </p>
+        </td>
+      </tr>
+      <tr class="b">
+        <td align="center"><b>A / localIP</b></td>
+        <td>
+          <p>
+            Local IP address.
+          </p>
+        </td>
+      </tr>		
+      <tr class="a">
+        <td align="center"><b>b / B / byteSent</b></td>
+        <td>
+          <p>
+            Response's content length.
+          </p>
+        </td>
+      </tr>				
+      <tr class="b">
+        <td align="center"><b>h / clientHost</b></td>
+        <td>
+          <p>
+            Remote host.
+          </p>
+        </td>
+      </tr>
+      <tr class="a">
+        <td align="center"><b>H / protocol</b></td>
+        <td>
+          <p>
+            Request protocol.
+          </p>
+        </td>
+      </tr>
+      <tr class="b">
+        <td align="center"><b>l</b></td>
+        <td>
+          <p>
+            Remote log name. In logback-access, this converter always
+            returns the value "-".
+          </p>
+        </td>
+      </tr>
+      
+      <tr class="a">
+        <td align="center"><b>reqParameter{paramName}</b></td>
+        <td>
+          <p>
+            Parameter of the response.
+          </p>
+          <p>This conversion word takes the first option in braces and looks
+          for the corresponding parameter in the request.</p>
+          <p><b>%reqParameter{input_data}</b> 
+          displays the corresponding parameter.</p>
+        </td>
+      </tr>		
+      <tr class="b">
+        <td align="center"><b>i{header} / header{header}</b></td>
+        <td>
+          <p>
+            Request header.
+          </p>
+          <p>This conversion word takes the first option in braces and looks
+          for the corresponding header in the request.</p>
+          <p><b>%header{Referer}</b> displays the referer of the request.</p>
+          <p>
+            If no option is specified, it displays every available header.
+          </p>
+        </td>
+      </tr>	
+      <tr class="a">
+        <td align="center"><b>m / requestMethod</b></td>
+        <td>
+          <p>
+            Request method.
+          </p>
+        </td>
+      </tr>		
+      <tr class="b">
+        <td align="center"><b>r / requestURL</b></td>
+        <td>
+          <p>
+            URL requested.
+          </p>
+        </td>
+      </tr>
+      <tr class="a">
+        <td align="center"><b>s / statusCode</b></td>
+        <td>
+          <p>
+            Status code of the request.
+          </p>
+        </td>
+      </tr>		
+      <tr class="b">
+        <td align="center"><b>t / date</b></td>
+        <td>
+          <p>Used to output the date of the logging event.  The date
+          conversion specifier may be followed by a set of braces
+          containing a date and time pattern strings used by
+          <code>java.text.SimpleDateFormat</code>.  <em>ABSOLUTE</em>,
+          <em>DATE</em> or <em>ISO8601</em> are also valid values.
 					</p>
-					<p>
-						For example,
-						<b>%d{HH:mm:ss,SSS}</b>
-						,
-						<b>
-							%d{dd&#160;MMM&#160;yyyy&#160;;HH:mm:ss,SSS}
-						</b>
-						or
-						<b>%d{DATE}</b>
-						. If no date format specifier is given then
-						ISO8601 format is assumed.
+					<p>For example, <b>%d{HH:mm:ss,SSS}</b>,
+					<b>%d{dd&#160;MMM&#160;yyyy&#160;;HH:mm:ss,SSS}</b> or
+					<b>%d{DATE}</b>.  If no date format specifier is given then
+					ISO8601 format is assumed.
 					</p>
-			</td>
-		</tr>
-		<tr class="a">
-			<td align="center"><b>u / user</b></td>
-			<td>
-				<p>
-					Remote user.
-				</p>
-			</td>
-		</tr>		
-		<tr class="b">
-			<td align="center"><b>U / requestURI</b></td>
-			<td>
-				<p>
-					Requested URI.
-				</p>
-			</td>
-		</tr>		
-		<tr class="a">
-			<td align="center"><b>v / server</b></td>
-			<td>
-				<p>
-					Server name.
-				</p>
-			</td>
-		</tr>
-		<tr class="b">
-			<td align="center"><b>localPort</b></td>
-			<td>
-				<p>
-					Local port.
-				</p>
-			</td>
-		</tr>
-		<tr class="a">
-			<td align="center"><b>reqAttribute{attributeName}</b></td>
-			<td>
-				<p>
-					Attribute of the request.
-				</p>
-				<p>This conversion word takes the first option in braces and looks
-				for the corresponding attribute in the request.</p>
-				<p><b>%reqAttribute{SOME_ATTRIBUTE}</b> 
-				displays the corresponding attribute.</p>
-			</td>
-		</tr>
-		<tr class="b">
-			<td align="center"><b>reqCookie{cookie}</b></td>
-			<td>
-				<p>
-					Request cookie.
-				</p>
-				<p>This conversion word takes the first option in braces and looks
-				for the corresponding cookie in the request.</p>
-				<p><b>%cookie{COOKIE_NAME}</b> displays corresponding cookie.</p>
-			</td>
-		</tr>
-		<tr class="a">
-			<td align="center"><b>responseHeader{header}</b></td>
-			<td>
-				<p>
-					Header of the response.
-				</p>
-				<p>This conversion word takes the first option in braces and looks
-				for the corresponding header in the response.</p>
-				<p><b>%header{Referer}</b> displays the referer of the response.</p>
-			</td>
-		</tr>
-    <tr class="b">
-      <td align="center"><b>requestContent</b></td>
-      <td>
-        <p>
-          This conversion word displays the content of the request, that is the
-          request's <code>InputStream</code>. It is used in conjunction with a
-          <a href="../xref/ch/qos/logback/access/servlet/TeeFilter.html">
-          <code>TeeFilter</code></a>, a <code>javax.servlet.Filter</code> that 
-          replaces the original <code>HttpServletRequest</code> 
-          by a <a href="../xref/ch/qos/logback/access/servlet/TeeHttpServletRequest.html">
-          <code>TeeHttpServletRequest</code></a>. The latter object allows
-          access to the requet's <code>InputStream</code> multiple times without
-          any loss of data.
-        </p>
-      </td>
-    </tr>
-    <tr class="a">
-      <td align="center"><b>fullRequest</b></td>
-      <td>
-        <p>This converter outputs the data associated with the
+        </td>
+      </tr>
+      <tr class="a">
+        <td align="center"><b>u / user</b></td>
+        <td>
+          <p>
+            Remote user.
+          </p>
+        </td>
+      </tr>		
+      <tr class="b">
+        <td align="center"><b>U / requestURI</b></td>
+        <td>
+          <p>
+            Requested URI.
+          </p>
+        </td>
+      </tr>		
+      <tr class="a">
+        <td align="center"><b>v / server</b></td>
+        <td>
+          <p>Server name.</p>
+        </td>
+      </tr>
+      <tr class="b">
+        <td align="center"><b>localPort</b></td>
+        <td>
+          <p>Local port.</p>
+        </td>
+      </tr>
+      <tr class="a">
+        <td align="center"><b>reqAttribute{attributeName}</b></td>
+        <td>
+          <p>Attribute of the request.</p>
+          <p>This conversion word takes the first option in braces and looks
+          for the corresponding attribute in the request.</p>
+          <p><b>%reqAttribute{SOME_ATTRIBUTE}</b> 
+          displays the corresponding attribute.</p>
+        </td>
+      </tr>
+      <tr class="b">
+        <td align="center"><b>reqCookie{cookie}</b></td>
+        <td>
+          <p>Request cookie.</p>
+          <p>This conversion word takes the first option in braces and looks
+          for the corresponding cookie in the request.</p>
+          <p><b>%cookie{COOKIE_NAME}</b> displays corresponding cookie.</p>
+        </td>
+      </tr>
+      <tr class="a">
+        <td align="center"><b>responseHeader{header}</b></td>
+        <td>
+          <p>
+            Header of the response.
+          </p>
+          <p>This conversion word takes the first option in braces and looks
+          for the corresponding header in the response.</p>
+          <p><b>%header{Referer}</b> displays the referer of the response.</p>
+        </td>
+      </tr>
+      <tr class="b">
+        <td align="center"><b>requestContent</b></td>
+        <td>
+          <p>This conversion word displays the content of the request,
+          that is the request's <code>InputStream</code>. It is used
+          in conjunction with a <a
+          href="../xref/ch/qos/logback/access/servlet/TeeFilter.html">
+          <code>TeeFilter</code></a>, a
+          <code>javax.servlet.Filter</code> that replaces the original
+          <code>HttpServletRequest</code> by a <a
+          href="../xref/ch/qos/logback/access/servlet/TeeHttpServletRequest.html">
+          <code>TeeHttpServletRequest</code></a>. The latter object
+          allows access to the requet's <code>InputStream</code>
+          multiple times without any loss of data.
+          </p>
+        </td>
+      </tr>
+      <tr class="a">
+        <td align="center"><b>fullRequest</b></td>
+        <td>
+          <p>This converter outputs the data associated with the
           request, including all headers and request contents.
-        </p>
-      </td>
-    </tr>
-    <tr class="b">
-      <td align="center"><b>responseContent</b></td>
-      <td>
-        <p>
-          This conversion word displays the content of the response, that is the
-          response's <code>InputStream</code>. It is used in conjunction with a
+          </p>
+        </td>
+      </tr>
+      <tr class="b">
+        <td align="center"><b>responseContent</b></td>
+        <td>
+          <p>This conversion word displays the content of the
+          response, that is the response's
+          <code>InputStream</code>. It is used in conjunction with a
           <a href="../xref/ch/qos/logback/access/servlet/TeeFilter.html">
-          <code>TeeFilter</code></a>, a <code>javax.servlet.Filter</code> that 
-          replaces the original <code>HttpServletResponse</code> 
-          by a <a href="../xref/ch/qos/logback/access/servlet/TeeHttpServletResponse.html">
-          <code>TeeHttpServletResponse</code></a>. The latter object allows
-          access to the requet's <code>InputStream</code> multiple times without
-          any loss of data.
-        </p>
-      </td>
-    </tr>
-    <tr class="a">
-      <td align="center"><b>fullResponse</b></td>
-      <td>
-        <p>
-          This conversion word takes all the available data
+          <code>TeeFilter</code></a>, a
+          <code>javax.servlet.Filter</code> that replaces the original
+          <code>HttpServletResponse</code> by a <a
+          href="../xref/ch/qos/logback/access/servlet/TeeHttpServletResponse.html">
+          <code>TeeHttpServletResponse</code></a>. The latter object
+          allows access to the requet's <code>InputStream</code>
+          multiple times without any loss of data.
+          </p>
+        </td>
+      </tr>
+      <tr class="a">
+        <td align="center"><b>fullResponse</b></td>
+        <td>
+          <p>This conversion word takes all the available data
           associatede with the response, inclusing all headers of the
           response and response contents.
-        </p>
-      </td>
-    </tr>
-		</table>
+          </p>
+        </td>
+      </tr>
+    </table>
 		
 		<p>Logback access' <code>PatternLayout</code> also recognize three keywords, which
 		act like shortcuts to a certain pattern.</p>
@@ -1887,10 +1873,10 @@
 	 	which displays client host, remote log name, user, date, requested URL, status code 
 	 	and response's content length</p>
 	 	
-	 	<p>The <em>combined</em> keyword is a shortcut to 
-	 	<em>%h %l %u %t \"%r\" %s %b \"%i{Referer}\" \"%i{User-Agent}\"</em>. This pattern begins
-	 	much like the <em>common</em> pattern but also displays two request headers, namely
-	 	 referer, and user-agent.</p>
+	 	<p>The <em>combined</em> keyword is a shortcut for <em>%h %l %u %t
+	 	\"%r\" %s %b \"%i{Referer}\" \"%i{User-Agent}\"</em>. This pattern
+	 	begins much like the <em>common</em> pattern but also displays two
+	 	request headers, namely referer, and user-agent.</p>
 
 		<a name="AccessHTMLLayout"></a>
 		<h3>HTMLLayout</h3>
@@ -1898,37 +1884,49 @@
 		<p>The <a
 		href="../xref/ch/qos/logback/access/html/HTMLLayout.html"><code>HTMLLayout</code></a>
 		class found in logback-access is similar to the <a
-		href="#ClassicHTMLLayout"><code>HTMLLayout</code></a> class found
-		in logback-classic.
+		href="#ClassicHTMLLayout"><code>HTMLLayout</code></a> class from
+		logback-classic.
     </p>
 		
 		<p>By default, it will create a table containing the following data:</p>
 		
 		<ul>
-			<p>Remote IP</p>
-			<p>Date</p>
-			<p>Request URL</p>
-			<p>Status code</p>
-			<p>Content Length</p>
+			<li>Remote IP</li>
+			<li>Date</li>
+			<li>Request URL</li>
+			<li>Status code</li>
+			<li>Content Length</li>
 		</ul>
 		
-		<p>Here is a sample output produced by <code>HTMLLayout</code> in logback-access:</p>
+		<p>Here is a sample output produced by <code>HTMLLayout</code> in
+		logback-access:</p>
 		<img src="images/htmlLayoutAccess.gif" alt="Access HTML Layout Sample Image"/>
 
-		<p>What is better than a real world example? Our own log4j
+		<p>What can be better than a real world example? Our own log4j
 		properties to logback <a
 		href="http://logback.qos.ch/translator/">translator</a> makes use
 		of logback-access to showcase a live ouput, using a
 		<code>RollingFileAppender</code> and <code>HTMLLayout</code>.</p>
 		
-		<p>You can see the file by <a
-		href="http://logback.qos.ch/translator/logs/access.html">following
-		this link</a>.</p>
-
-		<p>Just like any access log, each visit the <a
-		href="http://logback.qos.ch/translator/">translator</a>
-		web-application will add a new entry to the access logs.
-    </p>
+		<p>What can be better than a real world example? Our own log4j
+		properties for logback <a
+		href="http://logback.qos.ch/translator/">translator</a> makes use
+		of logback-access to demonstrate live ouput from
+		<code>RollingFileAppender</code> with <code>HTMLLayout</code>.</p>
+
+
+    <p>On every new user request to our <a
+    href="http://logback.qos.ch/translator/">translator</a>
+    web-application, a new entry will be added to the access logs,
+    which you can view by <a
+    href="http://logback.qos.ch/translator/logs/access.html">following
+    this link</a>.</p>
+
+
+    
+
+
+ 
 
 <script src="../templates/footer.js"></script>
 </div>

Modified: logback/trunk/logback-site/src/site/pages/manual/mdc.html
==============================================================================
--- logback/trunk/logback-site/src/site/pages/manual/mdc.html	(original)
+++ logback/trunk/logback-site/src/site/pages/manual/mdc.html	Mon Aug 25 21:54:06 2008
@@ -50,12 +50,11 @@
    	the SLF4J API: Mapped Diagnostic Contexts (MDC).
 		</p>
 		
-		<p>
-			To uniquely stamp each request, the user puts contextual
-			information into the <code><a
-			href="http://www.slf4j.org/api/org/slf4j/MDC.html">MDC</a></code>,
-			the abbreviation of Mapped Diagnostic Context.  The public
-			interface of the MDC class is shown below.
+		<p>To uniquely stamp each request, the user puts contextual
+		information into the <code><a
+		href="http://www.slf4j.org/api/org/slf4j/MDC.html">MDC</a></code>,
+		the abbreviation of Mapped Diagnostic Context.  The salient parts
+		of the MDC class is shown below.
 		</p>
 
 <div class="source"><pre>package org.slf4j;
@@ -73,9 +72,6 @@
 
   //Clear all entries in the MDC.
   <b>public static void clear();</b>
-
-  //Returns the keys in the MDC as a Set. The returned value can be null.
-  <b>public static Set&lt;String> getKeys();</b>
 }</pre></div>
 
 		<p>The <code>MDC</code> class contains only static methods.  It
@@ -615,6 +611,28 @@
   are unaffected. Furthermore, any given thread will contain correct
   MDC data any point in time.</p>
 		
+
+
+  <h3>MDC And Managed Threads</h3>
+
+  <p>A copy of mapped diagnostic context can not always be inherited
+  by worker thread from the initiating thread. This is the case when
+  <code>java.util.concurrent.Executors</code> is used for thread
+  management. For instance, <code>newCachedThreadPool</code> method
+  creates a <code>ThreadPoolExecutor</code> and like other thread
+  pooling code it has intricate thread creation logic.
+  </p>
+
+  <p>In such cases, it is recommended that
+  <code>MDC.getCopyOfContextMap()</code> is invoked on the original
+  (master) thread before submitting a task to the executor.  When the
+  task runs, as its first action, it should invoke
+  <code>MDC.setContextMapValues()</code> to associate the stored copy
+  of the orinal MDC values with the new <code>Executor</code> managed
+  thread.
+  </p>
+
+
 <script src="../templates/footer.js"></script>
 </div>
 </body>


More information about the logback-dev mailing list