updated

git-svn-id: http://svn.irssi.org/repos/irssi/trunk@1346 dbcabf3a-b0e7-0310-adc4-f8d773084564

docs/startup-HOWTO.txt

@@ -4,19 +4,41 @@
  Copyright (c) 2000-2001 by Timo Sirainen
 
 
-I've explained all this to different people too many times, so finally
+Index with some FAQ questions that are answered in the chapter:
-I bothered to write this small HOWTO :) For more details about some
+
-things (still not all) see manual.txt.
+ 1. For all the lazy people
+ 2. Basic user interface usage
+ 3. Server and channel automation
+      - how do I automatically connect to servers at starup?
+      - how do I automatically join to channels at startup?
+ 4. Setting up windows and automatically restoring them at startup
+ 5. Status and msgs windows & message levels
+      - I want /WHOIS to print reply to current window
+      - I want all messages to go to one window, not create new windows
+      - I want to have own status and/or msgs window for each servers
+ 6. How support for multiple servers works in irssi
+      - I connected to some server that doesn't respond and now irssi
+        keeps trying to reconnect to it again and again, how can I stop it??
+ 7. /LASTLOG and jumping around in scrollback
+      - How can I save all texts in a window to file?
+ 8. Logging
+ 9. Irssi's settings
 
 
- --- For all the lazy people ---
+ 1. For all the lazy people
+ --------------------------
 
 These settings should give you pretty good defaults (the ones I use):
 
+I don't like automatic query windows, I don't like status window, I do
+like msgs window where all messages go:
   /SET autocreate_own_query OFF
   /SET autocreate_query_level DCCMSGS
   /SET use_status_window OFF
   /SET use_msgs_window ON
+
+Disable automatic window closing when /PARTing channel or /UNQUERYing
+query:
   /SET autoclose_windows OFF
   /SET reuse_unused_windows ON
 
@@ -26,24 +48,109 @@ And example how to add servers:
 joining channels)
   /IRCNET ADD -autosendcmd "/^msg nickserv ident password;wait -opn 2000" opn
 
+Then add some servers to different networks (ircnet is already set up 
+for them), irc.kpnqwest.fi is used by default for IRCNet but if it fails,
+irc.funet.fi is tried next:
   /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:
+Automatically join to channels after connected to server, send op request
-
+to bot after joined to efnet/#irssi:
   /CHANNEL ADD -auto #irssi ircnet
   /CHANNEL ADD -auto -bots *!*@bot@host.org -botcmd "/^msg $0 op pass"
 	       #irssi efnet
 
 
