BitchX Tutorial

version 0.2

This document has been discontinued

1. Contents

1. Contents
2. About this document
2.1 What's it about?
2.2 What it's not about
3. About BitchX
3.1 What is BitchX
3.2 Obtaining BitchX
3.3 More documentation on BitchX
4. Chatting
4.1 Connecting to a server
4.2 Chatting on a channel (public)
4.2.1 Joining the channel
4.2.2 Leaving the channel
4.3 Chatting on multiple channels (public)
4.4 Chatting to a user (private)
4.5 Protecting yourself
4.6 Quiting BitchX
4.7 Other chatting thingies
5. Windows
5.1 Creating a new window
5.2 Changing windows
5.3 Using a window
5.3.1 Channel (public)
5.3.2 User (private)
5.3.3 Multiple servers
5.4 Settings a window's level
5.5 Removing a window
5.6 Other window options
5.7 Usefull aliases
6. Customizing BitchX
6.1 Aliases
6.2 Keybindings
6.2.1 Keys
6.2.2 Functions
6.3 Settings
6.4 Changing formats
6.4.1 About formats
6.4.2 Formats
6.4.3 Timestamps
6.4.4 Colors
6.5 Misc settings
7. Operator options
7.1 Setting channel modes
7.2 Protecting your channel
7.2.1 Kicking users
7.2.2 Banning users
7.2.3 Modes for channel protection
7.3 Automatically protecting other users
8. References
9. Document information
9.1 History
9.2 To Do
9.3 Contributing
10. Copyright

2. About this document.

2.1 What's it about?

BitchX can be a real Bitch to work with. The documentation is poorly written, or so it seams if you do not know where to look for the right documentation. It the interface can be complicated and do one thing at one time and another the next day. Due to my dissatisfaction with current documentations, I decided to write up this small document in the hope of providing some usefull information to the newbie bitchx users out there. But even if you've been using BitchX for quite some time, you might still find this document usefull.

2.2 What it's not about.

Please note that this is not an installation guide to BitchX, and neither is it a tutorial for IRC. A working BitchX client and some knowledge about what IRC is, and how it generally works is needed in order to understand this document. This document is about BitchX, the commandline client. It's not about the Gtk version of BitchX, though most (if not all) features discussed here, will probably also work with gtk-bitchx.

3. About BitchX.

3.1 What is BitchX

BitchX is based on another very popular IRC client, named IrcII, one of the first irc clients. Since ircII is open source software, they were able to take it's sourcecode, and simply extend it with various elements. BitchX is sometimes known as the 'hackers irc client', mainly because of it's advanced IRC features/hacks and because of it's cryptic interface.

3.2 Obtaining BitchX

3.3 More documentation on BitchX

Because most of BitchX's code base lies in ircII, most of ircII's documentation can also be applied on BitchX. Knowing this will put you one step further into getting to know BitchX. Many documents and tutorials can be found on the internet about ircII, as well as the documents distributed with ircII. At the end of this document, I have put a couple of links which refer to more documentation about ircII and BitchX in the hope that you may use them to extend your knowledge about BitchX.

4. Chatting.

First of all, I'll teach you some basic IRC-ing features of BitchX.

4.1 Connecting to a server

Connecting to an IRC server is easy. In this example, we'll connect to the irc.nl.uu.net server (IRCNet) with the username toDDie:

[todsah@sharky]~$ bitchx toDDie irc.nl.uu.net

You'll now see bitchx being started, and connecting to the specified server, namely irc.nl.uu.net:

-:- Connecting to port 6667 of server irc.nl.uu.net [refnum 0]

