Onsala 2000-09-11
			How to configure TkRat

   TkRat software and its included text is Copyright 1996-2000 by
   Martin Forssén.

   The full text of the legal notices is contained in the file called
   COPYRIGHT, included with this distribution.


	WHAT GOES INTO THE FILES

You can set a lot of options for TkRat via a couple of configuration
files, but you don't have to. All options should have reasonable default
values.
It is however recommended that the site administrator changes the site
defaults in the configuration file in the SITE directory (see below). The
user can then later do their own customizations from inside the program.
These user changes are saved in the users '~/.ratatosk/ratatoskrc' file.


	LOCATION OF CONFIGURATION FILES

The configuration files are first read from the SITE directory and then from
the users ~/.ratatosk directory. The configuration file is called 'ratatoskrc'.
The default SITE directory is /usr/local/etc. This will change if you give a
--prefix argument to configure (or --sysconfdir).


	SYNTAX OF CONFIGURATION FILES

The configuration files are read via the tcl source command which means that
they can have any valid tcl syntax. TkRat defines a 'RatLock' command which
locks a given variable so that it may not be changed anymore. An example of
an configuration file may look like this:

    # This is a comment line.
    # The lines below sets our domain to 'dtek.chalmers.se' and locks
    # the value so that the users can't change it (easily that is).
    set option(domain) dtek.chalmers.se
    RatLock option(domain)

    # Set the default editor
    set option(editor) "xterm -e vi %s"


	OPTIONS

Below follows a list of the options a site administrator normally might want
to set in the site-specific configuration file. To set option NAME in the
file you should use 'set option(NAME) VALUE'.

This is just a subset of the options. For a full list check the options.tcl
file in the tkrat subdirectory. Beware that many of the options have special
syntax and meanings. It is strongly recommended that you use the preferences
window in TkRat to change the options.

    NAME		DESCRIPTION
    language		The default language of the user interface. Currently
			the only possible values are 'en', 'sv', 'it', 'fr'
			and 'sr' (English, Swedish, Italian, French and
			Serbian). The default is English.

    default_folder	The definition of the folder that gets opened when
			the program is started for the first time. It will
			then be written into the users vfolderlist and this
			variable does not modify it any more. See FOLDER
			DEFINITIONS below for more details.

    editor		The default external editor. The editor will NOT be
			run in a terminal window. A '%s' must be included
			and will be expanded to the name of the file to edit.
			This defaults to 'emacs %s'.

    masquerade_as	If this option is set all messages sent (ie the From
			address) will look as if they came from the specified
			domain (ie the value of the option). No hostname will
			be included in the address. The default is no value.

    domain		The domain this host resides in. This option will be
			ignored if masquerade_as has a value.

    use_from		If this is true then the user may specify the address
			that goes on the From: line. If it is false then TkRat
			generates an address automatically. If true and if
			the user specifies an address which the program
			doesn't think points to the user a Sender: line is
			added.

    sendprot		Which protocol to use to send messages. Valid values
			are 'smtp' and 'prog'. The default is 'smtp'.

    smtp_hosts		A list of hosts that will be used to send messages
			via SMTP. The system will first try the first host,
			if that fails the second and so on. The default is
			'localhost'.

    sendprog		Which program to use if we are sending messages with
    			the 'prog' protocol. The program will be called with
			the recipients as arguments and the message on stdin.
			Default is '/usr/lib/sendmail'.

    sendprog_8bit	This option can be either '1' or '0' and
			indicates whether the sendprog can handle characters
			with the eight bit set. This defaults to 'false'.

    lookup_name		If this is set to '1' then TkRat will look in
			the local passwd-file for the full names of users
			when addressing messages. This might be time-consuming
			so some sites might want to disable it by default. The
			default is '1'.

    mail_steal		If this is true then we should check for mail
			that netscape has stolen from the inbox every time
			we start the application. The default is '1'.

    icon		This defines which icon bitmap the program should
			install. The possible values are: "normal" (a 64x64
			bitmap), "small" (50x50) and none. Default is normal.

    system_aliases	The identification of a system-wide address book.
			This should be a list with three elements:
				{NAME tkrat PATH}
			NAME is the name of the address book the user should
			see, tkrat is a keyword which says this file is in
			the tkrat-format (other possible values are pine,
			mail and elm). The last value is the path to the
			address book

    simple_prot		The protocol used for simple folders. This can be
			either file, mh or imap. Simple folders is a simple
			way to create folders, the user just enters a name
			and tkrat fills in the rest. This option (and the next)
			determines what tkrat does.

    simple_data		This is the extra data needed for the simple folder.
			If the simple_prot is file, then this option should
			contain the path under which the users folders should
			be created. If the protocol is mh then it is ignored.
			If the protocl is imap the it should contain an
			host:port pair (where :port may be omitted).


	FOLDER DEFINITIONS

Each folder is defined by a tcl list. For example the default value of default_
folder is "INBOX file {} /usr/spool/mail/$env(USER)". This is a list of four
elements, the first is the symbolic name of the folder, the second is the
type of folder, the third is a flag-field and the fourth is the actual file.
To set a value like this in a configuration file you write:

    set option(default_folder) "INBOX file {} /var/spool/mail/$env(USER)"

There are four different types of folders one might have as inboxes. The
syntax for them are (values written in capital letters should be customized,
other characters must be exactly as written):

File folders:	"NAME file {} FILENAME"
POP3 folders:	"NAME pop3 {} {{HOST:PORT/pop3}} USER"
IMAP folders:	"NAME imap {} {{HOST:PORT/imap}MAILBOX} USER"
Disconnected:	"NAME dis {} {{HOST:PORT/imap}MAILBOX} USER"

Note that the :PORT part is optional.


	CHARACTER SET ALIASES

You can instruct TkRat that one character set name really means another
character set. This is useful when dealing with software that is improperly
configured and therefore emits strange character set names. TkRat contains
a number of such aliases when shipped but each site may want to extend the
list to cover more names. 

To add more aliases you must create a charsetAliases file in any of the
configuration directories. This file should have lines in the following format:

set charsetAlias(ALIAS) NAME

This line says that ALIAS is an alias and the real name is NAME. I would also
appreciate if you notified me (maf@dtek.chalmers.se) of any aliases you think
should be built in into the release.