# $EPIC: onchannel,v 1.6 2002/01/13 00:27:11 anders Exp $
Synopsis:
   $onchannel()			(First Action)
   $onchannel(<channel>)		(First Action)
   $onchannel(<nick> <channel>)	(Second Action)

Technical:
   * There are two different actions provided by this function.  The first
     action is to provide a list of nicknames that are on a channel.  The
     section action is to tell you whether a particular person is on a
     particular channel.

   First Action (list of channel members):
   ---------------------------------------
   * If no arguments are provided, the current window's current channel is
     assumed, and the first action is performed.  NOTE THAT THIS MAY NOT
     NECCESARILY BE THE CORRECT CHANNEL IN AN /ON!
   * If the first argument is a channel name or the literal asterisk (``*'')
     then the first action is performed using the specified channel name.
     If the argument is an asterisk, the current window's current channel
     is used.  NOTE THAT THIS MAY NOT NECCESARILY BE THE CORRECT CHANNEL
     IN AN /ON!
   * If you are not on the specified channel on the current server, the
     empty string is returned.
   * On ircnet servers, anonymous channels (+a channel mode) won't give you
     a list of the channel members, and so you won't get anything useful
     out of this function.
   * In general you can't use this function in the status bar.
   * In ircII, this function is called $chanusers().  $chanusers() is
     available in epic for compatibility with ircII.

   Second Action (is this person on this channel?):
   ------------------------------------------------
   * If the first argument is not a channel name, then it is considered to
     be a nickname.  The second argument is taken to be a channel name.  If
     the channel argument is omitted, the empty string is returned.
   * If you are not on the specified channel, the return value is 0.
   * If the given nickname is not on the specified channel the return value
     is 0.
   * Between the time you JOIN a channel and when /ON CHANNEL_SYNC is thrown
     for that channel, the return value may be 0 or 1.
   * In some versions of the server, the NAMES reply sent to the client when
     you join truncates the last nickname.  This may result in a nickname
     not properly being added to the channel's cache.  This may return a
     false negative (0) value.  The client tries to compensate for this by
     watching the WHO reply.  You may get false negatives until 
     /ON CHANNEL_SYNC is thrown for the channel.
   * In general you can't use this function in the status bar.

Practical:

Returns:
   First action: A word list containing the members of the specified channel,
	or the current channel.  You must be on the channel.  There are some
	circumstances where this may fail.

   Second action: 1 if the specified user is on the specified channel, and 0
	if they are not.  You must be on the channel.  Bugs in the historical
	server implementation may result in false negatives sometimes.  There
	are some circumstances where this may fail.

Examples:

History:
   The first action is the historical EPIC behavior and first appeared in
   the "+3" client (post-ircII, pre-EPIC).  The ircII function $chanusers()
   is equivalent and first appeared around ircII-2.6.  Support for
   $chanusers() was added to EPIC1.

   The second action is the modern ircII behavior and first appeared around
   ircII-2.3.24.  Support for this was added around EPIC1.

See Also:
   names(2); on channel_sync(5); join(1); who(1)

