jwgc - Jabber Windowgram Client
jwgc [-h] [-debug <flags>] [-f <filename>] [-j <jid>]
[-u <username>] [-p <password>] [-r <resource>]
[-s <server>] [-register] [-ssl] [-port <port>]
[-priority <priority>] [-ttymode] [-nofork]
[-default <driver>] {-disable <driver>}*
[output driver options]
Jwgc is the base of all of jwgc's functionality. It handles
connections to the Jabber server and from the various jwgc clients.
(such as jwrite, jlocate, etc) You must have the jwgc component
running for anything else to work. It also handles displaying incoming
messages on any output devices you have enabled.
Jwgc is almost entirely configurable from the command line. Almost
all of the command line options have associated variables as listed
below.
- -h
-
Provides a listing of all of the available flags.
- -debug flags
-
Without flags, -debug lists all of the available debug output
types. Otherwise, this option enables debugging output of the
specified types, or 'all' for all debugging output.
- -f filename
-
Load an alternate description file.
- -u username
-
Username to log into the jabber server as. If this isn't
specified anywhere, and -j isn't specified, jwgc will use
your unix username.
Associated variable: username
- -p password
-
Password to log into the jabber server with. If this isn't
specified anywhere, jwgc will prompt you for it.
Associated variable: password
- -r resource
-
Jabber resource to use. This defaults to jwgc unless you
specify something else.
Associated variable: resource
- -s server
-
Jabber server to connect to. This defaults to jabber.org
unless you specify something else.
Associated variable: server
- -j jid
-
This option causes -u, -r and -s to be ignored. Instead, all
of this information is taken directory from the jid specified,
which tends to be of the form:
username@server/resource
Associated variable: jid
- -ssl
-
Turns on ssl support. This will try to connect to the ssl port
of the Jabber server for a secure connection.
Associated variable: usessl (true)
- -nossl
-
Turns off ssl support. This can be useful if ssl is enabled
by default and you don't have ssl support on the target server.
Associated variable: usessl (false)
- -port port
-
Specifies the port to connect to on the Jabber server.
Associated variable: port
- -priority priority
-
Specifies the Jabber priority to connect with.
Associated variable: priority
- -ttymode
-
Enables only tty mode, which eliminates any graphical interface.
- -nofork
-
Prevents jwgc from backgrounding itself.
- -register
-
Causes jwgc to attempt to register your account with the Jabber
server on startup. This is necessary to create a new account.
- -default driver, -disable driver, [output driver options]
-
These are all currently undocumented, sorry.
The following variables have no associated command line arguments:
- initprogs
-
Programs specifed with this variable are run automatically when jwgc
is started up.
Jwgc consists of two main types of configuration files, and extra
configuration files depending on which drivers you have enabled.
The jwgc description files are the most important piece of jwgc's
configuration. They tell jwgc how to display incoming messages. If
your description file is broken, then most likely nothing will be displayed
at all. There are two instances of the description file. One is
jwgc.desc, installed in an etc directory wherever the root of
your installation is. This is the default description file users will
be using. This can be overridden by placing a .jwgc.desc file in
one's home directory. Note that this is a -complete- override. The
default will not be read at all if a .jwgc.desc exists in the user's
home directory. As such, if a user wants to modify the output, that user
should copy the default jwgc.desc into their home directory as
.jwgc.desc and modify it there.
The jwgc variable files contain default settings for any of the
various variables jwgc uses. These are described in more detail
later, but there are three incarnations of this file: jwgc.vars,
jwgc.vars.fixed, and .jwgc.vars. jwgc.vars is a system
default file, and can be overridden by .jwgc.vars. jwgc.vars.fixed
is a system default file that contains variables that can -not- be
overridden by other config files, or by command line options. Finally,
.jwgc.vars is the user's personal configuration options. These files
don't have to exist at all for jwgc to function. In fact, all of the
options in them can be specified at the command line.
A description file is simply a list of commands. Whitespace
(spaces, tabs, and line breaks) is used to separate tokens.
The type and amount of whitespace separating tokens is
irrelevant. Comments can be delimited by # and newline (for
line-oriented comments, e.g. ``# this is a comment'' on a line
by itself) or by /* and */ (e.g. ``/* this is a comment */'').
Expressions are used by certain commands. They are composed
from string literals, variable references, function calls,
and operators. Parentheses can be used anywhere in an
expression to group expressions or increase readability.
String literals are specified by putting the contents in
``double quotes''.
Variables are set using the set command (see ``COMMANDS'',
below). They are referenced in an expression by using the
form $varname. Some variables are set by default for each
notice. All other variables retain their values between
notice interpretations, so that if you set a variable, it
retains that value until later modified.
Functions are called using a C-like syntax,
fname(expr1,expr2), where fname is the function name and
exprn are the arguments.
Binary operators use infix notation, such as ``a == b''.
Some commands use an expression list (exprlist), which is
simply a set of expressions separated by whitespace (e.g.
$var1 ``lit1'' $var2).
The following variables are always available:
- 1, ...
Numeric variables are assigned values corresponding to
that field in the notice (the body of each notice is
conceptually an array of fields, each terminated with a
null character). If the number is greater than the
number of fields actually in the notice, the value is
``''. For example, the standard jwrite messages have two
fields: $1 is the signature, and $2 is the text of the
message.
- date
-
The date on which the notice was sent.
- error
-
An error message from the port read/write commands.
- event
-
Event markers for messages, such as ``composing''.
- from
-
The full jabber id of the user that sent the current notice.
- longdate
-
The date on which the notice was sent, in a longer format.
- message
-
The full text of the message, with nulls converted to
newlines.
- nickname
-
The nickname associated with the jabber id of the user
that sent the current notice, if present.
- number_of_fields
-
The number of fields in the message (a string represen-
tation of a decimal number).
- output_driver
-
The name of the output driver in use.
- resource
-
The resource set by the user that sent the current notice.
- sender
-
Only the username of the user that sent the current notice.
- server
-
Only the server hostname of the user that sent the current notice.
- show
-
This is a piece of type: presence notices, and can be used to
indicate more information about the user's presence.
- status
-
This is a piece of type: presence notices, and can be used to
indicate more information about the user's presence.
- subject
-
The subject of the messaage.
- subtype
-
The jabber notice subtype of the current notice. This depends fairly
highly on what type the message is.
- time
-
The time of day at which the notice was sent, in 24-hour format.
- time12
-
The time of day at which the notice was sent, in 12-hour format.
- type
-
The jabber notice type of the current notice. This can be message,
presence, or some other variety of notice.
All of these variables (except for error, output_driver, and
version) are re-set before each notice is processed.
Following is a list of functions available for use in the
description file.
- buffer()
-
The contents of the current output buffer.
- downcase(expr)
-
Returns the value of expr, converted to lower case.
- get(expr)
-
Returns a line from the port named expr. If there is
no text waiting on the port (e.g. the program connected
to the port has not printed any output), this function
will wait until it can read a line of text from the
port.
- getenv(expr)
-
Returns the value of the environment variable expr, or
the empty string if it does not exist.
- lany(expr1, expr2), rany(expr1, expr2)
-
Return a number of characters equal to the length of
expr2 from the beginning (lany) or end (rany) of expr1
(e.g.
lany(``1234567890'',``foo'') would return ``123''). If
expr1 is a variable reference, the variable is modified
to remove the characters returned. If expr2 is longer
than expr1, the value of expr1 is returned (and expr1
is set to ``'', if a variable).
- lbreak(expr1, expr2), rbreak(expr1, expr2)
-
Expr2 defines a set of characters. The function
returns the longest initial (lbreak) or final (rbreak)
string from expr1 composed of characters not in this
set (e.g. lbreak(``characters'', ``tuv'') would return
``charac''). If expr1 is a variable reference, the
variable is modified to remove the characters returned.
If no characters in expr2 are in expr1, then expr1 is
returned (and expr1 is set to ``'', if a variable).
- lspan(expr1, expr2), rspan(expr1, expr2)
-
These functions are the negation of the break func-
tions; the returned string consists of characters in
the set defined by expr2
- protect(expr)
-
Returns a string which will be evaluated identically to
expr, but will not affect any surrounding environments.
That is, any characters which could close outside
environments are quoted, and any environments in expr
which are not closed at the end are closed.
- substitute(expr)
-
Evaluates variable references of the form $variable in
expr and converts $$ to $.
- upcase(expr)
-
Returns the value of expr, converted to upper case.
- verbatim(expr)
-
Returns a string that will be displayed exactly as expr
looks. Anything which could be mistaken for an
environment is quoted.
- jvar(expr)
-
Returns the value of the jabber variable expr, or the
empty string if it does not exist.
Following is a list of operators which can be used in the
description file to compose expressions:
- expr1 + expr2
-
String concatenation of expr1 and expr2
- expr1 == expr2
-
True if the two expressions are equal, false otherwise.
- expr =~ expr2
-
True if the regular expression pattern expr2 matches
expr1.
- expr1 !~ expr2
-
Negation of ``=~''.
- expr1 != expr2
-
Negation of ``==''
- expr1 and expr2, expr1 & expr2
-
True if expr1 and expr2 are both true.
- expr1 or expr2, expr1 | expr2
-
True if either of expr1 or expr2 are true.
- ! expr1, not expr1
-
The logical negation of expr1.
Following is a list of the commands usable in the descrip-
tion language:
- appendport expr1 expr2
-
Creates a port called expr1. All output to the port
will be appended to the file expr2. There is no input.
If the file is created, its mode is set to read-write,
owner only (no access for others).
- break
-
Exits the innermost if, case, or while block.
- case expr1 [ ((match expr [,expr ...]) | default) commands ] ... endcase
-
Evaluates expr1. Then, each of the match expressions
is evaluated in order. The first time an expression
matches expr1, then the body of commands under it is
executed, and the rest of the case statement is
skipped. This compare is case-insensitive. default
always matches, so it should always appear as the last
set of commands. See the default description file for
an example of use.
- clearbuf
-
Clears the output buffer (see below for details on
buffering).
- closeinput expr
-
Closes the file associated with expr.
- closeoutput expr
-
Sends an EOF (end-of-file) to the process if expr was a
port created by execport, or closes the file if it was
created by outputport or appendport.
- closeport expr
-
Closes both input and output of expr as defined above.
- fields variable1 ...
-
sets the list of variables to be equal to the fields in
the notice. If there are more variables than fields,
the extra variables are left empty.
- exec exprlist
-
Executes a program without any input or output. A com-
mand named by exprlist is executed. Each expression is
used as an argument to the program; the first expres-
sion names the program (it may be either an absolute
pathname, or a program name; the user's PATH is
searched to find simple program names).
- execport expr1 exprlist
-
Creates a port called expr1. A command named by
exprlist is executed, as described above for exec. All
output to the port is sent to the standard input of the
process. Reading from the port will return the stan-
dard output of the process.
- exit
-
Completes processing of the current notice. The
remainder of the description file is ignored after exe-
cution of this command.
- if expr1 then commands1 [elseif expr2 then commands2] ... [else commandsn] endif
-
If expr1 evaluates to true, execute commands1, etc. [A
conditional construct, similar to the constructs in the
C shell (csh).]
- inputport expr1 expr2
-
Creates a port called expr1. All input from the port
comes from the file expr2. There is no output.
- noop
-
does nothing
- outputport expr1 expr2
-
Creates a port called expr1. The file expr2 will be
truncated, or created if it does not exist. All output
to the port will be appended to the file expr2. There
is no input. If the file is created, its mode is set
to read-write, owner only (no access for others).
- print expr1 ...
-
adds the values of the expressions to the current out-
put buffer. The values of the expressions are
separated by spaces in the output.
- put [expr [exprlist]]
-
Sends data to a port. If expr is provided, then it is
used as the port, otherwise the port used is the port
corresponding to the default output device. If
exprlist is provided, the expressions in the list are
sent to the port, separated by spaces. If it is omit-
ted, then the contents of the output buffer are sent as
the data.
- set variable = expr
-
sets variable equal to expr. Variable can later be
referenced by $variable.
- show text endshow
-
Appends text to the output buffer. This command is
special, because the string does not need to be quoted.
Whitespace at the beginning or end of the lines of text
is ignored. The endshow must appear as the first token
on a line (it may only be preceded on that line by whi-
tespace). Variable substitutions and formatting com-
mands (but not expressions or functions) are processed
in the text. Example:
show
this is some text
from: $sender
endshow
- while expr do statements endwhile
-
Executes statements until expr is false.
Ports are an abstraction encompassing all I/O forms of which
jwgc is capable. There are pre-existing output ports
corresponding to each of the output devices, and more ports
can be created with the port commands described above.
The output is usually collected in the output buffer and
saved until a put command sends the output to an output dev-
ice (such as an X display or a terminal). The output buffer
is implicitly cleared after each notice is completely pro-
cessed.
Output devices are implemented as output ports. A message
is displayed in a device-dependent manner when a string is
output to the port corresponding to the output device. For-
matting commands are embedded in the text as @ commands of
the form @command(text). Command names are case-insensitive
and consist of alphanumeric characters and underscores.
Valid brackets are () [] {} and <>. If the command name is
empty (such as in ``@(foo)''), then a new environment with
no changes is created (This is useful to temporarily change
some parameter of the output, such as the font).
The following output devices are supported:
- stdout
-
Sends the string to standard output exactly as is.
- stderr
-
Sends the string to standard error exactly as is.
- plain
-
Sends the string with all formatting environments
removed to standard output.
- tty
-
Does formatting on the message according to @ commands
embedded in the text. The output, with appropriate
mode-changing sequences, is sent to the standard out-
put. The appropriate characteristics of the display
are taken from the TERMCAP entry (see
termcap(5)) for
the terminal named by the TERM environment variable.
Supported @ commands are:
- @roman
-
Roman (plain) letters (turns off all special modes).
- @b or @bold
-
Bold letters. If not available, reverse video, else underline.
- @i or @italic
-
Italic letters (underlining, if available).
- @beep
-
``bl'' termcap entry, else ``^G'' (beep the terminal);
limited to once per message.
- @l or @left
-
left aligned
- @c or @center
-
center aligned
- @r or @right
-
right aligned
Other @-commands are silently ignored.
- X
-
Displays one window per string output to the port. The
output is formatted according to @ commands embedded in
the string. Supported @ commands are:
- @roman
-
turns off @italic and @bold
- @b or @bold
-
turns on boldface
- @i or @italic
-
turns on italics
- @l or @left
-
left aligned
- @c or @center
-
center aligned
- @r or @right
-
right aligned
- @large
-
large type size
- @medium
-
medium type size
- @small
-
small type size
- @beep
-
Ring the X bell (limited to once per message)
- @font
-
sets the current font to the font specified in the contents of the
environment (e.g. @font(fixed)). This will remain in effect for the
rest of the environment (a temporary change can be achieved by
enclosing the font-change in an @(...) environment). If the named
font is not available, the font ``fixed'' is used instead.
- @color
-
sets the color to the color specified in the contents of the
environment. The color name should appear in the X color name data-
base. This color will remain in effect for the rest of the environ-
ment. If the named color is not available, the default foreground
color is used.
Any other environment name not corresponding to the
above environment names will set the current ``sub-
style.''
The attributes of a given block of text are determined
by any active environments, evaluated in the context of
the current style and substyle.
The style is specific to each window. Its name has
three dot (``.'') separated fields, which are by
default the values of the class, instance, and reci-
pient variables, with all dots changed to underscores
(``_'') and all letters converted to lowercase. The
style can be altered by setting the style variable.
Note that it must always have exactly two ``.'' char-
acters in it.
The substyle is determined by @ commands in the message
text.
Jwgc variables which the X output device reads are:
- default_X_geometry
-
default geometry for notices, set from resources
- X_geometry
-
overrides geometry in resource file, if set
- default_X_background
-
default background color for notices, set from resources
- X_background
-
overrides bgcolor in resource file, if set
- style
-
style, as described above
The expected geometry values are described below.
The fonts and color for a piece of text are determined
by the styles defined in the X resources file. The
following resources relating to text style are used by
jwgc:
- jwgc.style.stylenames.geometry
-
geometry for messages of the specified style
- jwgc.style.stylenames.background
-
background color for messages of the specified style
- jwgc.style.stylenames.substyle.substylename.fontfamily
-
fontfamily name for the specified style and substyle
- jwgc.style.stylenames.substyle.substylename.foreground
-
foreground color for the specified style and substyle
- jwgc.fontfamily.fontfamilyname.size.face
-
specifies the fonts for a given fontfam- ily. size
is one of small, medium, or large, and face is one of roman, bold,
italic, or bolditalic.
The best way to get started in customizing X resources
for jwgc is to examine the default application
resources and other users' resources to understand how
they specify the default appearance.
Other X resources used by jwgc are listed below. Entries
like
jwgc*option: value
Jwgc*option: value
jwgc.option: value
*option: value
will work.
An entry labeled with jwgc*option in any of the sources
takes precedence over Jwgc*option, which takes precedence
over *option entries. The following sources are searched in
order:
command-line arguments (-xrm)
contents of file named by XENVIRONMENT environment variable
X server resource database (see xrdb(1))
application resources file
Logical values can be ( Yes On True T ) or ( No Off False
nil ).
- cursorCode
-
number of a code from the cursorfont (should
be an even integer, see <X11/cursorfont.h>)
to use for the windows.
- 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 foreground or
background).
- ReverseVideo
-
Secondary toggle, if reverseVideo is not set.
[off is the default if neither is set]
- borderWidth
-
Primary border width selector
- BorderWidth
-
Secondary border width selector (if bor-
derWidth is not set) [1 is the default value
if neither is set]
- internalBorder
-
Primary border between edge and text
- InternalBorder
-
Secondary selector (if internalBorder not
set) [2 is the default value if neither is
set]
- geometry
-
Primary POSITION (not size) geometry specif-
ier. The geometry should be of the form
``{+|-}x{+|-}y'', specifying an (x,y)
coordinate for a corner of the window
displaying the notice. The interpretation of
positive and negative location specifications
follows the X conventions. A special loca-
tion of `c' for either x or y indicates that
the window should be centered along that
axis. Example: a geometry of ``+0+c'' speci-
fies the window should be at the top of the
screen, centered horizontally.
- Geometry
-
Secondary position specifer. [+0+0 is the
default if neither is set.]
- resetSaver
-
(logical) Primary value to force screen to
unsave when a message first appears.
- ResetSaver
-
(logical) Secondary value to force screen to
unsave. [default True]
- reverseStack
-
(logical) Primary value to specify that jwgc
should attempt to stack WindowGram windows
such that the oldest messages normally show
on top. Some X window managers may silently
ignore jwgc's attempts to restack its win-
dows. This option can cause some unusual
interactions with other windows if the user
manually restacks either the other windows or
the WindowGram windows.
- ReverseStack
-
Secondary value to enable reverse stacking.
[default False]
- title
-
(string) Primary window title
- Title
-
Secondary window title [defaults to the last
pathname component of the program name, usu-
ally ``jwgc'']
- transient
-
(logical) Primary value which determines if
jwgc windows will be created with the
WM_TRANSIENT_FOR property set. If this
resource is true, the property will be set,
telling certain windowmanagers to treat
jwgc windows specially. For instance,
twm will not put decorations on transient
windows, mwm will not let you iconify them,
and uwm ignores the resource entirely.
- Transient
-
Secondary transient determining value
[default False]
- enableDelete
-
(logical) If true, jwgc creates a
WM_PROTOCOLS property on all jgrams, with
WM_DELETE_WINDOW as contents.
- EnableDelete
-
Secondary value to enable WM_DELETE_WINDOW
protocol on jgrams [default False]
- minTimeToLive
-
Primary value which specifies the minimum
amount of time (``minimum time to live'') a
WindowGram must be on-screen (in mil-
liseconds) until it can be destroyed. This
feature is useful to avoid accidentally
clicking on new WindowGrams when trying to
delete old ones.
- MinTimeToLive
-
Secondary value of ``minimum time to live.''
- iconName
-
(string) Primary icon name
- IconName
-
Secondary icon name [defaults to the last
pathname component of the program name, usu-
ally ``jwgc'']
- name
-
(string) Primary window class name
- name
-
Secondary window class name [defaults to the
last pathname component of the program name,
usually ``jwgc'']
- synchronous
-
(logical) Primary X synchronous mode specif-
ier. On means to put the X library into syn-
chronous mode.
- Synchronous
-
Secondary X synchronous mode specifier.
[default is `off']
The window class is always ``Jwgc''.
Clicking and releasing any button without the shift key
depressed while the pointer remains inside a WindowGram win-
dow will cause it to disappear. If the pointer leaves the
window while the button is depressed, the window does not
disappear; this provides a way to avoid accidentally losing
messages.
If the control button is held down while clicking on a Win-
dowGram, then that WindowGram and all windowgrams under the
point where the button is released will be erased.
Portions of the text of a message may be selected for ``past-
ing'' into other X applications by using the shift key in
cooperation with the pointer buttons. Holding the Shift key
while depressing Button1 (usually the left button) will set
a marker at the text under the pointer. Dragging the
pointer with Shift-Button1 still depressed extends the
selection from the start point, until the button is
released. The end of the selection may also be indicated by
releasing Button1, holding down the Shift key, and pressing
Button3 (usually the right button) at the desired endpoint
of the selection. The selection will appear with the text
and background colors reversed.
If jwgc receives a WM_DELETE_WINDOW, it destroys the jwgc
window as if it were clicked on.
If a jwgc window is unmapped, it is removed from the stacking
order used by reverseStack.
- jwgc.desc
-
This is the default jwgc description file, read if a user's own
.jwgc.desc does not exist. This is more or less required to
exist, unless you plan on automatically putting a .jwgc.desc
in everyone's home directory by default.
- jwgc.vars, jwgc.vars.fixed
-
These contain default jwgc variable settings. Neither are required
to exist, nor contain any actual settings. Any settings in
jwgc.vars.fixed can -not- be changed by .jwgc.vars, jwgc.vars,
or command line options.
- .jwgc.vars, .jwgc.desc
-
These are the user (personal) variable and description files. If
a user wishes to customize jwgc, they should create these files
in their home directory.
- jwgc_resources
-
This contains the default X resources for jwgc. These can be
in a variety of ways, all explained in X windows documentation.
jwrite(1), jctl(1), jlocate(1), jstat(1)
Daniel Henninger jadestorm@users.sourceforge.net.
Copyright (c) 2002 Daniel Henninger. All right reserved.
This program is free software; you can redistribute
it and/or modify it under the terms explained in the LICENSE
file that comes with the jwgc distribution. The bulk of this
documentation is taken almost directly from MIT's zwgc man page.
I may have reworded a fair amount of it, but it's by far not my
original work.