232 lines
17 KiB
HTML
232 lines
17 KiB
HTML
<html>
|
|
|
|
|
|
<head>
|
|
<title>The Renga User Guide</title>
|
|
</head>
|
|
|
|
<body BGCOLOR=FFFFFF>
|
|
|
|
<a NAME="top">
|
|
|
|
<p ALIGN=CENTER><center><img SRC="rapture-title.gif"></center><br>
|
|
<font FACE="Courier New"><b><u><h1 ALIGN=CENTER>Welcome to Renga!</h1></u></b></font>
|
|
<p>XMPP is an open chat protocol that allows users to communicate
|
|
with each other much like <a HREF="http://www.aol.com">AOL Instant Messenger</a> and <a HREF="http://www.mirabilis.com">ICQ</a>.
|
|
|
|
<p>Renga is the client that allows XMPP to be used on Haiku. This user guide describes how to use the client as well as the XMPP chat system. Here's what we'll be covering:
|
|
<ol>
|
|
<li><a HREF="#getting">Getting Started on XMPP</a>
|
|
<li><a HREF="#logging">Logging In</a>
|
|
<li><a HREF="#im">I'm Logged In...So Now What?!</a>
|
|
<li><a HREF="#chatfeatures">Chat Features</a>
|
|
<li><a HREF="#groupchat">Group Chat</a>
|
|
<li><a HREF="#prefs">The Preferences Panel</a>
|
|
<li><a HREF="#further">Further Exploration</a>
|
|
<li><a HREF="#cause">The Rapture In Venice Cause</a>
|
|
</ol>
|
|
|
|
<a NAME="getting">
|
|
<font FACE="Courier New"><b><u><h1 ALIGN=CENTER>Getting Started on XMPP</h1></u></b></font>
|
|
<center><font SIZE=-2><a HREF="#top">top</a></font></center>
|
|
|
|
<p>Renga is a Haiku-native client. It is based on Jabber4BeOS originally developed by <a HREF="http://www.users.uswest.net/~jblanco">Rapture In Venice</a>.
|
|
Renga delivers the
|
|
friendly user experience that many XMPP clients do not, much in the style of <a HREF="http://www.jabber.com">JabberIM</a>.
|
|
Renga intends to be simple to use, with recycled GUI metaphors that make
|
|
using this client as natural as any other you're used to.
|
|
|
|
As such, let's look at Renga!
|
|
|
|
<a NAME="logging">
|
|
<h1 ALIGN=CENTER>Logging In</h1>
|
|
<a href="#top">top</a>
|
|
|
|
<p>When you first run Renga, you will be presented with a window like this:</p>
|
|
|
|
<div ALIGN=CENTER><img SRC="login-pane.png"></div>
|
|
|
|
<p>If you've used XMPP in the past then this should look familiar to you. Just
|
|
enter the login information you've always used. If you haven't seen the nickname field
|
|
before, this is used as a friendly name only for yourself in chat windows. Nobody else will see this
|
|
information so it's not critical. As an expert, you'll probably want to check the Auto-login box as well.</p>
|
|
|
|
<p>If you're new to XMPP, you need to create an account. This is an important step in getting online.
|
|
You'll want to decide on your official username! Here is what all the fields mean:</p>
|
|
|
|
<ul>
|
|
<li><b>Nickname:</b> This is a friendly name for yourself. Other people will see it, and you can change it each time you connect.</li>
|
|
<li><b>Username:</b> This is the username you will be officially referred to with. You cannot change this once you picked one.</li>
|
|
<li><b>Password:</b> Your password.</li>
|
|
<li><b>Auto-login:</b> This is a handy option if you just want Renga to log you in with your
|
|
last entered username/password automatically. It's quicker than entering in your
|
|
information all the time, but also less secure. If you're on a single-user machine, this
|
|
is a recommended option.</li>
|
|
</ul>
|
|
|
|
<p>To create your account, use the "Create an account" button and follow the instructions. You will
|
|
need to pick a server to host your account, or you can let Renga select one for you.</p>
|
|
|
|
<p>There are also some rules you should know about how Auto-login works in specific situations. Here they are:</p>
|
|
|
|
<ul>
|
|
<li><b>Normal login:</b> In the "normal" situation, running Renga will cause the login process to initiate for the last username/password you tried logging in with.</li>
|
|
<li><b>Failed login:</b> If Auto-login fails to log you in because your last username/password is, or is no longer, valid then the login screen will appear and allow you to correct any mistakes.</li>
|
|
<li><b>Multiple logins:</b> If you already have another instance of Renga running on the machine, Auto-login will not run for that second instance. Having two copies of the application running for the same account on the same machine would just be confusing.</li>
|
|
<li><b>Change login:</b> If you use Auto-login, but you want to change your username and log in under another address (stalkers again?), simply logout by selecting "Log Off" from the File menu. </li>
|
|
</ul>
|
|
|
|
<a NAME="im">
|
|
<font FACE="Courier New"><b><u><h1 ALIGN=CENTER>I'm Logged In...So Now What?!</h1></u></b></font>
|
|
<center><font SIZE=-2><a HREF="#top">top</a></font></center>
|
|
|
|
<p>Congratulations, you're logged in! Your login window has now transformed and looks like:
|
|
|
|
<p ALIGN=CENTER><img SRC="logged-in-with-friends.png"></p>
|
|
|
|
<p>On the left is your buddy list, or "roster" as the XMPP group likes to call it. This is where you'll see your friends and family, their online status and more. If you just created your account, it will appear empty. So let's fill it up!
|
|
|
|
<p>There are two basic concepts when dealing with this list: <i>roster</i> and <i>presence</i>. While many external chat systems
|
|
treat these concepts as one entity, XMPP keeps them separate. What you need to rememeber is that even if you add a friend to your list (<i>roster</i>), you don't automatically begin seeing their online status (<i>presence</i>). You need to ask for it.
|
|
Let's illustrate this with an example.
|
|
|
|
<p>Let's say you wish to add Rapture In Venice to your buddy list. Don't worry, it's OK, I like to chat. :-) The first thing you want to do is go to your Edit menu and select "Add New Buddy."
|
|
You will see a screen like this:
|
|
|
|
<p ALIGN=CENTER><img SRC="buddy-window.png">
|
|
|
|
<p>The two important fields at this time are <b>Nickname</b> and <b>Jabber ID</b>. The username is the Jabber ID of the user you want to add. Mine is <i>rapture@jabber.org</i>, so type that one in.
|
|
Next, you want to add a nickname, a casual name that tends to be less cryptic then the username. This is up to you, so you can feel free to type in whatever information you'd like that will help you remember who this new buddy really is. The usual value for me would be <a HREF="http://www.users.uswest.net/~jblanco">"Rapture In Venice"</a>. Remember, it's totally up to you.
|
|
|
|
<p> Hit "Add My Buddy".
|
|
|
|
<p>If everything worked well, you should now see your new entry under the Unknown list. It should be blue. If you see it there, congratulations! I am now your buddy. :-) I am now on your <i>roster</i>. But what good is a buddy when you don't know when they're online? This is the concept of <i>presence</i>.
|
|
|
|
<p>So you want to know when I'm online, right? OK. Right-click on my name in the list and in the Presence sub-menu select "Subscribe." You've just sent a request to me asking for my presence. What I will see in a moment is your request and I can either accept or decline. Remember this screen because you might be seeing it again very shortly:
|
|
|
|
<p ALIGN=CENTER><img SRC="presence-window.png">
|
|
|
|
<p>If you don't get acceptance right away, don't worry. It could be that the user (possibly me, as in this case) is not online. If at some point the presence is accepted, you will be alerted so no need to stress!
|
|
If you've gotten acceptance, you've probably already noticed that the user is now either in the online or offline list and their color is green (dark or light) or red. Bet you can't guess what this means? ;-)
|
|
Right! The greens are for online, red is for offline. The <b><font COLOR=005500>darker shade of green</font></b> means the user is online, but is either away from their computer or does not want to be distrubed. <b><font COLOR=00CC00>The lighter shade of green</font></b> signifies their open for chat. Usually, after being granted presence, the user is online because, well, how else could they have accepted your presence?
|
|
|
|
<p>Great! So the user is online. Now what? You want to chat is what! Isn't that why you downloaded this program? :-)</p>
|
|
|
|
<p>The chatting happens on the right part of the main window. At the bottom is a text input where you can send your messages. Above that is a list of previous messages for the current conversation. To chat with different people, simple select them on the left panel.</p>
|
|
|
|
<p>If you want to send a long message with multiple lines, remember to use <b>Command-Enter</b> to insert a newline (since pressing <b>Enter</b> will send the current message to the other user). If you are not happy with that, you can exchange the two in the preferences window.</p>
|
|
|
|
<a NAME="chatfeatures">
|
|
<font FACE="Courier New"><b><u><h1 ALIGN=CENTER>Chat Features</h1></u></b></font>
|
|
<center><font SIZE=-2><a HREF="#top">top</a></font></center>
|
|
|
|
<p>Renga supports what's known as <i>"/me syntax"</i>. This is when you want to type a message but want to make it as part of an action. It's almost always used for humorous purposes. Here's an example:
|
|
|
|
<p ALIGN=CENTER><img SRC="me-syntax.png"><br><font SIZE=-2>- Note how /me makes my message an action -</font>
|
|
|
|
<p>To deliver this kind of message, use this syntax:
|
|
|
|
<ul><tt>/me <i>your action</i></tt></ul>
|
|
|
|
<p>Here's exactly how I generated the previous example:
|
|
|
|
<ul><tt>/me does a barrel roll</tt></ul>
|
|
|
|
<p>A feature that is new with Jabber for <font COLOR=RED>B</font><font COLOR=BLUE>e</font>OS v1.2 is chat history. In any chat window, hold down the Command key and use the up and down arrows to scroll through the history of your last 50 messages. This is handy when your buddy misses a message or you just want to accentuate it! ;-)
|
|
|
|
<a NAME="groupchat">
|
|
<font FACE="Courier New"><b><u><h1 ALIGN=CENTER>Group Chat</h1></u></b></font>
|
|
<center><font SIZE=-2><a HREF="#top">top</a></font></center>
|
|
|
|
<p>In addition to one on one chat, Renga also support group chat. This is when more than two people can chat in the same window at the same time. The advantages are clear:
|
|
|
|
<ul>
|
|
<li><b>Group Meeting Place</b> - If you're on a development team or chatting with the rest of the UnReal club, group chat is a great place to get together!
|
|
<li><b>Privacy</b> - While <a HREF="http://www.lcscanada.com/beshare/index.html">BeShare</a> provides a great way to get together with other <font COLOR=RED>B</font><font COLOR=BLUE>e</font> community members, XMPP group chat lets you create your own rooms without being restricted to the one monolithic room that the server supports.
|
|
<li><b>Well Known Rooms</b> - XMPP houses some well known rooms, or rooms that people know about and attend. The most popular is the group chat that the XMPP server developers partake in (see more info below).
|
|
<li><b>Channels</b> - To help organize some nice <font COLOR=RED>B</font><font COLOR=BLUE>e</font> community rooms, check the Channels menu for rooms such as "<font COLOR=RED>B</font><font COLOR=BLUE>e</font> Developers" and <i>"Jabber Developers"</i>.
|
|
<li><b>Platform Independent Chat</b> - XMPP group chat is not restricted to Haiku users. Anyone with any client on any OS can chat along with you!
|
|
</ul>
|
|
|
|
<p>There are two ways to enter a groupchat. The first way allows you to create any arbitrary room you want which is what you want if you want to organize a specific meeting place among friends. From the buddy window, select Talk->Start Group Chat.
|
|
|
|
<img SRC="">
|
|
|
|
<p>Where it says <b>Username</b>, type the nickname you'd like to use for the room. Be unique! Then, where it says <b>Room Name</b>, give the desired name. Room names are of the form <i>name-of-the-room@conference.jabber.org</i>.
|
|
|
|
<p>There is a second way to enter a group chat and that's with Renga' own Channels. Channels are pre-named group chat rooms with friendly titles that other Renga users frequent. These are great meeting places for people of common interests. Explore.
|
|
|
|
<a NAME="prefs">
|
|
<font FACE="Courier New"><b><u><h1 ALIGN=CENTER>The Preferences Panel</h1></u></b></font>
|
|
<center><font SIZE=-2><a HREF="#top">top</a></font></center>
|
|
|
|
<p>We've eluded to the preferences panel several times, and you've probably found it and already know everything about it. But just to be sure... :-)
|
|
|
|
<p>For those of us who aren't so quick with new applications, the preferences panel can be found under the Edit menu as <i>"Preferences..."</i> There are three tabs:
|
|
|
|
<ul>
|
|
<li><b>Chat Rules:</b> This is where you can set options about how communication works, such as how new chat windows behave.
|
|
<li><b>Messages:</b> This is where you can set your canned quips.
|
|
<li><b>Transports:</b> This is a feature we haven't discussed, and it's core to the XMPP protocol. You can register with XMPP transports here. See the next section for details!
|
|
<li><b>Sounds:</b> This is where you can customize the sound effects to your tastes. Sound effects sound out for new chat windows popping up, users coming online and offline as well as incoming <b>/alert</b> calls.
|
|
</ul>
|
|
|
|
<a NAME="transports">
|
|
<h1 ALIGN=CENTER>XMPP Transports: Gateways to External Chat Systems</h1>
|
|
<a HREF="#top">top</a>
|
|
|
|
<p>If XMPP was just another new chat system, then everyone would just be a little more ill. :-)
|
|
But, in fact, XMPP is not. While it does support it's own network of users who can communicate
|
|
with each other along with other things like sending files, XMPP allows it's users to talk directly
|
|
with users of other chat clients! A little discussion about how it's done is in order.</p>
|
|
|
|
<p>If you're familiar with other <font COLOR=BLUE>B</font><font COLOR=RED>e</font>OS apps such as
|
|
GimICQ and BeAIM, you know that getting unofficial chat clients for popular chat systems is not a
|
|
new thing. Anything on the Internet is hackable, so there's no reason to believe AOL and ICQ have
|
|
secured their networks better than any hackable e-commerce system.
|
|
Well, these unofficial clients are just that -- clients. GimICQ only lets you talk to other ICQ
|
|
users, BeAIM the same with AOL users. However, XMPP lets you talk to both of these systems and more!</p>
|
|
|
|
<p>Here's where I have to give my disclaimers. You may remember the very public chat wars that went on between AOL Instant Messenger and MSN Messenger a while back. Basically, Microsoft was trying to hack the AOL chat protocol so that MSN Messenger users could talk to AOL users and vice-versa. AOL would have none of it and in what was a hilarious coding war, the cycle began:
|
|
|
|
<ul>
|
|
<li>MSN hacks AOL's protocol.
|
|
<li>AOL changes it's protocol and existing clients so MSN clients crash when they try to contact AOL clients.
|
|
<li>MSN updates code and again hack's AOL's protocol.
|
|
<li>AOL updates it's protocol again. MSN clients crash again.
|
|
<li>...so on and so on...
|
|
<li>Microsoft (with a straight face) releases statement, "We no longer wish to risk the security of our users to AOL's attacks and will therefore drop support for AOL clients."
|
|
</ul>
|
|
|
|
<p>What I'm trying to get at is that the XMPP transports are <b>not</b> always working. They are subject to changed protocols and downed servers. When the transports are updated to match the protocols then they'll work again...Basically,
|
|
if a transport doesn't work with Renga, it's probabably not the client's fault. You'll have to wait for the server's to catch up to the changing protocols. When these situations arise, you'll have two options:
|
|
|
|
<ul>
|
|
<li><b>Check <a HREF="http://www.jabber.org">Jabber.org</a>:</b> This is the website where you'll find updates on what's going on. If it's a problem with the server code, it'll be posted here.
|
|
<li><b>Change your server:</b> If you have reason to suspect the XMPP server you're registered with is having the problem, you can get a new login at another server. Of course, your address changes and if you've ever changed your email address, this is, well, the same thing. It's a real pain in the neck if you have a lot of contacts you need to communicate the change to. And you'll need to recreate your entire roster. Uggg!
|
|
</ul>
|
|
|
|
<p>Given a happy world where all transports work, you'll also want to add these external users to your roster. This is done the same as when adding XMPP users, except you want to change the menu to reflect what chat system they're using. Notice that the instructions on the "Add New Buddy" screen will change as you flip through the systems.
|
|
|
|
<p>The most common use of these bridging technologies is to access IRC discussion channels. Since
|
|
the IRC protocol does not change a lot, this seems to work better than bridging with other places.</p>
|
|
|
|
<p>To access an IRC channel, you need to mangle its name a bit. For example to join the #haiku
|
|
channel on irc.oftc.net you would use the address #haiku%irc.oftc.net@irc.jabberfr.org. Once joined,
|
|
this works like any other XMPP group chat.</p>
|
|
|
|
<a NAME="further">
|
|
<font FACE="Courier New"><b><u><h1 ALIGN=CENTER>Further Exploration</h1></u></b></font>
|
|
<center><font SIZE=-2><a HREF="#top">top</a></font></center>
|
|
|
|
<p>There are several other features that XMPP offers, as well as many nuances that are specific to Renga. The big one being changing your own online status. But I'll leave these all for you to explore! :-) If it's not easy enough to figure out on your own, then Rapture In Venice has failed you as a developer. So be confident!
|
|
|
|
<p>If you run into problems (or just want to say hi), you can find the Renga developers on our XMPP chat room renga@chat.jabberfr.org.</p>
|
|
|
|
<p>I hope this user manual is a friendly springboard to the world of XMPP and Renga. Have fun!
|
|
|
|
</body>
|
|
|
|
</html>
|
|
|