.\"  $HeadURL$ $LastChangedRevision$
.\"
.TH SWITCHER 1 "SPPSYM_RELEASE_DATE_MAN"
.ne 5
.SH NAME
switcher \- specify alternate commands in environment
.br
.br
.ne 5
.SH SYNOPSIS
.I program
[
.B \-V
|
.B \-\-version
] [
.B \-v
|
.B \-\-verbose
|
.B \-d
.I level
|
.B \-\-debug=\fIlevel
] [
.B \-h
|
.B \-\-help
] [
.B \-p
|
.B \-\-list\-paths
] 
[ 
.B \-\-say
.I text
]
.br
.ne 5
.SH DESCRIPTION
This manual page documents version SPPSYM_RELEASE_ID of
.B switcher\fR.
.PP
.B Switcher
is a generic script to allow invoking one command instead of another. In this
respect it is the same as shell aliases or functions. But unlike these facilities
it works not only when invoked from an interactive shell. 
.PP
.B Switcher
was originally written because the author wanted to trick 
.B BitchX\fR(1) 
into running an 
.B rxvt\fR(1)
instead of an 
.B xterm\fR(1).
.B Switcher
determines the command to actually be invoked by reading the contents of the
environment variable
.B SWITCHED_\fIcmd\fR,
where
.I cmd
is the name of the command that is actually specified.
.ne 5
.SH CONFIGURATION
Following the above example, and assuming 
.B $HOME/bin
is specified in 
.B $PATH\fR,
the following commands must be run:
.IP
.nf
.fam C
cd $HOME/bin
ln -s `which switcher` xterm
SWITCHED_xterm=rxvt
export SWITCHED_xterm
.fam T
.fi
.ne 5
.SH OPTIONS
.TP 25
.B \-d \fIlevel\fR, \fB\-\-debug=\fIlevel\fR
Determines how verbose
.B switcher
will be. The message types displayed for the different values of 
.I level
are as follows:
.RS 25
.TP 5
.B 0
internal errors only
.TP
.B 1
internal errors and normal errors 
.TP
.B 2
internal errors, normal errors and warnings
.TP 
.B 3
internal errors, normal errors, warnings and informational messages
.TP 
.B >3
all the above plus application-specific debug messages.
.RE
.TP 25
.B \-h\fR, \fB\-\-help
Displays a brief usage message.
.TP
.B \-p\fR, \fB\-\-list\-paths
List the compiled-in paths of various files and directories that
.B switcher
uses.
.TP
.B \-\-say \fItext
With this option
.B switcher
behaves just like
.B echo\fR(1).
Its purpose is to help
.B switcher
determine that the command it is invoking is not itself!
.TP 
.B \-v\fR, \fB\-\-verbose
Equivalent to
.B \-d 3\fR.
.TP
.B \-V\fR, \fB\-\-version
Print the program's version number and exit.
.br
.ne 5
.SH EXIT STATUS
On success
.B switcher
returns zero. On failure it returns non-zero and displays a diagnostic
message.
.br
.ne 5
.SH FILES
None.
.br
.ne 5
.SH ENVIRONMENT VARIABLES
.TP 25
.B SWITCHED_\fIcmd
This variable's name specifies the command that is being substituted,
and its value specifies the command that will be invoked in its place.
.br
.ne 5
.SH EXAMPLES
See CONFIGURATION above.
.br
.ne 5
.SH CAVEATS
None.
.br
.ne 5
.SH SEE ALSO
BitchX(1), echo(1), gvim(1), rxvt(1), xterm(1), vi(1)
.br
.ne 5
.SH AUTHOR
SPPSYM_AUTHOR_NAME <SPPSYM_AUTHOR_EMAIL>
.br
.ne 5
.SH COPYRIGHT & DISTRIBUTION POLICY
Copyright (C) 1999-SPPSYM_RELEASE_YEAR SPPSYM_AUTHOR_NAME
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.PP
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
.PP
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.