# README for xcmd
# created 30-May-1997 jmk
# autodate: 1998-Mar-26 
# autotime: 22:53

DESCRIPTION:

Xcmd is a front-end for starting programs under X11.  You can tell xcmd
to look for a window with a specific class, resource name, or title
string (using the `--find-<property>' options); if it finds one or
more, xcmd will `raise' them, otherwise it will run the command you
specify. You can tell xcmd to run commands that create their own
windows (using `--xcmd'), or to run commands inside a terminal window
(using `--cmd') with various options.


CHANGES:

 * Revision 1.8  1998/03/27 03:47:33  jmknoble
 * bugfix: execl() wasn't getting called with NULL as last argument
 * (how did it ever work?).
 *
 * Revision 1.7  1998/01/04 03:54:56  jmknoble
 * Moved log to bottom of file.  Updated spec file for use with
 * rpm-2.3.9 and later.
 *
 * Revision 1.6  1998/01/04 03:53:52  jmknoble
 * Some window managers (notably WindowMaker) create and destroy
 * icon windows on the fly, and so if we've deiconified a window, and then
 * we encounter its window id further down the list of the root window's
 * children, we get BadWindow errors.  Therefore, we install our own
 * X error handler to ignore the error and keep processing.
 * Also, now we default to raising the window only instead of
 * iconifying it, then raising.
 * Minor code reformatting.
 *
 * Revision 1.5  1997/08/11 05:21:13  jmknoble
 * added command-line options to choose whether to
 * iconify-and-raise or raise-only when we
 * find a window; added environment variable
 * to specify same behavior.


NOTES:

Xcmd requires X11R6 and a functioning Imake to build properly.  You
might be able to build it on X11R5 by hacking the Imakefile a bit; if
you manage to, please send me patches and tell me what you did, and
i'll try to integrate them into the source.  Also, i have only tested
xcmd on Linux-2.0.x on an i586 machine.  Your mileage may vary.


INSTALLING:

For purists, untar and then:

    cd ./xcmd-1.8
    more README
    xmkmf -a
    make
    make install
    make install.man

For Red Hat Linux users and RPM junkies, there's a .spec file included
in the tarball which you can use to build a binary RPM if you have
rpm-2.3.9 or later:

    su
    rpm -tb xcmd-1.8.tar.gz

You can then install the binary RPM normally on your system.  This is
the recommended method of installation.


SYNTAX:

  xcmd version 1.8

  usage: xcmd [options] {--cmd | --xcmd} <command>

  execute <command>, with the option of finding and raising a prior
  instance instead of running a new one.  if `--cmd' is specified,
  execute <command> in a terminal window; if `--xcmd' is specified,
  execute <command> in its own window.

  general options:
    -c or --cmd <command>          command to run in a terminal window
    -d or --display <display>      X display to use
    -h or --help                   print this help
    -x or --xcmd <command>         command to run in its own window

  find options:
    -fc or --find-class <text>     class of window to raise
    -fr or --find-resource <text>  resource name of window to raise
    -fs or --find-substr <text>    title-substring to raise
    -ft or --find-title <text>     title of window to raise

  terminal window options (for --cmd):
    -t or --title <text>           title of window
    -i or --icon <text>            title of icon
    -n or --name <text>            name to retrieve resources under
    -g or --geometry <geometry>    geometry of terminal window
    -s or --scroll                 display scrollbar in terminal window
    +s or +scroll                  no scrollbar in terminal window
    -o or --opt <options>          options to pass to terminal program
    -rt or --rxvt                  use rxvt as terminal program
    -xt or --xterm                 use xterm as terminal program

  raise options:
    -ir or --iconify-and-raise     first iconify, then raise windows we find
    -or or --only-raise            only raise windows we find (default)

  environment variables:
    XCMD_TERM (default terminal program to use; `xterm' if not set)
    XCMD_ICONIFY (`0'/`no'/`false' => only raise windows we find [default];
                  `1'/`yes'/`true' => iconify window, then raise)


TECHNICAL NOTES:

Xcmd uses an execl(3) call to run `/bin/sh -c exec <command>', so that
<command> inherits xcmd's process ID.  Xcmd runs in the foreground by
default; use your favorite shell's regular syntax to start xcmd in the
background (e.g., `xcmd --find-title vi --cmd vi &' for
Bourne-compatible shells).


AUTHOR:

Jim Knoble <jmknoble@pobox.com>
Copyright  1997,1998 Jim Knoble

Xcmd is very loosely derived from portions of xwit by Mark Martin and
David DiGiacomo and xwininfo by Mark Lillibridge.  Almost none of the
original code remains.

Distributed under the GNU General Public License (GPL).  See
ftp://prep.ai.mit.edu/pub/gnu/COPYING for more details.

# -------- End of document --------