After a while, the client will connect to the server, and some information will fly over the screen. Some modes will be changed, and the client will then wait for input from the user (that's you). In some cases, it will take extremely long before bitchx can connect to the server. Waiting for about 10 to 20 seconds is not unusual in these cases. If this also happens to you, your ident may be the problem. When connecting to an IRC server, the server requests your ident. For this to work, the machine you are connecting from (please note that this is the machine through which you connect to the internet, and may not be the machine you are running bitchx from. It might also be your networks gateway) must run an ident server. You can check if it is running this by either running the following command on the commandline :

[todsah@sharky]~$ ps ax | grep identd

When you don't see a line like this:

   283 ?     S     0:01 identd

something is wrong, and you should start/fix your identd server. Identd seems to have some difficulties when running from inetd (the internet super server). This was at least the case with my Debian GNU/Linux v2.2 machine. The fix was to not start identd from inetd, but as a normal daemon.

4.2 Chatting on a channel (public)

In order to start chatting, you will either need to join a channel, or know some usernames. To find out what channels are on the current IRC server, just type the IRC command:

/list

The bitchx client will now tell you that this is not a good idea, and that you should add -YES to the command of you really want to run this command. BitchX isn't kidding when it said this wasn't a good idea. Why? Because most public IRC servers have so many channels, that it'll take forever to list them all. Neither you, nor the IRC server you are connected to will like it if you do this. You might even be disconnected.

It's easier to just ask somebody who's already on IRC on which channel they reside, and join that channel. For instance: #toktok.

4.2.1 Joining the channel

/j #toktok

BitchX will join the channel, and show you some information about the channel:

	-:- Topic (#toktok): Welcome to #toktok.
	-:- [Users(#toktok:10)] 
	[ toDDie    ] [ BirdSgool ] [@Crasp     ] [@toDSaH    ] [ DoingK|Na ] 
	[ AczWeg    ] [ Zew[AWAY] ] [ Fluxi     ] [ tribbel   ] [@Ztn-na    ]
	-:- BitchX: Join to #toktok was synched in 5.656 secs!!
	

Each channel can have a topic. In order to set the topic, you can use the /topic command:

[#toktok] /topic Hey, I'm the new guy! Grtz, toDDie.

Some channels will not allow you to change the topic. In this case the channel operators (the people with an @ infront of their name) have set the mode of the channel '-t', which means that only other operators may change the topic.

When joining the channel, bitchx will automatically show you the number of users currently on the channel, and a list of their nicknames. You can get this list yourself at anytime (as long as you are on the channel) by typing:

/scan

A more extensive list can be retrieved by typing:

/who

This will also show the users mode, hostname and realname. Yet another method is pressing F2 and F3. F2 shows which operators are on the channel, and F3 shows which non-operators are on the channel.

If you want to say something to the channel, just type it at the prompt. The text you typed will then appear on the channel, for everybody on the channel to see. If you want to see something on the channel to which you say to someone specific, it's general to type in their nickname, followed by a colon (':"), or a comma (','):

[#toktok] Zetion: Hey, how are you doing?

The receiving user (in this case user 'Zetion') will see his nickname highlighted in this sentence. BitchX has tab-completion, which means that you only have to enter part of the name, i.e 'Ze' and then can press the tab key, and bitchx will complete the name from 'Ze' to 'Zetion' if possible. If you're on a slow channel, and your already talking to a specific user, and he's talking to you, this isn't neccesary. Just use your common sence. If the user will know you're talkin to him/her, there's no need to prefix your sentence with their nickname. (Also see the Netiquette chapter somewhere else in this document)

If you want to express somehthing, you can use the /me command (talk in the third person about yourself):

[#toktok] /me doesn't like it here

This will be shown on the channel as:

* toDSaH doesn't like it here

4.2.2 Leaving the channel

If you get tired of the channel, you can leave it by typing:

[#toktok] /part #toktok

or:

[#toktok] /part #toktok I'm tired of you people

In which case the users which remain on the channel will see something like:

-:- toDDie has left #toktok: I'm tired of you people

4.3 Chatting on multiple channels (public)

Most users don't just wanna chat on one channel, but on several channels at the same time. This is possible in bitchx. There are multiple ways in which you can do this. If you want to join, for example, channels #channel1 and #channel2, you can simply type:

[0] /j #channel1
	[#channel1] /j #channel2

You can now talk on both channel1 and channel2. Things said on the channel will appear on the same screen, pre- or appended with the channel it was said on. You can tell to which channel things you type will be sent by looking at the name of the channel in front of the prompt ( [#channel1] ). You can change channels by pressing Ctrl-x.

This method can be quite confusing. When somebody says something on #channel1, it's not uncommon to make the mistake of replying on #channel2. You'll probably get used to it, but there are better ways of doing it. To do it better, you'll have to read the Windows section elsewhere in this document.

4.4 Chatting to a user (private)

The time will come at which you will want to gossip about a user, but that user just happens to be on the channel you're on too. In this case you can send a user a private message, which only they will see. To do this, you use the /msg command. Just type:

[#channel1] /msg joe Hey joe, I think John is such a loser, don't you?

Only user 'joe' will see this message

Tab completion also works in this case. When typing '/msg jo', followed by the tab key, the name will be completed. But be carefull, because user 'joe' starts with 'jo', but user 'john' does too! It's only a guess to which username bitchx will complete the 'jo' part. It might very well complete it to 'john'. Upon recieving a private message from someone, it's possible to simply press the 'tab' key right away, and bitchx will automatically generate a command to send a private message to the last person from whom you recieved a private message.

Hitting tab can become teadeous after a while. If you're planning long private conversations with someone, you might want to use the /query command. The /query command allows you to talk privately to a user like you would publically to a channel. When used like this:

[#toktok] /query Zetion

[#toktok] /msg #toktok Hey new guy. Wait a minute okay? I'm talking to zetion right now

4.5 Protecting yourself

Just as in real life, IRC also has irritating persons whom like to annoy you, send you virusses and stalk you. BitchX has some built in protection agianst such activities.

ctcp cloacking: If you press the 'del' key, you'll turn on (or off) ctcp cloacking. This will prevent other users from getting extended information about i.e your bitchx version and stuff.

4.6 Quiting BitchX

When you've had it with IRCing, you can quit the client by using the /quit command. This will also quit any channels you were on at the time.

[#toktok] /quit I'm off again.

This will make you leave all channels you were on with the quit message "I'm off again.", and quit the bitchX client. Sometimes you'll not be able to type anything at the commandprompt, because i.e you are connecting to an IRC server. At this moment BitchX will not seem to respond to what you type. If you still wish to quit BitchX at this moment, you can type 'Ctrl-c' 5 times. You're quit message will be 'User aborted with 5 Ctrl-c's'.

4.7 Other chatting thingies

5. Windows

BitchX supports (just like ircII does) chatting in multiple windows. Do mind, that a 'window' is nota window as you probably know it. If you are using a terminal emulator under i.e the X windowing System, a 'window' does not mean a new terminal emulator window will be brougt up. BitchX windows all remain in the same X window.

Using BitchX windows can be used quite nicely to keep your chatting sessions clean. I.e. you can chat on different channels in different windows.

5.1 Creating a new window

To create a new BitchX window, you generally type:

[#channel1] /window new double on hide

All windowing commands start with /window. 'new' means a new window will be created. 'double on' means that the command prompt will be the same as the first window (a 2 lined command prompt which shows information about you and the current channel). 'hide' means the new window should be fullscreen (according to the size of the terminal emulator window of working under X) and should not be visible immediately. If you do not specify 'hide', the current screen will be split, and the new 'window' will be on the same screen as the current one. You can create as many new windows as you'd like. (*** FIXME:might be limited to about 10??)

5.2 Changing windows

Now that you've created a new window, you'd like to change to that window , so that you may use it. For this there are also a number of ways to do it. There are many ways of doing many thing in BitchX, aren't there?).

• /window next (/window prev)
• Pressing Ctrl-w n
• Pressing Alt-# (Where # is the corrisponding window number, i.e alt-1, alt-2, etc)

5.3 Using a window

When changed to the new window, you can use it like you would normally. Just type in commands at the command prompt, and the'll be run in the current window (most of the time, anyway).

5.3.1 Channel (public)

Typing /j #foobar joins #foobar. Consequentely, typing something will appear on #foobar. Changing back the previous window (/window prev, or ctrl-w p, or alt-1) allows you to talk to the channel which you joined in that window.

5.3.2 User (private)

If you want to talk to a user privately in the new window, just use the /query command. Remember, you don't have to be on the same channel as the user you want to chat privately with.

5.3.3 Multiple servers

It may sometimes be desirable to chat on different IRC networks (or differenent IRC servers, it's all the same). In this case, BitchX allows you to connect to a different IRC server in the new window. This won't work with the normal /server command, but you'll have to tell bitchx to only connect to the other server in the current window. You can do it like this:

[0] /window server irc.nl.undernet.org

This will connect you to the Undernet IRC network, but only in the current channel. Do be aware that it can sometimes become a bit messy when using multiple servers. Especially when you create new windows when you're already connected to two different servers.

If you want to quit the chatting on a specific server, you can switch to that server's window, and type /window discon. You will now be disconnected from the current server.

5.4 Setting a window's level

You can tell BitchX what information you want in a window, by adjusting it's level. When BitchX recieves information (i.e: a private message from another user) it will (by default) display it in the current window. All messages recieved from the IRC server (like splits and the like) are by default displayed in the current window. This can be anoyying, because it will generate a lot of random crap in between the normal channel flow. (this is especially the case when you're IRCing in Undernet, which generated enormous amounts of server messages)

If you only want to have all things said to #channel1 in the window for #channel1, you can use the '/window level' command:

[#channel1] /window level public

This will only allow public messages in the current window. Do note, that if another window is not present with a level which will allow other messages (like server message) the messages will still be shown in the current window. A list of available levels:

Please note that (like so many things in BitchX) window levels are not consistent or logical. When, for instance, setting window #1's level to ALL (which includes CRAP), and window #2's level to just PUBLIC, CRAP will still appear on window #2. This I call 'The BitchX uncertainty principle': Your milage may vary.

5.5 Removing a window

To remove a window, you can do the following:

• /window kill
• (ctrl-w k)

Mind you, that you will not quit any channels you were on in that window. You can still send messages to the channels you were on in the window, by using the '/msg' command or sometimes by changing to the channel with ctrl-x . With Ctrl-x, you're millage may vary though. BitchX is quite random with this.

5.6 Other window options

To get a list of things you can do with windows, type:

[#channel2] /window help

I'll cover a couple of neat options:

• /window hide (ctrl-w h) Hides the current window (in split screen)
• /window list (ctrl-w l) Lists all windows with their channels and more info

5.7 Usefull aliases

I myself use some aliases quite frequently, because I'm just too lazy to type '/window new double on hide' everytime. With the following alias, you can simply type '/wnq joe' to start a new query with user 'joe' in a new hidden window:

/alias wnq window new double on;query $0;window hide

(for a detailed description of the /alias command, see the 'Customizing BitchX' chapter)

6. Customizing BitchX

On of BitchX's strongest features is it's custumizability. Almost everything shown can be adapted to your liking. The interface can be changed and adapted to how you want it to work and look. Scripting commands can be used to make a 'link' between the system you're working on and the BitchX client. Speed up your daily chatting with aliases and keybindings and more.

6.1 Aliases

An alias is a kind of macro. It replaces another command (or set of commands) and it's (their) parameter(s) with a single command. This will greatly improve the usage of bitchx, because some commands can be quite tedious to type everytime (see the Windows chapter). New aliases can be created by using the /alias command. To get a list of current aliases which have been defined type:

	[#toktok] /alias
	WNQ     window new double on;query $0;window hide
	

This shows one alias, named WNQ. It runs three commands: 'window', 'query' and the 'window' command again. This alias takes 1 argument ($0) and creates a new window with the nickname, (or channel, or whatever) given as the paramter to WNQ, in a query. It then hides the window.

Aliases are not case sensetive. So you may say both /wnq joe, or /WNQ joe . Multple commands in aliases must be seperated by a ';'. Do mind that you may not have a space in front or after that ';'. Parameters are passed as $0, $1 .. $9. $* contains all parameters which where passed to the alias. Aliases are entered as follows: /alias [name] [command];[command] To remove an alias, you can prepend it's name with a '-' (hyphen). So:

[#toktok] /alias -wnq

Will remove the wnq alias.

6.2 Keybindings

Keybindings give you the ability to change the default keys used in bitchx for editing, changing windows, scrolling, etc. These keybindings are controlled via the /bind command. If /bind is run without any parameters, a list with current keybindings will be shown. To add new keybindings (or change existing ones, use the following command: /bind <key> <function> [<string>]

6.2.1 Keys

Allowed key sequences (taken directly from the ircII manual):

6.2.2 Functions

Allowed functions which can be binded on keys (taken directly from the ircII manual):

6.3 Settings

Possible settings:

6.4 Changing formats

6.4.1 About formats

BitchX's look can be changed by altering something called Formats. The client keeps a table of how things should look like. These formats can be changed by using /fset. You can change anything from how the status bar looks like to how messages are displayed. I.e: when something is said on the channel, bitchx internally takes this as a couple of fields, namely the time it was said, the nickname of who said it and the hostname of who said it. The rest is everything that was said. These fields can be used in the formats as a sort of parameters. $0 is the always the time, the other parameters differ. So, when something is said, BitchX takes (in this case) the format_public format, reads it, substitutes all parameters found in the format with the internal fields, renders the colors and then displays it. So if user 'Flunk' said 'Hey man!' at 10:40, and format_public is: [$0|$1> $3-, this will be displayed as: [10:40|Flunk> Hey man!. When a '-' is appended to a parameter, this means 'this parameter and all that follows'. 'Hey man!' would be broken up in $3 ('Hey') and $4 ('man!'), but $3- would become 'Hey man'. Colors can be inserted in the formats by using the '%' in formats. I.e: %B$0%n$1 would show the time in blue and the nickname in the normal color. More about colors in the Color section of this chapter.

6.4.2 Formats

The following formats are available in bitchx:

6.4.3 Timestamps

Adding timestamps can be done in two ways. You can either set the TIMESTAMP option to 'ON', which will give you some limited timestamps. For instance, public messages will be timestamped, but things you say yourself won't. The other method is defining all timestamps yourself by using the BitchX formats settings. This will allow you to add timestamps to just about everything. But it can be tidious work finding out all the different formats for messages and the likes. Therefor I've included here my own formats for timestamping (and some more stuff):

	/fset public %B[%n$0%B|%n$1%B>%n $3-
	/fset send_public %P[%n$0%P|%n$2%P>%n $3-
	/fset msg %B[%n$0%B|%G$1%B<%n $3-
	/fset send_msg %P[%n$0%P|%n%R$1%P> %n$3-
	/fset public_ar %B[%n$0%B|%Y$1%B>%n $3-
	/fset action %B[%n$0%B|%W$1%n $4-
	/fset action_ar %B[%n$0%B|%W$1%n $4-
	/fset action_channel %B[%n$0%B|%W$1/$3%n $4-
	/fset send_action %B[%n$0%B|%W$1%n $3-
	/fset send_action_other %B[%n$0%B|%W$2%n->%W$1%n $3-

	/fset channel_signoff %G[%n$0%G|%n$1%n%G|%n%CQUIT%n%G|%n$3%G>%n $4-
	/fset join %G[%n$0%G|%n$1%n%G|%n%CJOIN%n%G|%n$3%G>%n
	/fset leave %G[%n$0%G|%n$1%n%G|%n%CPART%n%G|%n$3%G>%n $4-
	/fset nickname %G[%n$0%G|%n$1%n%G|%n%CNICK%n%G>%n $3
	/fset nickname_other %G[%n$0%G|%n$1%n%G|%n%CNICK%n%G>%n $3
	/fset nickname_user %G[%n$0%G|%n$1%n%G|%n%CNICK%n%G>%n $3
	

Above format settings will add timestamps to public messages, private messages (by others and by yourself), channel joins, parts, quits, actions (/me's by you and by others). It will change the display of private messages too. While normally you would see something like:

	[toDS-na(todsah@d44200.upc-d.chello.nl)] Hello there
	[msg(toDS-na)] Hello to you to! 
	

you will now see the following (where red is what you said to toddie, and green is what toddie said to you):

	[14:23|toddie> Hello there
	[14:24|toddie< Hello to you to!
	

6.4.4 Colors

6.5 Misc settings

9. Document information

9.1 History

v0.2

• Changed font sizes for main text and code examples
• Fixed a non ending code example which made everyhing below it a code example
• Added notices that this document has been discontinued by the original author.

9.2 To Do

To Do's on this document are spread throughout this document in the form of '*** TODO DESCRIPTION'. At these places informations needs to be added, changed or whatever else is stated in the description. Global ToDo's are stated here:

• BitchX and Screen.
• CTCP information.
• Bot mode.
• Scripting.
• Netiquette.
• DCC information.
• Bouncers.
• References (irc help, other clients, etc).
• Colorify bitchx output lines.

The reason this document has been discontinued is very simple. BitchX doesn't cut it for me anymore, and I therefor do not feel the need to complete this document. Instead, I've switched do another, much better (IMHO, IMHO) irc client, namely Irssi

9.3 Contributing

If you feel like helping out finishing this document, making it the most complete guide to BitchX, your help is greatly appreciated. Things which you can help out with are i.e: removing spelling errors, finishing to do's, writing new sections, make suggestions, etc, etc, etc. All help, I repeat ALL HELP is more than welcome.

When contributing, please mention on which version of this document you made the changes. You may send any contributions to the email address in the copyright section.

10. Copyright

copyright (c) 2000, ferry boender

this document may be freely distributed, in part or as a whole, on any medium, without the prior authorization of the author, provided that this copyright notice remains intact, and there will be no obstruction as to the further distribution of this document. you may not ask a fee for the contents of this document, though a fee to compensate for the distribution of this document is permitted.

modifications to this document are permitted, provided that the modified document is distributed under the same license as the original document and no copyright notices are removed from this document. all contents written by an author stays copyrighted by that author.

failure to comply to one or all of the terms of this license automatically revokes your rights granted by this license

all brand and product names mentioned in this document are trademarks or registered trademarks of their respective holders.

Author:

Ferry Boender
De Cotelaer 28
3772 BP
Barneveld,
The Netherlands
EMail: f (DOT) boender (AT) electricmonk (DOT) nl