path: root/docs/startup-HOWTO.txt

 To new Irssi users (not to new IRC users ..)

 Copyright (c) 2000 by Timo Sirainen

I've explained all this to different people too many times, so finally
I bothered to write this small HOWTO :) For more details about some
things (still not all) see manual.txt.


 --- For all the lazy people ---

These settings should give you pretty good defaults (the ones I use):

/SET autocreate_own_query OFF
/SET -c autocreate_query_level (or /SET autocreate_query NO with 0.7.95 
and older versions)
/SET use_status_window OFF
/SET use_msgs_window ON
/SET autoclose_windows ON
/SET reuse_unused_windows ON

And example how to add servers:

/IRCNET ADD -autosendcmd "/^msg nickserv ident password" opn

/SERVER ADD -auto -ircnet ircnet irc.kpnqwest.fi 6667
/SERVER ADD -ircnet ircnet irc.funet.fi 6667
/SERVER ADD -auto -ircnet efnet efnet.cs.hut.fi 6667

And channels:

/CHANNEL ADD -auto #irssi ircnet
/CHANNEL ADD -auto -bots *!*@bot@host.org -botcmd "/^msg $0 op pass"
	     #irssi efnet


 --- Server and channel automation ---

Irssi's multiple IRC network support is IMHO very good - at least
compared to other clients :) Even if you're only in one IRC network you
should group all your servers to be in the same IRC network as this
helps with reconnecting if your primary server breaks and is probably
useful in some other ways too :)

First you need to have your IRC network set, use /IRCNET command to see
if it's already there. If it isn't, use /IRCNET ADD yourircnet. To make
Irssi work properly with different IRC networks, you might need to give
some special settings to /IRCNET ADD, see manual.txt for more
information about them. Irssi defaults to IRCNet's behaviour.

After that you need to add your servers. For example:

/SERVER ADD -auto -ircnet ircnet irc.kpnqwest.fi 6667

The -auto option specifies that this server is connected at startup.
You don't need to make more than one server with -auto switch, other
servers are automatically connected in same IRC network if the -auto
server fails.

And finally channels:

/CHANNEL ADD -auto -bots *!*@bot@host.org -botcmd "/^msg $0 op pass"
	     #irssi efnet

-bots and -botcmd should be the only ones needing a bit of explaining.
They're used to send commands automatically to bot when channel is
joined, usually to get ops automatically. You can specify multiple bot
masks with -bots option separated with spaces (and remember to quote
the string then). The $0 in -botcmd specifies the first found bot in
the list. If you don't need the bot masks (ie. the bot is always with
the same nick, like chanserv) you can give only the -botcmd option and
the command is always sent.

If the channel needs a key you can give it after the irc network.


 --- Placing the channels in the windows *I* want them to be in ---

First move the windows where you want them to be with /WINDOW MOVE
LEFT/RIGHT/number commands. After that use /SAVEWINDOWS command and
Irssi remembers the window positions the next time you start it.

This doesn't work very well with split windows currently.


 --- Jumping around in scrollback ---

Many clients have /LASTLOG command to find text from scrollback, but
with no easy way to jump to the position in scrollback where the
conversation was done in lastlog, except with keeping page up key down
for a long time.

Irssi has /SCROLLBACK (or alias /SB) commands for jumping around in
scrollback buffer, the most useful one is /SB GOTO time. You do a
"/LAST word", get list of lines where the word appeared with
timestamps, then you use "/SB GOTO hh:mm" to jump to wanted position.
"/SB END" jumps to end of scrollback buffer.


 --- Irssi's settings ---

You probably don't like Irssi's default settings. I don't like them.
But I'm still convinced that they're pretty good defaults. Here's some
of them you might want to change (the default value is shown):


 --- Queries ---

/SET autocreate_own_query ON - Should new query window be created when
you send message to someone (with /msg).

/SET autocreate_query_level MSGS - New query window should be created
when receiving messages with this level. Only MSGS and NOTICES levels
work currently. You can disable this with /SET -clear
autocrate_query_level. 0.7.95 and older versions use
/SET autocreate_query ON|OFF format.

/SET autoclose_query 0 - Query windows can be automatically closed
after certain time of inactivity. Queries with unread messages aren't
closed and active window is neither never closed. The value is given in
seconds.


 --- Windows ---

/SET use_msgs_window OFF - Create messages window at startup. All
private messages go to this window. This only makes sense if you're
disabled automatic query windows. Message window can also be created
manually with /WINDOW LEVEL MSGS, /WINDOW NAME (msgs).

