[logback-dev] svn commit: r1648 - logback/trunk/logback-site/src/site/pages/manual

[noreply.ceki at qos.ch]

Author: ceki
Date: Wed Mar 19 16:03:53 2008
New Revision: 1648

Modified:
   logback/trunk/logback-site/src/site/pages/manual/layouts.html

Log:
- added blurb on parentheses in layout patterns 

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 Mar 19 16:03:53 2008
@@ -1000,14 +1000,52 @@
 
 		<h3>Parentheses are special</h3>
 
-    <p>In logback, parentheses withing the pattern string are treated
+    <p>In logback, parentheses within the pattern string are treated
     as grouping tokens. Thus, it is possible to group a sub-pattern
     and apply formatting directives to that sub-pattern.
     </p>
 
-    <p>For example, 
+    <p>For example, the pattern</p> 
 
-    <span class="red"><b>XXXXXXXXXXXXXXXXXX</b></span>
+    <p class="source"><b>%-30(</b>%d{HH:mm:ss.SSS} [%thread]<b>)</b> %-5level %logger{32} - %msg%n</p> 
+
+    <p>will group the output generated by the sub-pattern
+    "%d{HH:mm:ss.SSS} [%thread]" so that it is right-padded if less
+    than 30 characters.
+    </p>
+
+    <p>If without the grouping the output was</p>
+
+    <p class="source">13:09:30 [main] DEBUG c.q.logback.demo.ContextListener - Classload hashcode is 13995234
+13:09:30 [main] DEBUG c.q.logback.demo.ContextListener - Initializing for ServletContext
+13:09:30 [main] DEBUG c.q.logback.demo.ContextListener - Trying platform Mbean server
+13:09:30 [pool-1-thread-1] INFO  ch.qos.logback.demo.LoggingTask - Howdydy-diddly-ho - 0
+13:09:38 [btpool0-7] INFO c.q.l.demo.lottery.LotteryAction - Number: 50 was tried.
+13:09:40 [btpool0-7] INFO c.q.l.d.prime.NumberCruncherImpl - Beginning to factor.
+13:09:40 [btpool0-7] DEBUG c.q.l.d.prime.NumberCruncherImpl - Trying 2 as a factor.
+13:09:40 [btpool0-7] INFO c.q.l.d.prime.NumberCruncherImpl - Found factor 2
+    </p>
+
+    <p>with the "%-30()" grouping applied it would be</p>
+
+    <p class="source">13:09:30 [main]            DEBUG c.q.logback.demo.ContextListener - Classload hashcode is 13995234
+13:09:30 [main]            DEBUG c.q.logback.demo.ContextListener - Initializing for ServletContext
+13:09:30 [main]            DEBUG c.q.logback.demo.ContextListener - Trying platform Mbean server
+13:09:30 [pool-1-thread-1] INFO  ch.qos.logback.demo.LoggingTask - Howdydy-diddly-ho - 0
+13:09:38 [btpool0-7]       INFO  c.q.l.demo.lottery.LotteryAction - Number: 50 was tried.
+13:09:40 [btpool0-7]       INFO  c.q.l.d.prime.NumberCruncherImpl - Beginning to factor.
+13:09:40 [btpool0-7]       DEBUG c.q.l.d.prime.NumberCruncherImpl - Trying 2 as a factor.
+13:09:40 [btpool0-7]       INFO  c.q.l.d.prime.NumberCruncherImpl - Found factor 2
+    </p>
+
+    
+    <p>The latter form is more comfortable to read, especially for
+    long log files.</p>
+    
+    <p>If you need to treat the parenthesis character as a literal, it
+    needs to be escaped by preceding the parentheses with a
+    backslash. As in, <b>\(</b>%d{HH:mm:ss.SSS} [%thread]<b>\)</b>.
+    </p>