- --- Server and channel automation ---
+ 2. Basic user interface usage
+ -----------------------------
+
+By default, irssi uses "hidden windows" for everything. Hidden window is
+created every time you /JOIN a channel or /QUERY someone. There's several
+ways you can change between these windows:
+
+  ALT-1, ALT-2, ... ALT-0 - Jump directly between windows 1-10
+  ALT-q .. ALT-p          - Jump directly between windows 11-20
+  ESC-1 .. ESC-0          - ALT-keys don't work everywhere, but you can use
+                            ESC-key instead of ALT.
+  /WINDOW <number>        - Jump to any window with specified number
+  Ctrl-P, Ctrl-N          - Jump to previous / next window
+
+Clearly the easiest way is to use ALT-number keys. Some terminals just
+don't allow it, with xterm and rxvt you should be able to fix it with
+changing X resources:
+
+  XTerm*eightBitInput:   false
+  XTerm*metaSendsEscape: true
+
+And how exactly does it happen? For Debian, there's
+/etc/X11/Xresources/xterm file where you can put them and it's read
+automatically when X starts. ~/.Xresources file might also work. If you
+can't get anything else to work, just copy&paste those lines to
+~/.Xresources and directly call "xrdb -merge ~/.Xresources" in some
+xterm. The resources affect only the new xterms you start, not existing
+ones.
+
+Many windows SSH clients also don't allow usage of ALT. One excellent
+client that does allow is putty, you can download it from
+http://www.chiark.greenend.org.uk/~sgtatham/putty/.
+
+Irssi also supports split windows, they've had some problems in past
+but I think they should work pretty well now :) Here's some commands
+related to them:
+
+  /WINDOW NEW                    - Create new split window
+  /WINDOW NEW HIDE               - Create new hidden window
+  /WINDOW CLOSE                  - Close split or hidden window
+
+  /WINDOW HIDE [<number>|<name>] - Make the split window hidden window
+  /WINDOW SHOW <number>|<name>   - Make the hidden window a split window
+
+  /WINDOW SHRINK [<lines>]       - Shrink the split window
+  /WINDOW GROW [<lines>]         - Grow the split window
+  /WINDOW BALANCE                - Balance the sizes of all split windows
+
+By default, irssi uses "sticky windowing" for split windows. This means
+that windows created inside one split window cannot be moved to another
+split window without some effort. For example you could have following
+window layout:
+
+  Split window 1: win#1 - Status window, win#2 - Messages window
+  Split window 2: win#3 - ircnet/#channel1, win#4 - ircnet/#channel2
+  Split window 3: win#5 - efnet/#channel1, win#6 - efnet/#channel2
+
+When you are in win#1 and press ALT-6, irssi changes jumps to split
+window #3 and moves the efnet/#channel2 the active window.
+
+With non-sticky windowing the windows don't have any relationship with
+split windows, pressing ALT-6 in win#1 moves win#6 to split window 1
+and sets it active, except if win#6 was already visible in some other
+split window irssi just changes to that split window. This it the way
+windows work with ircii, if you prefer it you can set it with
+
+  /SET autostick_split_windows OFF
+
+Each window can have multiple channels, queries and other "window
+items" inside them. If you don't like windows at all, you disable
+automatic creating of them with
+
+  /SET autocreate_windows OFF
+
+If you want to group only some channels or queries in one window, use
+
+  /JOIN -window #channel
+  /QUERY -window nick
+
+
+ 3. 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 :)
+useful in some other ways too :) For information how to actually use
+irssi correctly with multiple servers see the chapter 6.
 
 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
@@ -54,16 +161,18 @@ 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
+  /SERVER ADD -auto -ircnet worknet irc.mycompany.com 6667 password
 
-The -auto option specifies that this server is connected at startup.
+The -auto option specifies that this server is automatically connected
-You don't need to make more than one server with -auto switch, other
+at startup. You don't need to make more than one server with -auto
-servers are automatically connected in same IRC network if the -auto
+option to one IRC network, other servers are automatically connected in
-server fails.
+same network if the -auto server fails.
 
 And finally channels:
 
   /CHANNEL ADD -auto -bots *!*@bot@host.org -botcmd "/^msg $0 op pass"
 	       #irssi efnet
+  /CHANNEL ADD -auto #secret ircnet password
 
 -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
