ezbounce v2.0 User Preferences System
---------------------------------------------------------
Last Updated: $Date: 2008-01-03 22:56:40 -0600 (Thu, 03 Jan 2008) $


1. Introduction

The user preferences system in ezbounce v2.0 provides a powerful and flexible
way for users to customize their personal settings.


2. Differences from Earlier Versions

Users will find the configurable preferences and interface to be similar
to old versions.

The major improvement is the ability to customize preferences for individual 
IRC networks, servers and channels.  For example, chat logging options can 
now be controlled for individual channels.  Previously it could only turned 
on or off globally. 


3. Organization of Preferences

The configurable preferences are organized into a hierarchy of 4 different levels:
	
	- A root, or top level
	- IRC Network level
	- IRC Server level
	- IRC Channel level

Each level has its own set of preferences.  For example, the top level has
options to hold the preferred vhost and fake ident, while the IRC Server level
has options such as auto-detach.  

The settings are stored in a tree-like structure.  A 'node' exists for the top
level which has 1 or more children of the Network level.  The pattern is
repeated; each Network-level node has 1 or more children of the Server level.
Once again the pattern is repeated; each Server-level node has 1 or more
children of the Channel level.  

Initially each node only has 1 child -- called "default."  So, the root node
has a Network-level child "default", and that node has a Server-level child
"default" and so on.  Additional nodes are created as needed when you set
options.  For example, if you set an option on Network EFNet, a node for EFNet
will be created.

This structure allows settings to be customized for individual channels,
networks and even particular IRC servers.  For example, you can set an
option for any channel named #sports, or only the channel #sports on EFNet.

TODO: expand this section

4. Option Types

Currently there are 3 types of preferences:

	- Boolean: Acceptable values for these are true/false, 0/1 or on/off
	- Integer: Acceptable values depend on the option being set.
	- String:  Plain text. It is recommended you enclose these in quotes.
	

5. Available Preferences

For brevity, the complete set of options will not be listed here.  You may use 
the 'preferences' or 'options' command while logged in to see the list.  You 
can also get helpful description of an option with the 
'help option <option name>' command.

Here are a few of the available options:

Top Level:
     auto-server
     fake-ident
     vhost

IRC Server Level:
     auto-detach
     proxy-dcc-in
     proxy-dcc-out
     set-away-on-detach

IRC Channel Level:
     auto-rejoin
     log-detached-only
     enable-logging


NOTE: There are actually no Network-level options.  The Network level exists
mainly to consolidate multiple IRC Server nodes under one parent.


6. Target Lists

Target lists are the final important thing to understand about the
user preferences system.

A target list precisely defines what node or nodes a configuration command
refers to.  Recall the 4-level hierarchy and tree-like structure that the
settings are stored in.  A target list simply specifies a particular channel, IRC server,
or IRC network in that tree-like structure.

A target list consists of zero or more of the following pairs:

	<node class> <node name>

The 3 node classes are:  network, server, and channel

The node names depend on the node classes and should be self-explanatory. 

Here are some sample target lists:

	network quakenet
	
	network efnet  channel #sports

	network efnet  server irc.prison.net  channel default

	network quakenet  server default

	network default  channel default


The 'get' and 'set' optionally take in a target list as a parameter.  If you
don't specify one, a default one is generated.  For instance, trying to set
the channel-level option 'auto-rejoin' with no target list causes it to use a default one:

"network default  server default  channel default"

If you omit leading or trailing elements in the target list, they are
automatically filled in as well.  For example, 

	set  network efnet  auto-rejoin on

	automatically expands to:

	set  network efnet  server default  channel default  auto-rejoin on


Another example:

	set  channel #sports enable-logging  true

	becomes:

	set  network default server default channel #sports  enable-logging true


Also note that the elements of a target list must be in the right order.  For
example "channel #dummy network quakenet" is not a valid target list.


7. Setting Preferences

Use the 'set' command to set preferences.  The syntax is:

set [target list] <option> <value>


TODO: expand this section


8. Examples

This sets the root-level option auto-server.  Note that for root-level
options, there is no target list to specify:

	set auto-server "irc.prison.net"


This enables auto-rejoin for all channels by default:

	set auto-rejoin on

    (the following forms of the command are identical)

	set channel default auto-rejoin on
	set network default channel default auto-rejoin on


This set of commands enables auto-detach by default for all IRC Networks, but
disables it for QuakeNet.

	set auto-detach on
	set network QuakeNet auto-detach off

    (this sequence of commands is equivalent to the following)

	set network default server default auto-detach on
	set network quakenet channel default auto-detach off	
	



9. Viewing Preferences

Use the 'get' command to view the value of a preference for a particular target.

get [target list] <option>

TODO: Expand this section.


10. Other Commands

TODO


11. Notes


Sample configuration tree:

[Root]
   |
   |`-----------t-------------------------\
   |            |                         |
[Default ]    [EFNet]                [UnderNet]
[Network ]      |                         |
   |            |                         |-------------\
   |            |                         |             |
[Default ]    [Default  ]              [Default ]    [us.undernet.org]
[Server  ]    [Server   ]              [Server  ]        |
   |            |-------------\            |             |----------\
   |            |             |            |             |          |
[Default ]    [Default  ]   [#sports]  [Default ]     [Default]  [#sports]
[Channel ]    [Channel  ]              [Channel ]     [Channel]
   
   (#1)          (#2)          (#3)       (#4)           (#5)       (#6)


And these are the target lists for each listed channel node:

	#1: network default  server default	    channel default
	#2: network efnet    server default	    channel default
        #3: network efnet    server default	    channel #sports
        #4: network undernet server default	    channel default
	#5: network undernet server us.undernet.org channel default
        #6: network undernet server us.undernet.org channel #sports