[Log4cocoa-cvs] log4cocoa readme.txt,1.7,1.8

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

Update of /cvsroot/log4cocoa/log4cocoa
In directory sc8-pr-cvs1:/tmp/cvs-serv2459

Modified Files:
	readme.txt 
Log Message:
updated readme to reflect new macro names *** NOTE *** tweaked macro names, left old macros in place in L4Logger.h so that there won't be any compatibility problems for now.

Index: readme.txt
===================================================================
RCS file: /cvsroot/log4cocoa/log4cocoa/readme.txt,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -d -r1.7 -r1.8
--- readme.txt	7 May 2003 07:16:40 -0000	1.7
+++ readme.txt	15 Jun 2003 03:20:11 -0000	1.8
@@ -1,39 +1,44 @@
-Log4Cocoa Usage (May 7, 2003) --- draft 0.0.a.2
+Log4Cocoa Usage (May 7, 2003) --- draft 0.0.a.3
    
 To make Log4Cocoa easier, there are several high level macros, as follows:
 
-L4Debug((message));
-L4Info((message));
-L4Warn((message));
-L4Error((message));
-L4Fatal((message));
+log4Debug((message));
+log4Info((message));
+log4Warn((message));
+log4Error((message));
+log4Fatal((message));
 
-L4DebugWithException((message, e));
-L4InfoWithException((message, e));
-L4WarnWithException((message, e));
-L4ErrorWithException((message, e));
-L4FatalWithException((message, e));
+log4DebugWithException((message), e);
+log4InfoWithException((message), e);
+log4WarnWithException((message), e);
+log4ErrorWithException((message), e);
+log4FatalWithException((message), e);
 
-L4Assert((assertion, message));
+log4Assert(assertion, (message));
 
-**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. 
+
+**VERY IMPORTANT NOTE**: The second set of parenthesis around the log message are technically optional, however read the following note.  
+
+Since these are macros, if you have a comma "," in your log message, the gcc processor will assume that you have 2 arguments, even if you only have one.  Therefore, if you have a comma anywhere in your log message, you must wrap it in an extra set of parens or rewrite it without commas.
 
 This statement: 
-    L4Info([NSString stringWithFormat: @"Duration: %f", [end timeIntervalSinceDate: start]]);
+
+    log4Info([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:
+    MyClass.m:44: too many args (2) to macro 'log4Info' (1 expected)
 
-    L4Info(([NSString stringWithFormat: @"Duration: %f", [end timeIntervalSinceDate: start]]));
+Solution 1 - Wrapping:
 
-Solution 1b:  Or, you can re-write your log statement so that it does not include commas, like so:
+    log4Info(([NSString stringWithFormat: @"Duration: %f", [end timeIntervalSinceDate: start]]));
+
+Solution 2 - Rewriting:
     
-    L4Info([@"Duration: " stringByAppendingString: [[NSNumber numberWithDouble: [end timeIntervalSinceDate: start]] stringValue]]);
+    log4Info([@"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:
+Obviously the second way can be coded in numeruous ways, but I just wanted to point out the two approaches.  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__ 
@@ -41,9 +46,7 @@
                                                        info: message 
                                                   exception: e]
 
-All of the other levels expand out to their counterparts, but are not enclosed by the "isEnabled" if statement.  Also, FYI, __LINE__, __FILE__, and __PRETTY_FUNCTION__  are macros GCC built in as predefined macros to generate the appropriate information.
-
-L4Assert() takes an BOOL as an assertion expression that must evaluate to YES, or else it logs the message as an error.
+All of the other levels expand out to their counterparts, but are not enclosed by the "isEnabled" if statement.  Also, FYI, __LINE__, __FILE__, and __PRETTY_FUNCTION__  are macros GCC built in as predefined macros to generate the appropriate information.  log4Assert() takes an BOOL as an assertion expression that must evaluate to YES, or else it logs the message as an error.
 
 NOTE: none of these macro's do not include a final semi-colon, so make sure to use one when invoking them.
 
@@ -67,6 +70,30 @@
 Since, +logger; & -logger; are implmented as categories on NSObject, you can override them if you don't want the default logger for your class or you want cache the logger.
 
 
+II. Embedding Log4Cocoa
+
+To actually embed Log4Cocoa in your application, you'll need to add a copy phase to your build target.  Your application will run as long as Log4Cocoa is installed in your Framework search path but embedding it will make deployment much easier and gdb gets messed up when you use an embedded framework but don't actually embed it.
+
+From Apple's Documentation: 
+
+http://developer.apple.com/techpubs/macosx/DeveloperTools/ProjectBuilder/ProjectBuilder.help/Contents/Resources/English.lproj/Frameworks/chapter_19_section_3.html
+
+Copy the Framework Into the Application
+
+In the applicationÕs target, you need to add a copy-files build phase that copies the framework into the application.
+
+
+1) Add the framework to the applicationÕs target. See ÒAdding Files and FrameworksÓ. If the applicationÕs target and frameworkÕs target are in the same project, you should also make the applicationÕs target dependent on the frameworkÕs target. See ÒManaging Target DependenciesÓ.
+
+2) In the project window, click the Targets tab and open the application target.
+
+3) Click the last build phase under Build Phases, and choose Project > New Build Phase > New Copy Files Build Phase.
+
+4) Choose Frameworks from the Where pop-up menu, select the ÒCopy only when installingÓ option, and drag the framework to the Files field.
+
+You can find the framework in the Products group in the projectÕs Files list.
+
+
 Copyright (c) 2002, 2003, Bob Frank
 All rights reserved.
 
@@ -96,3 +123,4 @@
 OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+