.TH TKABBER-REMOTE 1 "2014-10-20" "1.1-1" "Instant Messaging Clients"
.SH NAME
tkabber\-remote \- remotely control a running instance of Tkabber

.SH SYNOPSIS

.PP
\fBtkabber-remote\fR [\fBoptions\fP] \-eval \fIscript\fP
.PP
\fBtkabber-remote\fR [\fBoptions\fP] \-command \fIcommand\fP

.SH DESCRIPTION

.PP
Tkabber is a GUI client for XMPP (Jabber) instant messaging
protocol. It provides full support for basic XMPP specifications
as well as many extensions (XEPs) including multi-user conferencing,
file transfers, extensive handling of privacy lists and much more.
Tkabber is written in Tcl/Tk and thus is easily extensible.
.PP
The \fBtkabber\-remote\fP program can be used to remotely control
a running instance of Tkabber by sending it predefined commands
or Tcl scripts for execution.
.PP
This manual page was written for the \fBDebian\fP distribution
because the original program does not have a manual page.

.SH OPTIONS

.IP "\fB\-user\fP \fIuser\fP"
Makes the program control Tkabber run by the specified user
instead of the user who runs \fBtkabber-remote\fP.
.IP "\fB\-pid\fP \fIPID\fP"
Makes the program control Tkabber process with the specified identifier (PID)
instead of all the instances found.

.SH "EXECUTING SCRIPTS"

To make a running Tkabber instance execute an arbitrary Tcl script
use the \fB\-eval\fP command\-line option followed by that script's text.
(The script's text must form a single argument passed to this program,
so proper quoting should be used, if necessary, when calling
\fBtkabber\-remote\fP from a shell).

.PP
Executing a script prints the PID of the process which received
and executed the script, and then the string representation of the Tcl
value the script returned.

.SH "EXECUTING COMMANDS"

.PP
The commands which can be used with the \fB\-command\fP command\-line
options are:

.IP "\fBlist\-commands\fP"
Prints a list of all the commands supported by the \fB\-command\fP
command\-line option.

.IP "\fBset\-proxy\-profile\fP \fIprofile\fP"
Sets an active network proxy profile by its name.
The profile must be already configured.

.IP "\fBset\-status\fP \fIstatus\fP [\fItextstatus\fP]"
Sets the availability (presence) status of the user.

.RS

.PP
Available status codes are:

.IP available
The user is available.

.IP away
The user is temporarily away.

.IP chat
The user is actively interested in chatting.

.IP dnd
The user does not want to be disturbed (dnd = "Do Not Disturb").

.IP xa
The user is away for an exteneded period of time (xa = "eXtended Away").

.PP
The optional \fItextstatus\fP argument can be used to set a textual
message which accompanies the availability status.
(The message's text must form a single argument,
so proper quoting should be used, if necessary, when calling
\fBtkabber\-remote\fP from a shell).

.PP
Note that sending this command while the receiving Tkabber instance
is offline (not connected) will not make it connect; the status will
merely be recorded and announced when Tkabber goes online.

.RE

.PP
Executing a command prints the PID of the process which received
and executed the command, and then the string representation of the Tcl
value the command returned.

.SH "SEE ALSO"

.BR tkaber (1)
.BR tkabber-plugins (7)

.SH AUTHOR
.PP
This manual page was written by
Konstantin Khomoutov <flatworm@users.sourceforge.net>
for the \fBDebian\fP system (but may be used by others).
Copying and distribution of this document, with or without
modification, are permitted in any medium without royalty
provided the copyright notice and this notice are
preserved.