]> asedeno.scripts.mit.edu Git - 1ts-debian.git/blob - zephyr/zwgc/zwgc.1
new upstream version
[1ts-debian.git] / zephyr / zwgc / zwgc.1
1 .\"     $Id: zwgc.1 2370 2009-03-29 16:08:44Z kcr@ATHENA.MIT.EDU $
2 .\"     # end of TP (cf }N below)
3 .\"     # copied here, since we use @ in some of our tags, and that
4 .\"     # messes up \w and \h
5 .de }1
6 .ds ]X \&\\*(]B\\
7 .nr )E 0
8 .if !"\\$1"" .nr )I \\$1n
9 .}f
10 .ll \\n(LLu
11 .in \\n()Ru+\\n(INu+\\n()Iu
12 .ti \\n(INu
13 .ie !\\n()Iu+\\n()Ru-\w'\\*(]X'u-3p \{\\*(]X
14 .br\}
15 .el \\*(]X\h@|\\n()Iu+\\n()Ru@\c
16 .}f
17 ..
18 .de }N
19 .if \\n()E .br
20 .di
21 .if "\\n()E"0" .}f
22 .if "\\n()E"1" .}1
23 .if "\\n()E"2" .}2
24 .nr )E 0
25 ..
26 .\"     # tagged paragraph (paragraph with hanging label, but no para spacing)
27 .de TQ
28 .if !"\\$1"" .nr )I \\$1n
29 .ne 1.1v
30 .in \\n()Ru
31 .nr )E 1
32 .ns
33 .it 1 }N
34 .di ]B
35 ..
36 .TH ZWGC 1 "November 30, 1989" "MIT Project Athena"
37 .SH NAME
38 zwgc \- Zephyr Windowgram Client program
39 .SH SYNOPSIS
40 .B zwgc
41 [ \-reenter ] [ \-nofork ] [ \-ttymode ] [ \-f
42 .I filename
43 ] [ \-subfile
44 .I filename
45 ] [ \-loc
46 .I text
47 ] [ \-default
48 .I portname
49 ] [ \-disable 
50 .I portname
51 ] ... [ output driver options ]
52 [ X Toolkit options... ]
53 .SH DESCRIPTION
54 .I Zwgc
55 is the main
56 .I zephyr(1)
57 client.  It is responsible for receiving selected zephyr notices on
58 behalf of the user, formatting them, and displaying them using
59 one or more of the output devices.
60
61 .SS "Selection of Zephyr Notices"
62 .PP 
63 .I Zwgc
64 subscribes to various notice classes and instances on behalf of the
65 user.  Only notices in the subscription list will be received.  The
66 subscription list is composed of the default subscriptions (stored on
67 the server), the user's subscriptions file, and any subscriptions made
68 using
69 .IR zctl (1).
70 The user's subscription file defaults to
71 .IR $HOME/.zephyr.subs ,
72 or it can be specified with the \-subfile
73 option.  If "\-" is specified as the subscription filename, the
74 subscriptions will be read from standard input.
75
76 .PP
77 The
78 .I zctl
79 command is used to manipulate and change subscriptions.  See the
80 .IR zctl (1)
81 man page for details.
82
83 .SS "Zephyr Description Files"
84 .PP
85 .I Zwgc
86 formats its output messages according to the commands in its
87 description file.  The user's description file 
88 .RI ( $HOME/.zwgc.desc
89 by default, or whatever is specified by \-f) is read, or the system file
90 is read if the user's does not exist.
91 .PP
92 Every time a notice is received, 
93 .I zwgc
94 runs through the description file, and executes the appropriate commands.
95
96 .SS "Zephyr Description File Syntax"
97 .PP
98 A description file is simply a list of commands.  Whitespace (spaces,
99 tabs, and line breaks) is used
100 to separate tokens.  The type and amount of whitespace separating tokens
101 is irrelevant.
102 Comments can be delimited by # and newline (for line-oriented comments,
103 e.g. "# this is a comment" on a line by itself) or by /* and */ (e.g. "/*
104 this is a comment */").
105
106 .SH "DESCRIPTION LANGUAGE"
107 .SS Expressions
108 Expressions are used by certain commands.
109 They are composed from string literals, variable references,
110 function calls, and operators.  Parentheses can be used anywhere in an
111 expression to group expressions or increase readability.
112 .PP
113 String literals are specified by putting the contents in "double quotes".
114 .PP
115 Variables are set using the
116 .B set
117 command (see "COMMANDS", below).  They are
118 referenced in an expression by using the form
119 .IR $varname .
120 Some variables are set by default for each notice.
121 All other variables retain their values between notice interpretations,
122 so that if you set a variable, it retains that value until later
123 modified.
124 .PP
125 Functions are called using a C-like syntax,
126 \fBfname\fR(\fIexpr1\fR,\fIexpr2\fR), where
127 .B fname
128 is the
129 function name and
130 .IB expr n
131 are the arguments.
132 .PP
133 Binary operators use infix notation, such as "a == b".
134 .PP
135 Some commands use an expression list (exprlist), which is simply a set
136 of expressions separated by whitespace (e.g. $var1 "lit1" $var2).
137
138 .SS "Default variables"
139 .PP
140 The following variables are always available:
141 .TP 5
142 .B 1, ...
143 Numeric variables are assigned values corresponding to that field in the
144 notice (the body of each notice is conceptually an array of fields, each
145 terminated with a null character).  If the number is greater than the
146 number of fields actually in the notice, the value is "".  For example,
147 the standard zwrite messages have two fields: $1 is the signature, and
148 $2 is the text of the message.
149 .TP 5
150 .B auth
151 An indication of the authenticity of the notice.  ``yes'' means the
152 notice is authentic, ``no'' means it is not, and ``forged'' means that
153 the message claimed to be authentic but the verification of the claim
154 failed.  The ``forged'' indication usually appears when a user has
155 changed his Kerberos tickets with
156 .IR kinit (1)
157 but has not run ``zctl sub'' to
158 register this change with the Zephyr servers.
159 .TP
160 .B class
161 The class of the current notice.
162 .TP
163 .B date
164 The date on which the notice was sent.
165 .TP
166 .B default
167 The default output format for the current notice
168 .TP
169 .B error
170 An error message from the port read/write commands.
171 .TP
172 .B fromhost
173 The full name of the host from which the notice appears to have been
174 sent.  
175 .I This is not fully reliable,
176 as the information used to determine this hostname is not guaranteed to
177 be correct (even for authentic messages).
178 .TP
179 .B fullsender
180 The notice sender's name, including the zephyr realm name.
181 .TP
182 .B instance
183 The instance of the current notice.
184 .TP
185 .B kind
186 The kind of notice.
187 .TP
188 .B message
189 The full text of the message, with nulls converted to newlines.
190 .TP
191 .B number_of_fields
192 The number of fields in the message (a string representation of a
193 decimal number).
194 .TP
195 .B opcode
196 The opcode of the current notice.
197 .TP
198 .B output_driver
199 The name of the output driver in use.
200 .TP
201 .B port
202 The port from which the notice was sent.
203 .TP
204 .B realm
205 The local zephyr realm.
206 .TP
207 .B recipient
208 The recipient for the current notice.  If the notice is a multicast
209 (sent to several people), the recipient is set to ``*''.
210 .TP
211 .B sender
212 Usually a shortened version of fullsender.  If the realm of the sender
213 is equal to the realm of the recipient,
214 .I sender
215 omits the realm name.
216 .TP
217 .B time
218 The time of day at which the notice was sent.
219 .TP
220 .B user
221 The full zephyr name of the user (e.g. marc@ATHENA.MIT.EDU).
222 .TP
223 .B version
224 The current version of 
225 .IR zwgc .
226 .TP
227 .B zephyr_version
228 The protocol version of the notice.
229 .PP
230 All of these variables (except for error, output_driver, and version)
231 are re-set before each notice is processed.
232
233 .SS Functions
234 .PP
235 Following is a list of functions available for use in the description
236 file.
237 .TP 5
238 .BI buffer ()
239 The contents of the current output buffer.
240 .TP
241 .BI downcase (expr)
242 Returns the value of \fIexpr\fR, converted to lower case.
243 .TP
244 .BI get (expr)
245 Returns a line from the port named \fIexpr\fR.  If there is no text
246 waiting on the port (e.g. the program connected to the port has not
247 printed any output), this function will wait until it can read a line of
248 text from the port.
249 .TP
250 .BI getenv (expr)
251 Returns the value of the environment variable \fIexpr\fR, or the empty
252 string if it does not exist.
253
254 .TP
255 .BI lany "(expr1, expr2), " rany "(expr1, expr2)"
256 Return a number of characters equal to the length of
257 .I expr2
258 from the beginning
259 .RB ( lany )
260 or end 
261 .RB ( rany )
262 of
263 .I expr1
264 (e.g. lany("1234567890","foo") would return "123").
265 If
266 .I expr1
267 is a variable reference, the variable
268 is modified to remove the characters returned.
269 If
270 .I expr2
271 is longer than
272 .IR expr1 ,
273 the value of
274 .I expr1
275 is returned (and 
276 .I expr1
277 is set to "", if a variable).
278 .TP
279 .BI lbreak "(expr1, expr2), " rbreak "(expr1, expr2)"
280 .I Expr2
281 defines a set of characters.  The function returns the longest
282 initial
283 .RB ( lbreak )
284 or final 
285 .RB ( rbreak )
286 string from
287 .I expr1
288 composed of characters
289 .I not
290 in this set (e.g. lbreak("characters", "tuv") would return "charac").  If
291 .I expr1
292 is a variable reference, the variable
293 is modified to remove the characters returned.  If no characters
294 in
295 .IR expr2 " are in " "expr1, " then " expr1 "
296 is returned (and 
297 .I expr1
298 is set to "", if a variable).
299 .TP
300 .BI lspan "(expr1, expr2), " rspan "(expr1, expr2)"
301 These functions are the negation of the 
302 .B break
303 functions; the returned string consists of characters 
304 .I in 
305 the set defined by
306 .I expr2
307 .TP
308 .BI protect (expr)
309 Returns a string which will be evaluated identically to \fIexpr\fR,
310 but will not affect any surrounding environments.  That is, any
311 characters which could close outside environments are quoted, and any
312 environments in \fIexpr\fR which are not closed at the end are closed.
313 .TP
314 .BI substitute (expr)
315 Evaluates variable references of the form \fI$variable\fR in expr and
316 converts $$ to $.
317 .TP
318 .BI upcase (expr)
319 Returns the value of \fIexpr\fR, converted to upper case.
320 .TP
321 .BI verbatim (expr)
322 Returns a string that will be displayed exactly as \fIexpr\fR looks.
323 Anything which could be mistaken for an environment is quoted.
324 .TP
325 .BI stylestrip (expr)
326 Returns \fIexpr\fR with all environments stripped out.
327 .TP
328 .BI zvar (expr)
329 Returns the value of the zephyr variable \fIexpr\fR,
330 or the empty
331 string if it does not exist.  [Zephyr variables
332 can be set and examined with 
333 .IR zctl (1).]
334
335 .SS Operators
336 .PP
337 Following is a list of operators which can be used in the description
338 file to compose expressions:
339 .TP
340 .IB expr1 " + " expr2
341 String concatenation of
342 .IR expr1 " and " expr2
343 .TP
344 .IB expr1 " == " expr2
345 True if the two expressions are equal, false otherwise.
346 .TP
347 .IB expr1 " =~ " expr2
348 True if the regular expression pattern
349 .IR expr2 " matches " expr1.
350 .TP
351 .IB expr1 " !~ " expr2
352 Negation of "=~".
353 .TP
354 .IB expr1 " != " expr2
355 Negation of "=="
356 .TP
357 \fIexpr1\fB and \fIexpr2\fR, \fIexpr1\fB & \fIexpr2\fR
358 True if
359 .IR expr1 " and " expr2
360 are both true.
361 .TP
362 \fIexpr1\fB or \fIexpr2\fR, \fIexpr1\fB | \fIexpr2\fR
363 True if either of
364 .IR expr1 " or " expr2
365 are true.
366 .TP
367 \fB! \fIexpr1\fR, \fBnot \fIexpr1\fR
368 The logical negation of
369 .I expr1.
370
371 .SS Commands
372 .PP
373 Following is a list of the commands usable in the description
374 language:
375 .TP 5
376 .BI appendport " expr1 expr2"
377 Creates a port called \fIexpr1\fR.  All output to the port will be
378 appended to the file \fIexpr2\fR.  There is no input.  If the file is
379 created, its mode is set to read-write, owner only (no access for others).
380 .TP
381 .B break
382 Exits the innermost if, case, or while block.
383 .TP
384 \fBcase \fIexpr1\fR [ ((\fBmatch \fIexpr\fR [,\fIexpr ...\fR]) | \fBdefault\fR)\fI commands \fR] ... \fBendcase\fR
385 Evaluates \fIexpr1\fR.  Then, each of the match expressions is
386 evaluated in order.  The first time an expression matches \fIexpr1\fR,
387 then the body of commands under it is executed, and the rest of the case
388 statement is skipped.  This compare is case-insensitive.  default always
389 matches, so it should always appear as the last set of commands.  See
390 the default description file for an example of use.
391 .TP
392 .B clearbuf
393 Clears the output buffer (see below for details on buffering).
394 .TP
395 .BI closeinput " expr"
396 Closes the file associated with \fIexpr\fR.
397 .TP
398 .BI closeoutput " expr"
399 Sends an EOF (end-of-file) to the process if \fIexpr\fR was a port created by
400 execport, or closes the file if it was created by outputport or
401 appendport.
402 .TP
403 .BI closeport " expr"
404 Closes both input and output of \fIexpr\fR as defined above.
405 .TP
406 .BI fields " variable1 ..."
407 sets the list of variables to be equal to the fields in the
408 notice.  If there are more variables than fields, the extra
409 variables are left empty.
410 .TP
411 .BI exec " exprlist"
412 Executes a program without any input or output.  A command named by
413 \fIexprlist\fR is executed.  Each expression is used as an argument to
414 the program; the first expression names the program (it may be either an
415 absolute pathname, or a program name; the user's PATH is searched to
416 find simple program names).
417 .TP
418 .BI execport " expr1 exprlist"
419 Creates a port called \fIexpr1\fR.  A command named by \fIexprlist\fR
420 is executed, as described above for \fBexec\fR.
421 All output to the port is sent to the standard input
422 of the process.  Reading from the port will return the standard output
423 of the process.
424 .TP
425 .B exit
426 Completes processing of the current notice.  The remainder of the
427 description file is ignored after execution of this command.
428 .\" hack because the following line otherwise breaks because it is too long.
429 .TP
430 \fBif \fIexpr1 \fBthen \fIcommands1\fR [\fBelseif \fIexpr2 \fBthen \fIcommands2\fR] ... [\fBelse \fIcommandsn\fR] \fBendif\fR
431 If \fIexpr1\fR evaluates to true, execute \fIcommands1\fI, etc. [A conditional
432 construct, similar to the constructs in the C shell (csh).]
433 .TP
434 .BI inputport " expr1 expr2"
435 Creates a port called \fIexpr1\fR.  All input from the port comes from
436 the file \fIexpr2\fR.  There is no output.
437 .TP
438 .B noop
439 does nothing
440 .TP
441 .BI outputport " expr1 expr2"
442 Creates a port called \fIexpr1\fR.  The file \fIexpr2\fR will be
443 truncated, or created if it does not exist.  All output to the port
444 will be appended to the file \fIexpr2\fR.  There is no input.  If the file is
445 created, its mode is set to read-write, owner only (no access for others).
446 .TP
447 .BI print " expr1 ..."
448 adds the values of the expressions to the current output buffer.  The
449 values of the expressions are separated by spaces in the output.
450 .TP
451 .B put \fR[\fIexpr \fR[\fIexprlist\fR]]
452 Sends data to a port.  If \fIexpr\fR is provided, then it is used as the
453 port, otherwise the port used is the
454 port corresponding to the default output device.
455 If \fIexprlist\fR is provided, the expressions in the list are sent to
456 the port, separated by spaces.  If it is omitted, then the contents
457 of the output buffer are sent as the data.
458 .TP
459 .BI set " variable " = " expr"
460 sets
461 .I variable
462 equal to
463 .IR expr .
464 Variable can later be
465 referenced by 
466 .IR $variable .
467 .TP
468 .BI show " text " endshow
469 Appends text to the output buffer.  This command is special, because
470 the string does not need to be quoted.  Whitespace at the beginning or
471 end of the lines of text is ignored.  The \fIendshow\fR must appear as
472 the first token on a line (it may only be preceded on that line by whitespace).
473 Variable substitutions and formatting commands
474 (but not expressions or functions) are processed in the text.  Example:
475 .nf
476 show
477    this is some text
478    from: $sender
479 endshow
480 .fi
481 .TP
482 .BI while " expr " do " statements " endwhile
483 Executes \fIstatements\fR until \fIexpr\fR is false.
484
485 .SH PORTS
486 .PP
487 Ports are an abstraction encompassing all I/O forms of which
488 zwgc is capable.  There are pre-existing output ports corresponding to each
489 of the output devices, and more ports can be created with the
490 port commands described above.
491
492 .SH OUTPUT
493 The output is usually collected in the
494 .I "output buffer"
495 and saved until a
496 .I put
497 command sends the output to an output device (such as an X display or a
498 terminal).  The output buffer is implicitly cleared after each notice is
499 completely processed.
500
501 .PP
502 Output devices are implemented as output ports.  A message is
503 displayed in a device-dependent manner when a string is output to the
504 port corresponding to the output device.  Formatting commands are
505 embedded in the text as @ commands of the form @command(text).
506 Command names are case-insensitive and consist of alphanumeric
507 characters and underscores.  Valid brackets are () [] {} and <>.
508 If the command name is empty (such as in
509 .RB `` @(foo) ''),
510 then a new
511 environment with no changes is created (This is useful to temporarily
512 change some parameter of the output, such as the font).
513 .PP
514 The following output devices are supported:
515 .TP 5
516 stdout
517 Sends the string to standard output exactly as is.
518 .TP
519 stderr
520 Sends the string to standard error exactly as is.
521 .TP
522 plain
523 Sends the string with all formatting environments removed to standard
524 output.
525 .TP
526 tty
527 Does formatting on the message according to @ commands embedded in the
528 text.  The output,
529 with appropriate mode-changing sequences, is sent to the standard output.
530 The appropriate characteristics of the display are taken from
531 the TERMCAP entry (see
532 .IR termcap (5)) 
533 for the terminal named by the TERM environment variable.
534 Supported @ commands are:
535 .RS 10
536 .TP 15
537 @roman
538 Roman (plain) letters (turns off all special modes).
539 .TP
540 @b or @bold
541 Bold letters.  If not available, reverse video, else underline.
542 .TP
543 @i or @italic
544 Italic letters (underlining, if available).
545 .TP
546 @beep
547 "bl" termcap entry, else "^G" (beep the terminal); limited to once per
548 message.
549 .TP
550 @l or @left
551 left aligned
552 .TP
553 @c or @center
554 center aligned
555 .TP
556 @r or @right
557 right aligned
558 .RE
559 .IP "" 5
560 Other @-commands are silently ignored.
561 .TP 5
562 X
563 Displays one window per string output to the port.  The output is
564 formatted according to @ commands embedded in the string.  Supported
565 @ commands are:
566 .RS 10
567 .TP 15
568 @roman
569 turns off @italic and @bold
570 .TP
571 @b or @bold
572 turns on boldface
573 .TP
574 @i or @italic
575 turns on italics
576 .TP
577 @l or @left
578 left aligned
579 .TP
580 @c or @center
581 center aligned
582 .TP
583 @r or @right
584 right aligned
585 .TP
586 @large
587 large type size
588 .TP
589 @medium
590 medium type size
591 .TP
592 @small
593 small type size
594 .TP
595 @beep
596 Ring the X bell (limited to once per message)
597 .TP
598 @font
599 sets the current font to the font specified in the contents of the
600 environment (e.g. @font(fixed)).  This will remain in effect for the
601 rest of the environment (a temporary change can be achieved by enclosing the
602 font-change in an @(...) environment).  If the named font is not
603 available, the font ``fixed'' is used instead.
604 .TP
605 @color
606 sets the color to the color specified in the contents of the
607 environment.  The color name should appear in the X color name database.
608 This color will remain in effect for the rest of the environment.  If
609 the named color is not available, the default foreground color is used.
610 .RE
611 .IP "" 5
612 Any other environment name not corresponding to the above environment
613 names will set the current ``substyle.''
614 .IP
615 The attributes of a given block of text are determined by any active
616 environments, evaluated in the context of the current style and
617 substyle.
618 .IP
619 The style is specific to each window.  Its name has three dot
620 (``.'') separated fields, which are by default the values of the class,
621 instance, and recipient variables, with all dots changed to underscores
622 (``_'') and all letters converted to lowercase.  The style can be
623 altered by setting the
624 .I style
625 variable.  Note that it \fBmust always\fR have exactly two ``.''
626 characters in it.
627 .IP
628 The substyle is determined by @ commands in the message text.
629 .IP
630 Zwgc variables which the X output device reads are:
631 .RS 10
632 .TP 15
633 default_X_geometry
634 default geometry for notices, set from resources
635 .TP
636 X_geometry
637 overrides geometry in resource file, if set
638 .TP
639 default_X_background
640 default background color for notices, set from resources
641 .TP
642 X_background
643 overrides bgcolor in resource file, if set
644 .TP
645 style
646 style, as described above
647 .RE
648 .IP "" 5
649 The expected geometry values are described below.
650 .IP
651 The fonts and color for a piece of text are determined by the styles
652 defined in the X resources file.  The following resources relating to
653 text style are used by zwgc:
654 .RS 10
655 .TP 10
656 zwgc.style.\fIstylenames\fR.geometry
657 geometry for messages of the specified style
658 .TP
659 zwgc.style.\fIstylenames\fR.background
660 background color for messages of the specified style
661 .TP
662 zwgc.style.\fIstylenames\fR.substyle.\fIsubstylename\fR.fontfamily
663 fontfamily name for the specified style and substyle
664 .TP
665 zwgc.style.\fIstylenames\fR.substyle.\fIsubstylename\fR.foreground
666 foreground color for the specified style and substyle
667 .TP
668 zwgc.fontfamily.\fIfontfamilyname\fR.\fIsize\fR.\fIface\fR
669 specifies the fonts for a given fontfamily.  \fIsize\fR is one
670 of small, medium, or large, and \fIface\fR is one of roman,
671 bold, italic, or bolditalic.
672 .RE
673 .IP "" 5
674 The best way to get started in customizing X resources for
675 .I zwgc
676 is to examine the default application resources and other users'
677 resources to understand how they specify the default appearance.
678
679 .SH "X RESOURCES"
680 Other X resources used by
681 .I zwgc
682 are listed below.
683 Entries like
684 .sp
685 .nf
686 .in +5
687 zwgc*option: value
688 Zwgc*option: value
689 zwgc.option: value
690 *option: value
691 \&.option: value
692 .in -5
693 .fi
694 .sp
695 will work.
696 .PP
697 An entry labeled with zwgc*option in any of the sources takes precedence
698 over Zwgc*option, which takes precedence over *option entries.
699 The following sources are searched in order:
700 .nf
701 .in +5
702 command-line arguments (\-xrm)
703 contents of file named by XENVIRONMENT environment variable
704 X server resource database (see \fIxrdb\fR(1))
705 application resources file
706 .in -5
707 .fi
708 .PP
709 Logical values can be ( Yes On True T ) or ( No Off False nil ).
710 .TP 15
711 \fBOPTION:\fR
712 \fBMEANING [default]:\fR
713 .TP
714 cursorCode
715 number of a code from the cursorfont (should be an even integer, see
716 \fI<X11/cursorfont.h>\fR) to use for the windows.
717 .TP
718 foreground
719 Primary foreground color
720 .TP
721 Foreground
722 Secondary foreground color (if foreground not set) [BlackPixel is the default if neither is set]
723 .TP
724 background
725 Primary background color
726 .TP
727 Background
728 Secondary background color (if background not set) [WhitePixel is the
729 default if neither is set]
730 .TP
731 borderColor
732 Primary border color
733 .TP
734 BorderColor
735 Secondary border color (if borderColor not set) [BlackPixel is the
736 default if neither is set]
737 .TP
738 pointerColor
739 Primary mouse pointer color [foreground color is the default if not set]
740 .TP
741 reverseVideo
742 (logical) Toggles foreground and background (and border, if it matches
743 foreground or background). 
744 .TP
745 ReverseVideo
746 Secondary toggle, if reverseVideo is not set. [off is the default if
747 neither is set]
748 .TP
749 borderWidth
750 Primary border width selector
751 .TP
752 BorderWidth
753 Secondary border width selector (if borderWidth is not set) [1 is the
754 default value if neither is set]
755 .TP
756 internalBorder
757 Primary border between edge and text
758 .TP
759 InternalBorder
760 Secondary selector (if internalBorder not set) [2 is the default value
761 if neither is set]
762 .TP
763 geometry
764 Primary POSITION (not size) geometry specifier.
765 The geometry should be of the form "{+|\-}x{+|\-}y", specifying an (x,y)
766 coordinate for a corner of the window displaying the notice.  The
767 interpretation of positive and negative location specifications follows
768 the X conventions.  A special location of `c' for either x or y
769 indicates that the window should be centered along that axis.  Example:
770 a geometry of "+0+c" specifies the window should be at the top of the
771 screen, centered horizontally.
772 .TP
773 Geometry
774 Secondary position specifer. [+0+0 is the default if neither is set.]
775 .TP
776 resetSaver
777 (logical) Primary value to force screen to unsave when a message first
778 appears.
779 .TP
780 ResetSaver
781 (logical) Secondary value to force screen to unsave. [default True] 
782 .TP
783 reverseStack
784 (logical) Primary value to specify that zwgc should attempt to stack
785 WindowGram windows such that the oldest messages
786 normally show on top.  Some X window managers may silently ignore
787 .IR zwgc 's
788 attempts to restack its windows.  This option can cause some unusual
789 interactions with other windows if the user manually restacks either the
790 other windows or the WindowGram windows.
791 .TP
792 ReverseStack
793 Secondary value to enable reverse stacking. [default False] 
794 .TP
795 title
796 (string) Primary window title
797 .TP
798 Title
799 Secondary window title [defaults to the last pathname component
800 of the program name, usually "zwgc"]
801 .TP
802 transient
803 (logical) Primary value which determines if zephyrgram windows will be
804 created with the \fBWM_TRANSIENT_FOR\fR property set.  If this
805 resource is true, the property will be set, telling certain
806 windowmanagers to treat zephyrgram windows specially.  For instance,
807 \fItwm\fR will not put decorations on transient windows, \fImwm\fR
808 will not let you iconify them, and \fIuwm\fR ignores the resource
809 entirely.
810 .TP
811 Transient
812 Secondary transient determining value [default False]
813 .TP
814 allDesktops
815 (logical) Primary value which determines if zephyrgram windows should
816 appear on all desktops, for those window managers which support multiple
817 desktops (sometimes referred to as workspaces).  When this resource is
818 true (the default),
819 .I zwgc
820 sets the \fB_NET_WM_DESKTOP\fR property to 0xFFFFFFFF for each zephyrgram
821 window, indicating that it should appear on all desktops.
822 .TP
823 AllDesktops
824 Secondary value determining whether zephyrgram windows should appear
825 on all desktops.
826 .TP
827 scrollDelete 
828 (logical) If true, scrolling over a zgram will cause it
829 to be deleted
830 .TP
831 ScrollDelete
832 Secondary value to enable deletion of a zgram by scrolling over it
833 [default False]
834 .TP
835 enableDelete
836 (logical) If true, zwgc creates a WM_PROTOCOLS property on all zgrams, with
837 WM_DELETE_WINDOW as contents.
838 .TP
839 EnableDelete
840 Secondary value to enable WM_DELETE_WINDOW protocol on zgrams [default False]
841 .TP
842 minTimeToLive
843 Primary value which specifies the minimum amount of time (``minimum time to
844 live'') a WindowGram must be on-screen (in milliseconds) until it can
845 be destroyed.  This feature is useful to avoid accidentally clicking
846 on new WindowGrams when trying to delete old ones.
847 .TP
848 MinTimeToLive
849 Secondary value of ``minimum time to live.''
850 .TP
851 iconName
852 (string) Primary icon name
853 .TP
854 IconName
855 Secondary icon name [defaults to the last pathname component
856 of the program name, usually "zwgc"]
857 .TP
858 name
859 (string) Primary window class name
860 .TP
861 name
862 Secondary window class name [defaults to the last pathname component
863 of the program name, usually "zwgc"]
864 .TP
865 synchronous
866 (logical) Primary X synchronous mode specifier.  On means to put the X
867 library into synchronous mode.
868 .TP
869 Synchronous
870 Secondary X synchronous mode specifier.  [default is `off']
871 .PP
872 The window class is always "Zwgc".
873 .SH X BUTTONS
874 .PP
875 Clicking and releasing any button without the shift key depressed while
876 the pointer remains inside a WindowGram window will cause it to
877 disappear. If the pointer leaves the window
878 while the button is depressed, the window does not disappear; this
879 provides a way to avoid accidentally losing messages.
880 .PP
881 If the control button is held down while clicking on a WindowGram,
882 then that WindowGram and all windowgrams under the point where the
883 button is released will be erased.
884 .PP
885 .B WARNING:
886 If you do this with too many WindowGrams under the mouse, it is
887 possible for your subscriptions to be lost.  If \fIzctl retrieve\fR
888 returns nothing, then issue a \fIzctl load\fR command to re-subscribe
889 to your default set of subscriptions.  If you use znol, then \fIznol
890 \-q &\fR will restore the subscriptions you need for \fIznol\fR.
891 .PP
892 Portions of the text of a message may be selected for "pasting" into other X
893 applications by using the shift key in cooperation with the pointer
894 buttons.
895 Holding the Shift key while depressing Button1 (usually the left button)
896 will set a marker at the
897 text under the pointer.  Dragging the pointer with Shift-Button1 still
898 depressed extends the selection from the start point, until the button
899 is released.  The end of the selection may also be
900 indicated by releasing Button1, holding down the Shift key, and pressing
901 Button3 (usually the right button) at the desired endpoint of the selection.
902 The selection will appear with the text and background colors reversed.
903
904 .SH ADDITIONAL X FEATURES
905 If
906 .I zwgc
907 receives a WM_DELETE_WINDOW, it destroys the zephyrgram as if it were
908 clicked on.
909 .PP
910 If a zephyrgram is unmapped, it is removed from the stacking order
911 used by reverseStack.
912
913 .SH COMMAND LINE
914 .I zwgc
915 is normally invoked from 
916 .IR /usr/athena/lib/init/login ,
917 .IR $HOME/.xsession ,
918 or 
919 .I /usr/athena/lib/init/xsession
920 in the foreground. When it has successfully set your location and
921 obtained subscriptions, it will put itself into the background (unless
922 the \-nofork option has been specified). At this point it is safe to
923 invoke additional zephyr commands, such as
924 .IR znol (1).
925 (You can also put these commands in the
926 .I initprogs
927 Zephyr variable; the value of this variable is passed as the argument to
928 the
929 .IR system (3)
930 library call during initialization.)
931 .I zwgc
932 will exit with an exit
933 status of 0 if it was able to open the X display successfully or 1 if it
934 couldn't open the display and the Zephyr variable
935 .I fallback
936 was set to ``false''. If
937 .I fallback
938 is set to ``true'',
939 .I zwgc
940 will fall back to ``ttymode'' (making the tty driver the default output
941 device) if it can't open the X display.  If
942 .I fallback
943 is not set and the display cannot be opened,
944 .I zwgc
945 prints an explanatory message and exits with a status of 1.
946 .PP
947 If the
948 .I \-ttymode
949 option is specified,
950 .I zwgc
951 will ignore any X display and use the terminal as its primary output
952 device.  This flag overrides any setting of the fallback variable.
953 .PP
954 If the
955 .I \-loc
956 option is specified,
957 .I zwgc
958 will use the specified string as the tty field for the location it
959 sets.  This allows users to potentially specify more useful auxiliary
960 information than their ttys or display names.
961 .PP
962 The
963 .I \-reenter
964 option is provided for compatibility with the previous version of
965 .IR zwgc .
966 .PP
967 .I zwgc
968 will exit cleanly (unset location and cancel subscriptions) on:
969 .nf
970         SIGTERM
971         SIGHUP
972         XIOError (with a message to stderr)
973 .fi
974 SIGHUP is what it expects to get upon logout.  Also, the signals
975 SIGINT, SIGQUIT, and SIGTSTP are ignored because they can be sent
976 inadvertently, and bizarre side-effects can result.  If you want them
977 to be acted on, then run
978 .I zwgc -nofork &
979 .PP
980 If
981 .I zwgc
982 receives a SIGUSR1, it will rewrite the file used to store the
983 WindowGram port number ($WGFILE or /tmp/wg.\fIuid\fR), in the event
984 that the file has been lost.
985 .SH CONTROL MESSAGES
986 In order to allow some special user controls over the behavior of
987 .IR zwgc ,
988 certain Zephyr control notices can be sent directly to
989 .I zwgc
990 using the
991 .IR zctl (1)
992 program. Currently implemented controls are
993 .TP 15
994 wg_read
995 tell
996 .I zwgc
997 to re-read the current description file.
998 .TP
999 wg_shutdown
1000 tell 
1001 .I zwgc
1002 to cancel all subscriptions and stop acting on incoming notices. 
1003 .I zwgc
1004 saves the subscriptions that were in effect at the time of the shutdown
1005 so that it can restore them later if needed.
1006 .TP
1007 wg_startup
1008 tell 
1009 .I zwgc
1010 to restart from being shutdown and reinstall the saved subscriptions.
1011 .PP
1012 Other control messages may be implemented in the future.
1013
1014 .SH EXAMPLES
1015 For an example of a description file, see
1016 .IR /usr/athena/share/zephyr/zwgc.desc .
1017 For an example of X resources, see
1018 .IR /usr/athena/share/zephyr/zwgc_resources .
1019
1020 .SH BUGS
1021 The X selection code can highlight the wrong portions of messages
1022 containing formatted text placed with the @center() or @right()
1023 directives.
1024 .PP
1025 If you are using Kerberos support and get new tickets (using
1026 ``kinit''), you must send a subscription notice to the server (using a
1027 command such as ``zctl load /dev/null'') or all received Zephyr
1028 notices will appear to be unauthentic.  (If all received Zephyr
1029 notices appear to be forged, your tickets have probably expired, in
1030 which case you must get new tickets and then run ``zctl load
1031 /dev/null''.)
1032 .SH FILES
1033 .TP 15
1034 $HOME/.zwgc.desc
1035 Default location of user's description file
1036 .TP
1037 /usr/athena/share/zephyr/zwgc.desc
1038 System-wide description file
1039 .TP
1040 /usr/athena/share/zephyr/zwgc_resources
1041 Default X application resources.
1042 .TP
1043 $ZEPHYR_VARS or $HOME/.zephyr.vars
1044 File containing variable definitions
1045 .TP
1046 $HOME/.zephyr.subs
1047 Supplementary subscription file
1048 .TP
1049 $HOME/.Xresources
1050 Standard X resources file
1051 .TP
1052 $WGFILE or /tmp/wg.\fIuid\fR
1053 File used to store WindowGram port number for other clients
1054 .SH SEE ALSO
1055 csh(1), kinit(1), xrdb(1), zctl(1), zephyr(1), znol(1), X(1), getenv(3),
1056 system(3), termcap(5), zephyrd(8), zhm(8)
1057 .br
1058 Project Athena Technical Plan Section E.4.1, `Zephyr Notification Service'
1059 .SH AUTHORS
1060 .nf
1061 John Carr (MIT/Project Athena) <jfc@athena.mit.edu>
1062 Marc Horowitz (MIT/Project Athena) <marc@athena.mit.edu>
1063 Mark Lillibridge (MIT/Project Athena) <mdl@CS.CMU.EDU>
1064 .fi
1065 .SH RESTRICTIONS
1066 Copyright (c) 1989 by the Massachusetts Institute of Technology.
1067 All Rights Reserved.
1068 .br
1069 .I zephyr(1)
1070 specifies the terms and conditions for redistribution.