[Log4cocoa-cvs] log4cocoa readme.txt,1.5,1.6

[<chi...@us...>]

Update of /cvsroot/log4cocoa/log4cocoa
In directory usw-pr-cvs1:/tmp/cvs-serv22390

Modified Files:
	readme.txt 
Log Message:
added warning about commas in macros

Index: readme.txt
===================================================================
RCS file: /cvsroot/log4cocoa/log4cocoa/readme.txt,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- readme.txt	18 Oct 2002 05:23:24 -0000	1.5
+++ readme.txt	4 Nov 2002 04:47:33 -0000	1.6
@@ -2,21 +2,38 @@
    
 To make Log4Cocoa easier, there are several high level macros, as follows:
 
-L4Debug(message);
-L4Info(message);
-L4Warn(message);
-L4Error(message);
-L4Fatal(message);
+L4Debug((message));
+L4Info((message));
+L4Warn((message));
+L4Error((message));
+L4Fatal((message));
 
-L4DebugWithException(message, e);
-L4InfoWithException(message, e);
-L4WarnWithException(message, e);
-L4ErrorWithException(message, e);
-L4FatalWithException(message, e);
+L4DebugWithException((message, e));
+L4InfoWithException((message, e));
+L4WarnWithException((message, e));
+L4ErrorWithException((message, e));
+L4FatalWithException((message, e));
 
-L4Assert(assertion, message);
+L4Assert((assertion, message));
 
-Both versions of the Debug & Info macros expand into methods that are wrapped by an "isEnabled" if statement, like so:
+**VERY IMPORTANT NOTE**: The second set of parenthesis are optional, however read the following note.  Since these are macros, if you have a comma "," in your log statement, the gcc processor will assume that you have 2 arguments, even if you only have one. 
+
+This statement: 
+    L4Info([NSString stringWithFormat: @"Duration: %f", [end timeIntervalSinceDate: start]]);
+will result in this error: 
+    MyClass.m:44: too many args (2) to macro 'L4Info' (1 expected)
+
+Solution 1a:  If you have commas in your log message line *ANYWHERE*, you can remove this issue by wraping your log message with an extra set of parenthesis as documented above, like so:
+
+    L4Info(([NSString stringWithFormat: @"Duration: %f", [end timeIntervalSinceDate: start]]));
+
+Solution 1b:  Or, you can re-write your log statement so that it does not include commas, like so:
+    
+    L4Info([@"Duration: " stringByAppendingString: [[NSNumber numberWithDouble: [end timeIntervalSinceDate: start]] stringValue]]);
+    
+Obviously the second way can be coded in numeruous ways, but I just wanted to point out the two approaches.  Clearly the second way is more cumbersome and not as straight forward, therefore if you use the first approach, it is important to remember to use 2 sets of parenthesis.
+
+Also, both versions of the Debug & Info macros expand into methods that are wrapped by an "isEnabled" if statement, like so:
 
 if([[self logger] isInfoEnabled]) [[self logger] lineNumber: __LINE__ 
                                                    fileName: __FILE__