@@ -74,40 +183,214 @@ 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.
+
+ 4. Setting up windows and automatically restoring them at startup
+ -----------------------------------------------------------------
+
+First connect to all the servers, join the channels and create the
+queries you want. If you want to move the windows or channels around
+use commands:
+
+  /WINDOW MOVE LEFT/RIGHT/number    - move window elsewhere
+  /WINDOW ITEM MOVE <number>|<name> - move channel/query to another window
+
+When everything looks the way you like, use /LAYOUT SAVE command (and
+/SAVE, if you don't have autosaving enabled) and when you start irssi
+next time, irssi remembers the positions of the channels, queries and
+everything. This "remembering" doesn't mean that simply using /LAYOUT
+SAVE would automatically make irssi reconnect to all servers and join
+all channels, you'll need the /SERVER ADD -auto and /CHANNEL ADD -auto
+commands to do that.
+
+If you want to change the layout, you just rearrange the layout like
+you want it and use /LAYOUT SAVE again. If you want to remove the
+layout for some reason, use /LAYOUT RESET.
 
 
- --- Placing the channels in the windows *I* want them to be in ---
+ 5. Status and msgs windows & message levels
+ -------------------------------------------
 
-First move the windows where you want them to be with /WINDOW MOVE
+By default, all the "extra messages" go to status window. This means
-LEFT/RIGHT/number commands. After that use /LAYOUT SAVE command and
+pretty much all messages that don't clearly belong to some channel or
-Irssi remembers the window positions the next time you start it.
+query. Some people like it, some don't. If you want to remove it, use
 
-This doesn't work very well with split windows currently.
+  /SET use_status_window OFF
+
+This doesn't have any effect until you restart irssi. If you want to
+remove it immediately, just /WINDOW CLOSE it.
+
+Another common window is "messages window", where all private messages
+go. By default it's disabled and query windows are created instead. To
+make all private messages go to msgs window, say:
+
+  /SET use_msgs_window ON
+  /SET autocreate_query_level DCCMSGS  (or if you don't want queries to
+                                        dcc chats either, say NONE)
+
+use_msgs_window either doesn't have any effect until restarting irssi.
+To create it immediately say:
+
+  /WINDOW NEW HIDE     - create the window
+  /WINDOW NAME (msgs)  - name it to "(msgs)"
+  /WINDOW LEVEL MSGS   - make all private messages go to this window
+  /WINDOW MOVE 1       - move it to first window
+
+Note that neither use_msgs_window nor use_status_window have any effect
+at all if /LAYOUT SAVE has been used.
+
+This brings us to message levels.. What are they? All messages that
+irssi prints have one or more "message levels". Most common are PUBLIC
+for public messages in channels, MSGS for private messages and CRAP for
+all sorts of messages with no real classification. You can get a whole
+list of levels with
+
+  /HELP levels
+
+Status window has message level "ALL -MSGS", meaning that all messages,
+except private messages, without more specific place go to status
+window. The -MSGS is there so it doesn't conflict with messages window.
 
 
- --- Jumping around in scrollback ---
+ 6. How support for multiple servers works in irssi
+ --------------------------------------------------
 
-Many clients have /LASTLOG command to find text from scrollback, but
+ircii and several other clients support multiple servers by placing the
-with no easy way to jump to the position in scrollback where the
+connection into some window. IRSSI DOES NOT. There is no required
-conversation was done in lastlog, except with keeping page up key down
+relationship between window and server. You can connect to 10 servers
-for a long time.
+and manage them all in just one window, or join channel in each one of
+them to one sigle window if you really want to. That being said, here's
+how you do connect to new server without closing the old connection:
 
-Irssi has /SCROLLBACK (or alias /SB) commands for jumping around in
+  /CONNECT irc.server.org
-scrollback buffer, the most useful one is /SB GOTO time. You do a
+
-"/LAST word", get list of lines where the word appeared with
+Instead of the /SERVER which disconnects the existing connection. To
-timestamps, then you use "/SB GOTO hh:mm" to jump to wanted position.
+see list of all active connections, use /SERVER without any parameters.
-"/SB END" jumps to end of scrollback buffer.
+You should see a list of something like:
+
+  -!- IRCNet: irc.telia.fi:6667 (IRCNet)
+  -!- OPN: tolkien.openprojects.net:6667 (OPN)
+  -!- RECON-1: 192.168.0.1:6667 () (02:59 left before reconnecting)
+
+Here you see that we're connected to IRCNet and OPN networks. The the
+IRCNet at the beginning is called the "server tag" while the (IRCnet)
+at the end shows the IRC network. Server tag specifies unique tag to
+refer to the server, usually it's the same as the IRC network. When
+the IRC network isn't known it's some part of the server name. When
+there's multiple connections to same IRC network or server, irssi adds
+a number after the tag so there could be ircnet, ircnet2, ircnet3 etc.
+
+Server tags beginning with RECON- mean server reconnections. Above we
+see that connection to server at 192.168.0.1 wasn't successful and
+irssi will try to connect it again in 3 minutes.
+
+To disconnect one of the servers, or to stop irssi from reconnecting,
+use
+
+  /DISCONNECT ircnet   - disconnect server with tag "ircnet"
+  /DISCONNECT recon-1  - stop trying to reconnect to RECON-1 server
+  /RMRECONNS           - stop all server reconnections
+
+  /RECONNECT recon-1   - immediately try reconnecting back to RECON-1
+  /RECONNECT ALL       - immediately try reconnecting back to all
+                         servers in reconnection queue
+
+Now that you're connected to all your servers, you'll have to know how
+to specify which one of them you want to use. One way is to have an
+empty window, like status or msgs window. In it, you can specify which
+server to set active with
+
+  /WINDOW SERVER tag    - set server "tag" active
+  Ctrl-X                - set the next server in list active
+
+When the server is active, you can use it normally. When there's
+multiple connected servers, irssi adds [servertag] prefix to all
+messages in non-channel/query messages so you'll know where it came
+from.
+
+Several commands also accept -servertag option to specify which server
+it should use:
+
+  /MSG -tag nick message
+  /JOIN -tag #channel
+  /QUERY -tag nick
+
+/MSG tab completion also automatically adds the -tag option when nick
+isn't in active server.
 
 
- --- Irssi's settings ---
+ 7. /LASTLOG and jumping around in scrollback
+ --------------------------------------------
+
+/LASTLOG command can be used for searching texts in scrollback buffer.
+Simplest usages are
+
+  /LASTLOG word     - print all lines with "word" in them
+  /LASTLOG word 10  - print last 10 occurances of "word"
+  /LASTLOG -topics  - print all topic changes
+
+If there's more lines to be printed than 1000, irssi doesn't thinks
+that you probably made some mistake and won't print them without -force
+option. If you want to save the full lastlog to file, use
+
+  /LASTLOG -file ~/irc.log
+
+With -file option you don't need -force even if there's more than 1000
+lines. /LASTLOG has a lot of other options too, see /HELP lastlog for
+details.
+
+Once you've found the lines you were interested in, you might want to
+check the discussion around them. Irssi has /SCROLLBACK (or alias /SB)
+command for jumping around in scrollback buffer. Since /LASTLOG prints
+the timestamp when the message was originally printed, you can use /SB
+GOTO hh:mm to jump directly there. To get back to the bottom of
+scrollback, use /SB END command.
+
+
+ 8. Logging
+ ----------
+
+Irssi can automatically log important messages when you're set away
+(/AWAY reason). When you set yourself unaway (/AWAY), the new messages
+in away log are printed to screen. You can configure it with:
+
+  /SET awaylog_level MSGS HILIGHT     - Specifies what messages to log
+  /SET awaylog_file ~/.irssi/away.log - Specifies the file to use
+
+Easiest way to start logging with Irssi is to use autologging. With it
+Irssi logs all channels and private messages to specified directory.
+You can turn it on with
+
+  /SET autolog ON
+
+By default it logs pretty much everything execept CTCPS or CRAP (/WHOIS
+requests, etc). You can specify the logging level yourself with
+
+  /SET autolog_level ALL -CRAP -CLIENTCRAP -CTCPS (this is the default)
+
+By default irssi logs to ~/irclogs/<servertag>/<target>.log. You can
+change this with
+
+  /SET autolog_path ~/irclogs/$tag/$0.log (this is the default)
+
+The path is automatically created if it doesn't exist. $0 specifies the
+target (channel/nick). You can make irssi automatically rotate the logs
+by adding date/time formats to the file name. The formats are in "man
+strftime" format. For example
+
+  /SET autolog_path = ~/irclogs/%Y/$tag/$0.%m-%d.log
+
+For logging only some specific channels or nicks, see /HELP log
+
+
+ 9. 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 ---
+ - Queries
 
 /SET autocreate_own_query ON - Should new query window be created when
 you send message to someone (with /msg).
@@ -123,7 +406,7 @@ closed and active window is neither never closed. The value is given in
 seconds.
 
 
- --- Windows ---
+ - Windows
 
 /SET use_msgs_window OFF - Create messages window at startup. All
 private messages go to this window. This only makes sense if you've
@@ -163,14 +446,14 @@ the latter way.
 each window.
 
 
- --- User information ---
+ - 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 ---
+ - Server information
 
 /SET skip_motd OFF - Should we hide server's MOTD (Message Of The Day).
 
@@ -184,7 +467,7 @@ before disconnecting and trying to reconnect. This happens mostly only
 when network breaks between you and IRC server.
 
 
- --- Appearance ---
+ - Appearance
 
 /SET timestamps ON - Show timestamps before each message.
 
@@ -221,38 +504,10 @@ format works for now.
 statusbar. Type "/SET statusbar" to see all the different settings.
 
 
- --- Nick completion ---
+ - 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.
-