root/climm/doc/climmrc.5

.\"     $Id$ -*- nroff -*-
.\" EN: $Id$
.TH CLIMMRC 5 climm
.SH NAME
.B ~/.climm/climmrc
\- The configuration file for climm
.SH DESCRIPTION
This manual page describes the configuration files for climm. It consists
of several sections that are started by
.IR [section] ,
where
.I section
is the name of the section. File or directory names given are taken relative
to the base directory, which is usually ~/.climm/.
.SH CONNECTIONS
A
.B Connection
section describes a server connection within climm. Typically, these are
to connect to ICQ or XMPP servers.
You may also have a
remote control connection: that means a FIFO is opened, and lines read from
it are interpreted in the same way as input lines.
.TP
.BI type \ <type>\ [auto]
Set the connection type to
.IR type ,
which can be
.B icq8
for a connection to an ICQ v8 server or
.B xmpp
for a connection to an XMPP server.
If
.I auto
is given, create this connection on startup. You presumable want to do this,
unless you have several UINs, then set this on the connection corresponding
to this UIN you are using.
.TP
.BI version \ <nr>
Set the version of the protocol used for this connection to
.IR nr .
Please note that for a server connections, versions
.BR 5 ,
.B 7
and
.B 8
are supported, and for peer to peer connections
.BR 6 ,
.B 7
and
.BR 8 .
Remote control FIFOs don\'t have a version.
.TP
.BI server \ <server>
Set the server to connect to to
.IR server .
This defaults to
.IR login.icq.com .
Unused for peer to peer connections. For remote control fifos,
this is the path of the FIFO to be created.
.TP
.BI port \ <port>
Set the port to connect on the server to
.IR port ,
or the first port to try to listen on for peer to peer connections to
.IR port .
.TP
.BI uin \ <uin>
Set the UIN to log in with to
.IR uin .
Unused for peer to peer connections and remote control FIFOs.
.TP
.BI password \ [<password>]
Set the password to log in with to
.IR password .
Unused for peer to peer connections. If omitted, ask for password on startup.
Note: BeOS users may not omit the password.
.TP
.BI status \ <nr>
Set the status to be on log in in to
.IR nr .
Status can be:
.RS
.TP
0
online
.TP
1
away
.TP
5
not available
.TP
17
occupied
.TP
19
do not disturb
.TP
32
free for chat
.TP
256
invisible
.RE
.TP
.BI options \ <options>
Define options for this server connection. See the opt command in
climmcmds(7) for a complete list.
.SH GENERAL
The
.B General
section includes general options and some strings to override.
.PP
A few book-keeping options are usually placed at the beginning of
the climmrc file:
.TP
.BI encoding\ file\  <encoding>
Specify the encoding which is used for strings in this file as
.IR encoding .
climm will always write this file in UTF-8.
.TP
.BI encoding\ local\  <encoding>
Specify the user\'s terminal\'s encoding as
.IR encoding .
This overrides the encoding derived from environment variables.
.br
.B Note:
Using this will cause the locale to be flagged as broken, thus causing
characters outside the iso-8859-1 range to be printed in input handling as
hex unicode code points as their screen cell width cannot be determined with
wcwidth() anymore. Thus, always use the LC_CTYPE locale setting to override
the used character encoding.
.TP
.BI encoding\ remote\  <encoding>
Set the encoding to use for meta data on the server,
including the password, to
.IR encoding .
This encoding is also used for communicating with other contacts
whose client doesn\'t understand utf8 messages unless a specific
encoding is set for this contact.
Deprecated as of climm 0.5; use the
.I encoding
global option instead.
.TP
.BI format \ <nr>
Set the format this config file is to
.IR nr .
Format 2 is current, but format 1 is also accepted.
.PP
Now the other options:
.TP
.BI verbose \ <level>
Set the verbosity level on startup to
.IR level .
.TP
.BI auto_away \ <time>
Set the time to set status to away after to
.I time
seconds. Set to
.I 0
to disable.
.TP
.BI Screen_width \ <width>
Set the default screen width to
.IR width .
If unset or
.IR 0 , \ 80
will be used. This is rarely needed as usually
the current screen width can be deduced at runtime.
.TP
.BI set \ delbs\ on|off
If set to
.BR on ,
let the delete character act as a backspace. When
.BR off ,
let it act as a delete character.
.TP
.BI set \ funny\ on|off
Disable or enable "funny" messages.
.TP
.BI set \ color\ on|off
Disable or enable the use of colors.
.TP
.BI set \ hermit\ on|off
If set to
.BR on ,
ignore all messages from everyone not on your contact list.
Deprecated as of climm 0.5, set the global option
.I ignore
to
.I on
for the same effect.
.TP
.BI set \ log\ on|off
Disable or enable logging.
Deprecated as of climm 0.5, set the global option
.I logmess
to
.I on
for the same effect.
.TP
.BI set \ logonoff\ on|off
When logging, disable or enable the logging of online/offline status changes.
Deprecated as of climm 0.5, set the global options
.IR logmess \ and \ logchange
to
.I on
for the same effect.
.TP
.BI set \ auto\ on|off
Disable or enable automatic responses (reply messages).
.TP
.BI set \ autosave\ on|off
Disable or enable the automatic saving of the climmrc.
.TP
.BI set \ autofinger\ on|off
Disable or enable the automatic fingering of new UINs.
.TP
.BI set \ linebreak\ <type>
Configure the line break type for incoming messages to
.IR type ,
which can be
.B simple
to just wrap lines as usual,
.B break
to have a line break before each message,
.B indent
to have a line break and indent the message and
.B smart
to have a line break only if the message doesn\'t fit on the current line.
.TP
.BI set \ tabs\ simple|cycle|cycleall
Deprecated as of climm 0.5, as it uses a much improved tab handling now
which has all of the previous features.
.TP
.BI set \ silent\ <type>
Suppress some output, namely status changes for
.B on
and status changes, logins and logouts for
.BR complete .
Deprecated as of climm 0.5, use global options
.IR showchange \ and \ showonoff
to
.I on
for the same effect.
.TP
.BI options \ <options>
Set global options. See the
.I opt
command for details.
.TP
.BI chat \ <nr>
Set the random chat group to
.IR nr .
Use
.B \-1
to disable, and
.B 49
for climm (which is the default).
.TP
.B autoupdate \ <level>
Current level of automatic configuration updates done. Will be
incremented to a bigger value each time configuration is updated
to new default values. Do not make the mistake to set to 0 to
disable as that will have the effect of all updates being re-done.
.PP
At last, some strings can be defined:
.TP
.BI color\ scheme \ <nr>
Select the color scheme number
.IR nr .
.TP
.BI color \ <use>\ <color>
Select color
.IR color
for
.IR use .
.IR use
can be any of
.BR none ,
.BR server ,
.BR client ,
.BR message ,
.BR contact ,
.BR sent ,
.BR ack ,
.BR error ,
.BR debug
or
.BR incoming ,
while
.IR color
can be any one of
.BR black ,
.BR red ,
.BR green ,
.BR yellow ,
.BR blue ,
.BR magenta ,
.BR cyan ,
.BR white ,
.BR none ,
or
.BR bold
or a combination of those
.RB ( bold ,
however, must be last to take effect),
or any verbatim string to make the user\'s terminal
select the desired color.
.TP
.BI logplace \ <file>|<dir>
Set the file to log into to
.IR file ,
or the directory to log into to
.IR dir .
Please note that a path is assumed to be a directory if it has a trailing
.IR / .
.TP
.BI sound \ on|beep|off|event
Specify what happens if a beep is to be generated.
.B on
or
.B beep
will simply beep,
.B off
will do noting,
while
.B event
will call the script for events.
.TP
.BI event \ <script>
Set the script to execute for events to
.IR script .
It is called with the following arguments:
.br
1. The IM type, currently only
.BR icq .
.br
2. The UIN of the contact this event relates to, or 0.
.br
3. The nick of the contact this events to relates to, or the empty string.
.br
4. The string
.BR global .
.br
5. The type of this event, which can be
.BR msg ,
.BR on ,
.BR off ,
.BR beep
or
.BR status ,
where
.BR on \ and \ off
are for oncoming and offgoing contacts. This list may not be exhaustive.
.br
6. For messages, the message type, for offgoing contacts, the previous status,
and for oncoming contacts or status changes, the new status, otherwise 0.
.br
7. The text of the message.
.br
8. The contact\'s user agent.
.br
Note that for security reasons, single quotes may be replaced by double
quotes, and the message text may be truncated.
.TP
.BI auto \ <status>\ <string>
Set the automatic reply in status
.I status
to
.IR string .
This option may be repeated for all possible values
.BR away ,
.BR na ,
.BR dnd ,
.BR occ ,
.BR inv ,
and
.B ffc
for
.IR status .
.TP
.BI prompt_strftime \ <strftime_format>
Set format for option %T used in user
.IR prompt .
For details see climmcmds(7) and strftime(3).
.SH STRINGS
The
.B Strings
section contains command renames.
.TP
.BI prompt \ <user_prompt>
Set user prompt in
.IR user_prompt .
For details see command
.IR prompt 
in climmcmds(7).
.TP
.BI alter \ <old>\ <new>
Rename command
.I old
to
.IR new .
Note the old name may still be used, unless it conflicts with some
.I new
name.
For possible command names, see
.BR climmcmds (7).
This option may be repeated as desired.
.br
Note: this option is obsolete, use
.I alias
instead.
.TP
.BI alias\ [auto[expand]] \ <alias>\ <expansion>
Define an alias named
.I alias
which is substituted with
.IR expansion .
If the
.I auto
or
.I autoexpand
keyword is given, the expansion also happens when the space key
or the return key is pressed directly after the alias.
If the string
.B %s
is present in
.IR expansion ,
each occurence is replaced with the given arguments when the alias is invoked,
otherwise they will be appended.
If the string
.B %r
is present in
.IR expansion ,
each occurence is replaced by the nick name or, if the nick is not
available, the UIN, of the contact that sent the last message to you,
or the empty string if there is none.
If the string
.B %a
is present in
.IR expansion ,
each occurence is replaced by the nick name or, if the nick is not
available, the UIN, of the contact that you sent the last message to,
or the empty string if there is none.
.br
New for 0.4.10. Auto-expanding aliases new for 0.5.0.4.
.SH GROUP
The
.B Group
section contacts a contact group and may be repeated as required. Note
that for format 2, it is saved in the BASE/status file, not in
BASE/climmrc.
It may have the following commands:
.TP
.BI server \ <type>\ <uin>
Set the server connection this contact group belongs to to the one of type
.IR type ,
which currently can be 
.BR icqv8
for ICQ server connections version 8 or
.BR icqv5
for ICQ server connections version 5,
and for UIN
.IR uin .
If this command is omitted, the first active server connection is assumed.
.TP
.BI label \ <label>
Set the label of this contact group to
.IR label .
If it is
.BI contacts- <type> - <uin>,
then it is the contact list for this server connection. Note that for format 2
of the BASE/status file, this is obsolete, as the contacts distributed to
the server connections according to the server statement in their Contacts
section.
.TP
.BI id \ <id>
Set the id of this contact group to
.IR id .
.B 0
means no id defined. This will be set when downloading or uploading a contact list.
.TP
.BI options \ <options>...
Define options for this contact group. See the
.I opt
command for details.
.TP
.BI entry \ <id>\ <uin>
Add contact with UIN
.I uin
as id
.I id
to this contact group. Note that
.I id 
is obsolete as of climm 0.5 and always set to 0. The id is set
in the
.I Contacts
section instead.
.SH CONTACTS (obsolete format)
The
.B Contacts
section contains the (global) contact list. It is obsolete in this format.
.TP
.I [*][~][^] uin nick
Make user with UIN
.I uin
known under the nick
.IR nick .
If
.B *
is given, the user may see you while you\'re invisible. If
.B ~
is given, let him see you as always offline. If
.B ^
is given, ignore this user.
If a uin occurs multiple times, all except the first are treated as aliases.
.SH CONTACTS
The
.B Contacts
section contains a contact list for one server connection. It is
repeated for each server connection.
Note that it is saved in the BASE/status file, not in BASE/climmrc.
It may have the following commands:
.TP
.BI server \ <type>\ <uin>
Defines the server connection this is the contact list for, with the
same syntax as in the
.I Group
section.
.TP
.BI entry \ <id>\ <uin>\ <nick>...
Adds user with the UIN
.I uin
and id
.I id
to this contact list, with nick and arbitrary many aliases
.IR nick .
.TP
.BI options \ <options>...
Define options for the previous contact. See the
.I opt
command for details.
.SH SEE ALSO
.BR climm (1),
.BR climmcmds (7)
.SH AUTHOR
This man page was written by James Morrison
.IR <ja2morrison@student.math.uwaterloo.ca> .
It was rewritten to match new config file syntax by R\(:udiger Kuhlmann
.IR <climm@ruediger-kuhlmann.de> .