[logback-dev] svn commit: r1372 - in logback/trunk/logback-site/src/site/pages: css manual

noreply.ceki at qos.ch noreply.ceki at qos.ch
Wed Feb 28 22:30:52 CET 2007


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&#252;lc&#252;, 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&#252;lc&#252;, 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>&lt;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&lt;LoggingEvent&gt;</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>&lt;configuration>
 
   &lt;appender name="STDOUT"
     class="ch.qos.logback.core.ConsoleAppender">
     &lt;layout class="chapter5.MySampleLayout2"> 
-    	<b>&lt;prefix>MyPrefix&lt;/prefix>
-    	&lt;printThreadName>false&lt;/printThreadName></b>
+      <b>&lt;prefix&gt;MyPrefix&lt;/prefix&gt;</b>
+      <b>&lt;printThreadName&gt;false&lt;/printThreadName&gt;</b>
     &lt;/layout>
   &lt;/appender>
 
@@ -290,9 +309,7 @@
 &lt;/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>
 
 



More information about the logback-dev mailing list