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>
_______________________________________________
logback-dev mailing list
[email protected]
http://qos.ch/mailman/listinfo/logback-dev
