README

   1 urk 0.-1.cvs
   2 http://urk.sourceforge.net/
   3
   4
   5 Overview:
   6
   7 urk is an IRC client written purely in python for linux/gnome. It has a powerful
   8 built-in scripting system (also python), which is used to implement much of the
   9 client.
  10
  11
  12 Requirements/User installation:
  13
  14 urk requires the following packages (and should run on any os that can provide
  15 them):
  16 -python version 2.4 or greater (www.python.org)
  17 -pygtk 2.6 or greater (www.pygtk.org)
  18
  19 Most Linux (or at least GNOME) users should have these things already or be able
  20 to easily install them.
  21
  22 Because urk is pure python, no compilation of urk is required. Just extract the
  23 source to somewhere and run 'python urk.py'.
  24
  25 Windows versions of the above should theoretically work but may not in practice.
  26 I am hoping someone will come along and actually support urk on windows.
  27
  28
  29 Optional requirements:
  30
  31 urk can also make use of these packages if you have them:
  32 -pygtksourceview, part of gnome-python-extras <=2.12 and gnome-python-desktop
  33  >=2.14, for source highlighting and undo in the internal script editor
  34 -python-dbus, for, well, not much (if dbus is available, urk only makes a single
  35  instance per session, and commands can be executed remotely by calling urk.py)
  36
  37
  38 Getting started:
  39
  40 Make sure you have all the requirements, go to the directory where you have
  41 extracted the source, and type 'python urk.py'.
  42
  43 We don't have any preferences windows yet. You can change your nickname by
  44 typing '/nick nickname' (replacing nickname with the nick you want to use)
  45 or typing a new nick in the nick field on the lower right corner and pressing
  46 enter.
  47
  48 To connect, type '/server irc.gamesurge.net' (replacing irc.gamesurge.net with
  49 the server you want to connect to).
  50
  51 If you want to connect to another server (without disconnecting the current
  52 one), use the -m switch as in '/server -m irc.gamesurge.net'.
  53
  54 To join a channel when you're connected to a server, type '/join #channelname',
  55 replacing #channelname with the channel you want to join.
  56
  57 urk currently only supports the bare minimum commands and features you should
  58 need to connect and chat normally. On channels, you can send messages by
  59 typing them (if you want to send a message that starts with a /, use /say to
  60 send your message). You can send actions to channels with /me and send messages
  61 to arbitrary targets with /msg. If urk does not recognize a command, it will
  62 send it to the server. This works to implement most commands you would expect
  63 on an irc client.
  64
  65
  66 Configuration:
  67
  68 Most configuration has to be done manually. If urk is running, you can configure
  69 it using commands. The settings are stored in urk.conf on your profile
  70 directory, which you can locate by typing '/pyeval urk.userpath' in urk.
  71
  72 To set a value in urk, type
  73
  74 /pyexec conf.conf['setting'] = value
  75
  76 To see the current value, type
  77
  78 /pyeval conf.conf['setting']
  79
  80 To unset a value (meaning urk will use the default), type
  81
  82 /pyexec del conf.conf['setting']
  83
  84 Setting:            Description:
  85
  86 'nick'                 The nickname urk should use. The default is to try to get
  87     it from the os. Put this in quotes when you set it.
  88
  89 'altnicks'             A list of alternative nicknames to use. The default is
  90     an empty list.
  91
  92 'quitmsg'              The message people see when you quit. The default is to
  93     advertise urk with your current version; we have to promote it somehow.
  94     This value needs to be in quotes.
  95
  96 'autoreconnect'        If True, urk will try to reconnect when you're
  97     disconnected from a network. Defaults to True. Set this to True or False.
  98
  99 'highlight_words'      A list of words, in addition to your nick, that cause a
 100     highlight event (normally the tab label turns blue and, if it's available,
 101     the tray icon shows up). For example: ['python', 'whale', 'peanut butter']
 102
 103 'log_dir'              The place where logs are written. The default is a
 104     directory called "logs" on your profile directory.
 105
 106 'ui-gtk/tab-pos'       The side of the window where the tabs will reside
 107     2 for top
 108     0 for left
 109     1 for right
 110     3 for bottom (default)
 111
 112 'ui-gtk/show-menubar'  If True, the menubar is shown. The default is True. Set
 113     this to True or False.
 114
 115 'command_prefix'       The prefix used to signal a command. Defaults to '/'
 116
 117 'font'                 The font used for output. Defaults to "sans 8".
 118
 119 'bg_color'             The background color ("black" or "#000000").
 120
 121 'fg_color'             The foreground color ("white" or "#ffffff").
 122
 123 'timestamp'            A timestamp that will show up before messages. The
 124     default is no timestamp. A simple timestamp with hours and minutes is
 125     "[%H:%M] ". See http://docs.python.org/lib/module-time.html#l2h-1955 for
 126     a key to format this string.
 127
 128 'start-console'        If True, urk will start up with a special console window
 129     that shows debugging output (normally sent to a terminal) and accepts
 130     python expressions. Defaults to False.
 131
 132 'status'               If True, urk will be in status window mode. Each network
 133     will ALWAYS have a status window. When not in status window mode, networks
 134     only have a status window when there are no channel windows. Defaults to
 135     False.
 136
 137 'open-file-command'    The command used to open files and url's with your
 138     preferred application (such as "gnome-open"). This is ignored on Windows,
 139     and you should never need to mess with this, ever.
 140
 141
 142 System-wide installation:
 143
 144 Not yet implemented.
 145
 146
 147 About scripting:
 148
 149 urk scripts are python source files that contain definitions of functions with
 150 certain "magic" names, like onText (for when someone sends a channel or private
 151 message). See www.python.org for help on writing python code. The format for
 152 onText is:
 153
 154 def onText(e):
 155     code
 156
 157 e is an object used to pass on the various information relating to the event
 158 that triggered the function. The name is a convention we use, much like self.
 159
 160 e.source is the nickname of the person who sent the message.
 161
 162 e.target is the nickname or channel that received the message.
 163
 164 e.text is the text of the message.
 165
 166 e.network is an object representing the network where the message was sent.
 167
 168 e.window is a window that seems to be related to the event for some unspecified
 169 reason. It could be the status window, a channel window, a query, anything.
 170
 171 Complete documentation doesn't exist yet. Sorry. Ask us or look at the source. theme.py is good for finding event names.
 172
 173
 174 Bugs/Feedback:
 175
 176 Naturally, feedback of any sort is welcome. Of course we want to know about
 177 bugs. In particular, we'd also like to hear about any features you want or
 178 expect in an irc client that urk doesn't have. While we'd like to limit the
 179 things that go in the default client (a notify list, for example, is something
 180 we'd want to see as an external script, not as part of the default setup, and
 181 something we're not likely to implement soon), there are probably a lot of
 182 little things that we may have skipped over because we don't use them or have
 183 become used to urk not having them.
 184
 185 The best way to get in touch with us is by irc, at #urk on irc.gamesurge.net.
 186 Or send a message to the mailing list, urk-discussion@lists.sourceforge.net.