Index: ossp-pkg/fsl/fsl.pod
RCS File: /v/ossp/cvs/ossp-pkg/fsl/fsl.pod,v
rcsdiff -q -kk '-r1.4' '-r1.5' -u '/v/ossp/cvs/ossp-pkg/fsl/fsl.pod,v' 2>/dev/null
--- fsl.pod	2002/07/22 15:16:32	1.4
+++ fsl.pod	2002/07/23 09:40:38	1.5
@@ -86,61 +86,77 @@
 
 =head1 L2SPEC
 
-l2_ch_buffer.c:    size,           INT, &cfg->bufsize);
-l2_ch_buffer.c:    interval,       INT, &cfg->bufinterval);
-l2_ch_buffer.c:    levelflush,     INT, &cfg->levelflush);
-
-l2_ch_fd.c:        filedescriptor, INT, &cfg->fd);
-
-l2_ch_file.c:      path,           STR, &cfg->path);
-l2_ch_file.c:      append,         INT, &cfg->append);
-l2_ch_file.c:      perm,           INT, &cfg->perm);
-
-l2_ch_filter.c:    regex,          STR, &cfg->szRegex);
-l2_ch_filter.c:    negate,         INT, &cfg->bNegate);
-l2_ch_filter.c:    nocase,         INT, &cfg->bNoCase);
-
-l2_ch_irc.c:       progname,       STR, &cfg->cpLocalProg);
-l2_ch_irc.c:       localhost,      STR, &cfg->cpLocalHost);
-l2_ch_irc.c:       localuser,      STR, &cfg->cpLocalUser);
-l2_ch_irc.c:       nickname,       STR, &cfg->cpNickname);
-l2_ch_irc.c:       username,       STR, &cfg->cpUsername);
-l2_ch_irc.c:       realname,       STR, &cfg->cpRealname);
-l2_ch_irc.c:       channel,        STR, &cfg->cpChannel);
-l2_ch_irc.c:       join,           INT, &cfg->bJoin);
-l2_ch_irc.c:       host,           STR, &cfg->cpHost);
-l2_ch_irc.c:       port,           STR, &cfg->cpPort);
-l2_ch_irc.c:       timeout,        INT, &cfg->nTimeout);
-
-l2_ch_pipe.c:      execmode,       STR, &szMode); /* mode direct or shell  */
-l2_ch_pipe.c:      runtime,        STR, &szRel);  /* continuous or oneshot */
-l2_ch_pipe.c:      path,           STR, &cfg->szCmdpath); /* path of cmd   */
-
-l2_ch_prefix.c:    prefix,         STR, &cfg->prefix);
-l2_ch_prefix.c:    timezone,       STR, &cfg->timezone);
-
-l2_ch_smtp.c:      progname,       STR, &cfg->cpLocalProg);
-l2_ch_smtp.c:      localhost,      STR, &cfg->cpLocalHost);
-l2_ch_smtp.c:      localuser,      STR, &cfg->cpLocalUser);
-l2_ch_smtp.c:      from,           STR, &cfg->cpFrom);
-l2_ch_smtp.c:      rcpt,           STR, &cfg->cpRcpt);
-l2_ch_smtp.c:      subject,        STR, &cfg->cpSubject);
-l2_ch_smtp.c:      host,           STR, &cfg->cpHost);
-l2_ch_smtp.c:      port,           STR, &cfg->cpPort);
-l2_ch_smtp.c:      timeout,        INT, &cfg->nTimeout);
-
-l2_ch_socket.c:    proto,          STR, &cfg->szProto);
-l2_ch_socket.c:    host,           STR, &cfg->szHost);
-l2_ch_socket.c:    port,           STR, &cfg->szPort);
-l2_ch_socket.c:    timeout,        INT, &cfg->nTimeout);
-
-l2_ch_syslog.c:    target,         STR, &cfg->szTarget);
-l2_ch_syslog.c:    remotehost,     STR, &cfg->szRemoteHost);
-l2_ch_syslog.c:    remoteport,     INT, &cfg->nRemotePort);
-l2_ch_syslog.c:    localhost,      STR, &cfg->szLocalHost);
-l2_ch_syslog.c:    facility,       STR, &cfg->szFacility);
-l2_ch_syslog.c:    ident,          STR, &cfg->szIdent);
-l2_ch_syslog.c:    logpid,         INT, &cfg->bLogPid);
+The "logging library" (L2) builds its working configuration using a
+global environment object and channels which are interconnected to form
+a tree.  The environment object holds general internal information and
+maintains the registration of formatters.  The channels are used to
+process the logging message and use formatters to transform it.  The
+root channel of the tree and each intermediate channel might have one or
+more children below it, passing the processed message down the tree. The
+leafs of the tree are constructed by channels specifically designed for
+outputting the message.  Every logging message is injected into a
+channel, most likely the uppermost one, and traverses down the tree
+where channels with multiple children duplicate the message.  L2 allows
+a developer to build this tree programmatically.  In addition, L2 also
+supports building up the channel tree using a text based specification
+called the l2spec. The l2spec offers maximum flexibility as a program
+can read a l2spec created by a system administrator and pass it to L2
+verbatim without even knowing anything about existing channels.  When
+this approach is used, a newly designed channel can be used by an
+existing program by just linking in the latest lib_l2. The main program
+remains unmodified.
+
+FIXME T_ID, channel_cons, try to remove the word "streams"
+
+B<tree>          ::= B<stream>
+
+B<stream>        ::=
+                | B<channel>
+                | B<channel> => stream
+                | B<channel> => '{' streams '}'
+
+B<streams>       ::=
+                | stream
+                | stream ';' streams
+
+B<channel>       ::=
+                | B<channel_level> '/' B<channel_level> ':' B<channel_cons>
+                | B<channel_level> ':' B<channel_cons>
+                | B<channel_cons>
+
+B<channel_level> ::=
+                | T_ID
+                | '(' B<channel_mask> ')'
+
+B<channel_mask>  ::=
+                | T_ID
+                | T_ID '|' B<channel_mask>
+
+B<channel_params>::= I<empty>
+                | '(' ')'
+                | '(' B<channel_plist> ')'
+
+B<channel_plist> ::=
+                | B<channel_param>
+                | B<channel_param> ',' B<channel_plist>
+        
+B<channel_param> ::=
+                | paramter '=' value
+ 
+
+Here is a table of available channels that lists their names and
+parameters including the type of each parameter.
+
+buffer (INT size, INT interval, INT levelflush);
+fd     (INT filedescriptor);
+file   (STR path, INT append, INT perm);
+filter (STR regex, INT negate, INT nocase);
+irc    (STR progname, STR localhost, STR localuser, STR nickname, STR username, STR realname, STR channel, INT join, STR host, STR port, INT timeout);
+pipe   (STR execmode, STR runtime, STR path);
+prefix (STR prefix, STR timezone);
+smtp   (STR progname, STR localhost, STR localuser, STR from, STR rcpt, STR subject, STR host, STR port, INT timeout);
+socket (STR proto, STR host, STR port, INT timeout);
+syslog (STR target, STR remotehost, INT remoteport, STR localhost, STR facility, STR ident, INT logpid);
 
 =head1 EXAMPLE