zephyr/USING

   1 This file explains how to use an existing Zephyr service once you've
   2 built and installed the Zephyr 2.0 distribution.  To learn how to
   3 build and install Zephyr, read the file INSTALL.  To learn how to set
   4 up Zephyr service at a site, read the file OPERATING.
   5
   6 First, before you can do anything else, your client machine must be
   7 running zhm from the local system binary directory (/etc/athena/zephyr
   8 if you built Zephyr with --enable-athena, /usr/local/sbin/zephyr if
   9 you installed Zephyr in /usr/local and didn't use --enable-athena).
  10 Only one copy of zhm can be running on a given machine, and it can be
  11 started by any user.  If you're using a machine you don't administer,
  12 you may want to check if the machine is configured to start up zhm
  13 automatically at boot time.
  14
  15 Once you have zhm running, you can start receiving zephyrgrams by
  16 running the command:
  17
  18         zwgc
  19
  20 "zwgc" stands for "Zephyr WindowGram Client".  If you built Zephyr
  21 with X support and are using an X display, you will receive messages
  22 as windows on your screen (click on them to get rid of them);
  23 otherwise, you will receive messages in your terminal as text.  Read
  24 the man page on zwgc to find out how to configure it using the
  25 .zwgc.desc file in your home directory.
  26
  27 You can send messages to another user with:
  28
  29         zwrite username
  30
  31 To write to groups of users, you must agree on a "class" and/or
  32 "instance" to write to (this will be explained in greater detail
  33 below).  At MIT, most users communicate in private groups via classes.
  34 Suppose a bunch of people wanted to communicate on a class "newclass".
  35 They would all subscribe to the class with the command:
  36
  37         zctl add newclass \* \*
  38
  39 and send messages with:
  40
  41         zwrite -c newclass
  42
  43 The "zctl add" command adds the subscription to the .zephyr.subs file
  44 in your home directory, so that you will automatically be subscribed
  45 to the class the next time you run zwgc.  If you just want to
  46 subscribe without adding the subscription to your .zephyr.subs file,
  47 use "zctl sub" instead of "zctl add".
  48
  49 Now for a bit more explanation about what classes and instances are:
  50 every Zephyr message is send to a class, an instance, and a recipient,
  51 commonly written as <class,instance,recipient>.  The default class is
  52 "MESSAGE"; the default instance is "PERSONAL".  When you use "zwrite
  53 username", you are sending a message to <MESSAGE,PERSONAL,username>.
  54 If you don't specify a username on the zwrite command line, you will
  55 be sending to the recipient "*", so when you use "zwrite -c newclass",
  56 you are sending a message to <newclass,PERSONAL,*>.
  57
  58 Similarly, every time you request a subscription, you are subscribing
  59 to a class, an instance, and a recipient.  The recipient must be
  60 either "*" or your username.  The instance can be any string; however,
  61 if you subscribe to instance "*", you will receive messages to any
  62 instance as long as the class and recipient also match.  The class can
  63 be any string; "*" has no special meaning for class names.  When you
  64 start zwgc, you are automatically subscribed to
  65 <MESSAGE,PERSONAL,yourusername> and <MESSAGE,URGENT,yourusername> even
  66 if you don't explicitly request those subscriptions.
  67
  68 As an example of how you might use these features, at MIT we have
  69 several frequently-used instances of class MESSAGE, called
  70 "white-magic", "help", "weather", "tmbg" and so forth.  These are
  71 commonly known as "public" instances because they are not intended to
  72 exclude anyone.  Users can subscribe to individual instances using
  73 "zctl add message help \*", or they can subscribe to all of them at
  74 once using "zctl add message \* \*".  (If users do this, they can tell
  75 zwgc to filter out messages from certain instances; see the man page
  76 for zwgc.)  If users want to have semi-private group conversations,
  77 they use separate classes, as described earlier.