# $EPIC: server_description.txt,v 1.4 2006/11/23 17:07:48 jnelson Exp $
======Special Topic:======
A [[server description]] is the way you give the client enough information
about an irc server for it to be added to the server list and used.

Any place you are supposed to provide a "server", you can provide either
a server refnum, or the server description.

======About server descriptions:======
A server description is a colon-separated list of several data items that 
changes from time to time.  

| hostname | The hostname or p-addr of the server                           |
| port     | The port the server is running on (default: 6667)              |
| password | The irc PASSword (if necessary) to log on with (default: none) |
| nickname | The irc NICKname to log on with (default: global nickname)     |
| group    | The server group this belongs to (default: no group)           |
| type     | The protocol type to use, either IRC or IRC-SSL (default: IRC) |
| protocol | The socket protocol to use, either "tcp4" or "tcp6" or "any"   |
| vhost    | The local address (virtual host) to use for the connection     |

Only the //hostname// field is mandatory.  If you want to use the default 
value in a field, you can leave it blank.

Because the server description is colon separated, IPv6 p-addrs have to be
surrounded in square brackets such as //[fe::00]//.

======Server descriptions and skipping fields:======
It can be confusing to keep track of which field you want to set, especially
when you want to skip some of the middle fields.  Each field has a name, 
which you can see in the above table.  You can switch around to any field
at any time by "assigning" to a field name:
	irc.foobar.com:7002:type=IRC-SSL
and you can abbreviate a field name as long as it's not ambiguous:
	irc.foobar.com:pr=tcp6

If you skip fields by doing an assignment, any following (unassigned)
fields are in the same natural order as in the above table:
	irc.foobar.com:group=efnet:IRC-SSL
(since 'type' follows 'group', the field after the 'group=' is 'type'.)

You don't have to skip fields in order, you can skip around and specify
them however you want.  If you happen to specify a field multiple times, 
the last one is the one that will be used.

======About server refnums and the server list:======
Any time you present a new server description to the client, it is added to
the server list and is assigned a unique reference number.  This is also 
called a "servref" or "refnum".  A server refnum is an internal number which
is used to map windows, channels, timers, and other things to the appropriate 
server.  

The //hostname// and //port// fields create the primary key for the server 
list.  Two servers that have the same hostname and port are considered to 
be the same server.

======Examples:======
A server on irc.foobar.com, port 6667, where you use the nickname "JoeBob":
      irc.foobar.com:::JoeBob

A server on irc.foo.com, port 6666, using nickname "blah"
      /server -add irc.foo.com:6666::blah

A server on irc.foo.com, port 8000, that uses SSL
     /server irc.foobar.com:8000::::IRC-SSL