ZWGC(1)

NAME
zwgc - Zephyr Windowgram client program

SYNOPSIS
zwgc [-reenter] [-nofork] [-ttymode]

DESCRIPTION
Zwgc is the primary zephyr(1) client. It is responsible for displaying zephyr notices in a pleasing format, and allows the user to quickly dispose of messages as they read them.

Clicking and releasing any button while the pointer is inside a WindowGram window will cause it to disappear. If the button is released while the pointer is outside the WindowGram window, the window does not disappear; this provides a way to avoid accidentally losing messages.

The user can configure the appearance of notices through the ~/.zephyr.desc file. This file contains commands which zwgc uses to define the format of the notices.

WindowGram Language Functions

does var

    match value1

    ...

    endmatch

    match value2

    ...

    endmatch

enddoes
This block compares the value of var to each value of the match statement, and executes the commands inside the appropriate match - endmatch set. Either or both of var or value n can end in an asterisk (*) and wild-card match the end of the string, for example filsys* matches filsys:priam.mit.edu.

beep
Beeps the terminal (either tty or X.) Useful for alerting for urgent messages; can be used multiple times for repeated beeps.

exec string
Executes string via the system(3) function, passing it to a shell and running it in the background. string can have variables in it (which get evaluated) as well as font information (see show below) which is ignored.

set var value
Sets var to value.

fields var var ...
Sets each of var to consecutive "fields" within a notice. Specially generated notices (such as login announcements and discuss meeting notices) are divided in to fields which can be named and called upon by name.

summary string
Sets the summary for this message to string. A summary is a one-line abbreviation of a notice for use with an optional browser (see zbrowser(1)). The abbreviation is stored as a window property in the Atom ZEPHYR_SUMMARY, type STRING (see xprop(1)). The first summary line to be invoked is the one used, likewise the first show invoked is the one used. If no summary has been assigned by the time a show is invoked, the description file is searched until one is found. Note that if an exit is found before a summary can be invoked, the rest of the file is ignored and the system default (and then internal last-resort) description file is searched.

show

    text

endshow
Prints text. text may include any of the following:

    @bold(text)
    Prints text in the bold font.

    @italic(text)
    Prints text in italics.

    @normal(text)
    Prints text in the normal font, which is useful inside one of the other font modifying commands.

    @font0(text) ... @font9(text)
    Prints text in a numbered font from 0 to 9, as defined in the user's ~/.Xresources file.

    @center(text)
    Prints text centered in the middle of the notice window.

    @right(text)
    Prints text flush right in the notice window.

    @left(text)
    Prints text flush left of the notice window (this is the default).

    Note that in all of the above, left and right parentheses may be replaced by any of the matching character pairs < > [ ] { } as long as they match symmetrically.

Any word starting with '$' is a variable, and is replaced by the value of the variable. In addition to variables defined using set, there are some pre-defined variables:

$kind
    Returns the kind of message, such as "ACKED".

$auth
    Returns yes, no, or forged, depending on whether the notice was authenticated, not authenticated, or authenticated unsuccessfully.

$port
    Returns the port number where the notice was sent from.

$class
    Returns the class of the notice, such as "MESSAGE".

$instance
    Returns the instance of the notice, such as "PERSONAL".

$opcode
    Returns the opcode of the notice, such as "USER_LOGIN".

$sender
    Returns the name of the user or service who sent the notice.

$recipient
    Returns the name of the recipient, either the user who got the message, or "*".

$mode
    Returns window if zwgc is running under the X window system, or tty if it is running on a terminal without window support.

$fromhost
    Returns the full name of the host that the notice appears to have been sent from. This is not fully reliable, as the information used to determine this hostname is not guaranteed to be correct (even for authentic messages).

$message
    Returns the message contained in the notice.

$default
    Returns the default formatted form of the message. showing this will usually give you the description the application author expected the notice to appear in. This will be displayed automatically by the system default file.

All variable names and commands are case insensitive. Also, does...match ignores case when comparing fields.

