Index: ossp-pkg/l2/l2_syslog.pod
RCS File: /v/ossp/cvs/ossp-pkg/l2/Attic/l2_syslog.pod,v
rcsdiff -q -kk '-r1.1' '-r1.2' -u '/v/ossp/cvs/ossp-pkg/l2/Attic/l2_syslog.pod,v' 2>/dev/null
--- l2_syslog.pod	2002/06/27 09:24:40	1.1
+++ l2_syslog.pod	2002/07/02 09:50:51	1.2
@@ -31,7 +31,7 @@
 
 =head1 NAME
 
-B<l2_syslog> - L2 syslog replacement
+B<OSSP l2syslog> - L2 based syslog(3) replacement
 
 =head1 VERSION
 
@@ -39,72 +39,65 @@
 
 =head1 SYNOPSIS
 
-=over 4
-
-CPPFLAGS="-I /FIXME/include"
-
-LDFLAGS="-L /FIXME/lib"
-
-LIBS="-Ll2syslog -Ll2"
-
-=back
+ LDFLAGS=`l2-config --ldflags` \
+ LIBS="-ll2syslog -ll2" \
+ ./configure [...]
 
 =head1 DESCRIPTION
 
-The B<l2_syslog> is a library offering the syslog(3) API otherwise
-provided by the Standard C Library.  Instead of writing dump log files
-it uses the powerful L2 logging capabilities. It is a drop-in
-replacement which enables any syslog(3) consumer to take advantage of L2
-by just linking this library against an existing object. The source code
-remains unchanged.
+B<OSSP l2syslog> is a companion library to B<OSSP l2>, offering the
+syslog(3) API otherwise provided by the Standard C Library (F<libc>).
+Instead of writing to the syslogd(8) process, it uses the powerful
+B<OSSP l2> logging capabilities. It is a drop-in link-time replacement
+which enables any syslog(3) consumer to take advantage of B<OSSP l2>
+by just linking this library in before F<libc>. The source code of the
+program remains unchanged.
 
 =head1 FILES
 
-The B<l2_syslog> library reads configuration sections located in one or
-more files. The path to the directory containing these file(s) is
-specified at compile time and is given to the configure script via
-'--with-syslog-cfgdir=...'.
+The B<OSSP l2syslog> library reads configuration sections located in
+one or more files. The path to the directory containing these file(s)
+is specified at compile time and is given to the configure script via
+C<--with-cfgdir=>I<cfgdir>.
 
 =head1 OPERATION
 
-When an application calles openlog(3) it passes an ident string and a
-log facility along. B<l2_syslog> tries to read the file
-C<syslog-cfgdir/>I<ident>. If the file is not readable, all files
-matching C<syslog-cfgdir/l2*> are read. All data that has been read in
-is then parsed for configuration sections. These are identified by
-'%ident I<match>' at the beginning of line. The I<match> argument is a
-PCRE (Perl Compatible Regular Expression) that is matched against a
-string concatenated from I<ident>/I<facility> given to the openlog(3)
-call.  The configuration section contains a L2 specification enclosed in
-curly brackets where the closing bracket must be placed on the beginning
-of a line. The L2 specification may contain $1, $2 ... variables
-which are filled from regex matches enclosed in round brackets.  A
-channel tree is build from each matching section and all trees form a
-single metatree. Further calls to syslog(3) will then inject log
-messages into this metatree.
+If an application calls openlog(3) it passes an identification string
+(I<ident>) and a logging facility (I<facility>) along. B<OSSP l2syslog>
+tries to read the file "C<cfgdir>C</l2.>I<ident>". If the file is not
+readable, all files matching I<cfgdir>C</l2.*> are read.
+
+In both cases, all data that has been read in is then parsed for
+configuration sections. These are identified by "C<ident >I<match>"
+at the beginning of a line. The I<match> argument is a PCRE (Perl
+Compatible Regular Expression) that is matched against a string
+concatenated from "I<ident>/I<facility>" given to the openlog(3) call.
+
+The configuration section contains an B<OSSP l2> specification enclosed
+in curly brackets where the closing bracket must be placed on the
+beginning of a line and terminated with a semicolon. The B<OSSP l2>
+specification may contain $1, $2, ... variables which are filled in from
+the I<match> regex parts enclosed in round brackets.
+
+An B<OSSP l2> channel tree is build from each matching section and all
+found trees are merged together with a "null" channel to form a single
+tree. Further calls to syslog(3) will then inject log messages into this
+channel tree.
 
 =head1 EXAMPLE
 
-=over 4
-
-%ident sendmail/.* {
-
-    debug:
-        prefix(
-            prefix="%%b %%d %%H:%%M:%%S <%%L> $1 [%%P]: ",
+ ident sendmail/.* {
+   debug:
+     prefix(prefix="%%b %%d %%H:%%M:%%S <%%L> $1 [%%P]: ",
             timezone=local)
-        -> file(
-            path="sendmail.debug.log",
-            append=0,perm=432)
-
-}
+     -> file(path="sendmail.debug.log", append=0,perm=432)
+ };
 
-=back
 
 =head1 OPENPKG
 
-OpenPKG RPM packages must require "l2" for both %BuildPreReq and
-%PreReq.
+OpenPKG RPM packages must require the package "l2" in both C<BuildPreReq> and
+C<PreReq> and force the packaged application to link against F<libl2syslog.a>.
 
 =head1 SEE ALSO