/SET use_status_window ON - Create status window at startup. All
messages that don't really have better place goes here, like all /WHOIS
replies etc. Status window can also be created manually with /WINDOW
LEVEL ALL -MSGS, /WINDOW NAME (status).

/SET autoclose_windows OFF - Should window be automatically closed when
the last item in them is removed (ie. /PART, /UNQUERY).

/SET reuse_unused_windows OFF - When finding where to place new window
item (channel, query) Irssi first tries to use already existing empty
windows. If this is set ON, new window will always be created for all
window items. This setting is ignored if autoclose_windows is set ON.

/SET window_auto_change OFF - Should Irssi automatically change to
automatically created windows - usually queries when someone sends you
a message. To prevent accidentally sending text meant to some other
channel/nick, Irssi clears the input buffer when changing the window.
The text is still in scrollback buffer, you can get it back with
pressing arrow up key.

/SET print_active_channel OFF - When you keep more than one channel in
same window, Irssi prints the messages coming to active channel as
"<nick> text" and other channels as "<nick:channel> text". If this
setting is set ON, the messages to active channels are also printed in
the latter way.

/SET window_history OFF - Should command history be kept separate for
each window.


 --- User information ---

/SET nick (or default_nick in 0.7.95 and older) - Your nick name
/SET alternate_nick - Your alternate nick.
/SET user_name, /SET real_name - Your user- and real name.


 --- Server information ---

/SET skip_motd OFF - Should we hide server's MOTD (Message Of The Day).

/SET server_reconnect_time 300 - Seconds to wait before connecting to
same server again. Don't set this too low since it usually doesn't help
at all - if the host is down, the few extra minutes of waiting won't
hurt much.

/SET lag_max_before_disconnect 300 - Maximum server lag in seconds
before disconnecting and trying to reconnect. This happens mostly only
when network breaks between you and IRC server.


 --- Appearance ---

/SET timestamps ON - Show timestamps before each message.

/SET hide_text_style OFF - Hide all bolds, underlines, MIRC colors, etc.

/SET show_nickmode ON - Show the nick's mode before nick in channels, ie.
ops have <@nick>, voices <+nick> and others < nick>

/SET show_quit_once OFF - Show quit message only once in some of the
channel windows the nick was in instead of in all windows.

/SET topicbar ON - Show the channel's topic in top of screen.

/SET lag_min_show 100 - Show the server lag in status bar if it's
bigger than this, the unit is 1/100 of seconds (ie. the default value
of 100 = 1 second).

/SET indent 10 - When lines are longer than screen width they have to
be split to multiple lines. This specifies how much space to put at the
beginning of the line before the text begins. This can be overridden in
text formats with %| format.

/SET noact_channels - If you don't want to see window activity in some
certain channels or queries, list them here. For example
"#boringchannel =bot1 =bot2". If any highlighted text or message for
you appears in that window, this setting is ignored and the activity is
shown.

/SET mail_counter ON - Show the number of mails in your mbox in status
bar. The mbox file is taken from $MAIL environment setting. Only mbox
format works for now.

/SET statusbar_xxx - Change these to change the color of the statusbar.
Type "/SET statusbar" to see all the settings.


 --- Nick completion ---

/SET completion_auto OFF - Automatically complete the nick if line
begins with start of nick and the completion character. Learn to use
the tab-completion instead, it's a lot better ;)

/SET completion_char : - Completion character to use.


 --- Logging ---

Irssi can automatically log important messages when you're set away.
When you set yourself unaway, the new messages in away log are
printed to screen.

/SET awaylog_level MSGS HILIGHT - Specified what messages to log.
/SET awaylog_file ~/.irssi/away.log - Specifies to away log file.

Easiest way to start logging with Irssi is to use autologging. With it
Irssi logs all channels and private messages to specified directory.

/SET autolog OFF - Set ON to start logging.

/SET autolog_path ~/irclogs/$tag/$0.log - Log path. $0 specifies the
target (channel/nick), $tag is the server's tag you're logging. If
you're only in one IRC network or you're not in same named channels
with different IRC networks you don't really need this part. You can
also use strftime formats (see man 3 strftime) to specify when the log
file was created, Irssi also automatically rotates the logs if they're
used. The path is automatically created if it doesn't exist.

/SET autolog_level ALL -CRAP - Logging level, CRAP isn't logged because
WHOIS replies (and maybe some other nick-specific crap) would be logged
with it.