The octothorp (#) is used as the comment character, as in sh and csh. It can be used on any line, and causes the remainder of that line to be ignored.

X DEFAULTS
Zwgc reads either ~/.Xdefaults or server xrdb defaults (see xrdb(1) and XGetDef(3x)). Entries like

zwgc*option: value
zwgc.option: value

should work, in either ~/.Xdefaults loaded into the display server with xrdb (but not both.)

Logical values can be ( Yes On True T ) or ( No Off False nil ).

OPTION:
    MEANING (default):

useBackground
    use background pixmap updates (off by default)

textUpdate
    use image text updates (on by default)

nPlanes
    number of planes to draw to (debugging only)

cursorCode
    number of a code from the cursorfont (should be an even integer, see <X11/cursorfont.h>)

foreground
    Primary foreground color

Foreground
    Secondary foreground color (if foreground not set) [BlackPixel is the default if neither is set]

background
    Primary background color

Background
    Secondary background color (if background not set) [WhitePixel is the default if neither is set]

borderColor
    Primary border color

BorderColor
    Secondary border color (if borderColor not set) [BlackPixel is the default if neither is set]

pointerColor
    Primary mouse pointer color [foreground color is the default if not set]

reverseVideo
    (logical) Toggles foreground and background and border if it matches one of them.

ReverseVideo
    Secondary toggle, if reverseVideo is not set.

borderWidth
    Primary border width selector

BorderWidth
    Secondary border width selector (if borderWidth is not set) [1 is the default value if neither is set]

internalBorder
    Primary border between edge and text

BorderWidth
    Secondary selector (if internalBorder not set) [2 is the default value if neither is set]

geometry
    Primary POSITION (not size) geometry specifier. Negative/0 options allowed.

Geometry
    Secondary position specifer. [+0+0 is the default if neither is set.]

resetSaver
    (logical) Force screen to unsave when a message first appears. [default True]

reverseStack
    (logical) Attempt to stack WindowGram windows such that the oldest messages normally show on top. Some X window managers may silently ignore zwgc's attempts to restack its windows. This option can cause some unusual interactions with other windows if the user manually restacks either the other windows or the WindowGram windows. [default False]

name
    (string) window name [default "Zwgc"]

iconName
    (string) icon name [default "ZephyrGram"]

volume
    (integer) Beep volume adjustment [default 0]

interline
    Interline spacing [default 1 pixel]

debugBack
    (logical) debugging only: make the default window background the wrong color, to make sure it gets painted over (just causes flashing, no display corruption) [default FALSE]

bold
    Font for @bold() [default fgb-13]

italic
    Font for @italic() [default times-italic14]

normal
    Font for @normal() or unspecified type [default fg-13]

font0 ... font9
    Fonts for @font0() ... @font9() [all default to vctl-25]

Note that if a font cannot be opened, "fixed" is used instead. If fixed also fails (which did happen in testing) zwgc prints a warning message and tries to revert to ttymode.

The client will exit cleanly (unset location and cancel subscriptions) on:
	SIGTERM
	SIGHUP
	SIGINT
	SIGQUIT
	XIOError (with a message to stderr)
SIGHUP is what it expects to get upon logout.

COMMAND LINE
zwgc is normally invoked from /usr/athena/.login or /usr/athena/lib/init/login_misc in the foreground and with no arguments. When it has successfully set your location, it will put itself into the background. At this point it is safe to invoke additional zephyr commands, such as znol(1). (You can also put these commands in the initprogs Zephyr variable; the value of this variable is passed as the argument to the system(3) library call. See zctl(1) for details on how to set Zephyr variables.) zwgc will exit with an exit status of 0 if it was able to open the display successfully (if not in ttymode) or 1 if it couldn't open the display and the Zephyr variable fallback was not set to ``true''. If fallback is set to ``true'', then zwgc will fall back to ttymode if it can't open the display.

When running it by hand, the following command line options are recognized:
	-ttymode	Use the terminal, even if X is available
	-nofork		Stay in the foreground at all times
If you begin your .zephyr.desc file with
	#!/mit/yourdir/program
zwgc will attempt to run program instead of itself. If it succeeds, the other program will be invoked with the -reenter argument to warn it that this step has already been done once. This allows you to run a modified version of a normal zwgc without having it loop.

CONTROL MESSAGES
In order to allow some special user controls over the behavior of zwgc, certain Zephyr control notices can be sent directly to zwgc using the zctl(1) program. Currently implemented controls are

wg_read
    tell zwgc to re-read the ~/.zephyr.desc file.

wg_shutdown
    tell zwgc to cancel all subscriptions and stop acting on incoming notices. zwgc saves the subscriptions that were in effect at the time of the shutdown so that it can restore them later if needed.

wg_startup
    tell zwgc to restart from being shutdown and reinstall the saved subscriptions.

Other control messages may be implemented in the future.

DIAGNOSTICS
XErrors are diagnosed to stdout, and then IGNORED.

All internal errors are preceded by zwgc:.

After /tmp/wg.uid is written, the process forks off and disconnects from the terminal. It forks off and execs ``zctl load''.

NOTABLE CHANGES from the experimental release
Many bugs have been fixed.

Vast numbers of user-settable defaults have been added, most notable a geometry specification to allow the user to control where on the window the notices appear.

For speed, the description files are now compiled at load time, rather than reinterpreted.

The notices are single windows, not multiple nested ones (and as a consequence, the program runs smaller and faster). The XToolkit is no longer being used at all for the critical zwgc delivery client; the seperate browser uses it, without slowing down zwgc.

exec automatically backgrounds whatever it runs.

summary is now available to customize the labels used by the optional WindowGram browser.

While zwgc is wg_shutdown, it cancels subscriptions so that messages are not bitbucketed without warning. It restores these subscriptions upon wg_startup.

FILES
~/.zephyr.desc
~/.zephyr.vars			for exposure, initprogs, fallback
/etc/athena/zephyr.desc
~/.Xresources
/tmp/wg.uid
Note that zwgc will attempt to read $HOME/file for any file in the user's home directory, and fall back to ~/file (based on /etc/passwd.)

FONTS
fg-13, fgb-13, vctl-25	if available and not overridden by defaults
fixed			if any specified font is missing

BUGS
Zwgc does not at this time read the standard X Toolkit command line arguments.

SEE ALSO
zctl(1), zbrowser(1), zephyr(1), znol(1), system(3), zephyrd(8), zhm(8)
Project Athena Technical Plan Section E.4.1, `Zephyr Notification Service'

AUTHOR

Mark W. Eichin (MIT-Project Athena) <eichin@athena.mit.edu>

RESTRICTIONS
Copyright (c) 1987,1988 by the Massachusetts Institute of Technology. All Rights Reserved.
zephyr(1) specifies the terms and conditions for redistribution.