.\"
-.\" Copyright (C) 2004, 2005, 2006, 2007 Richard Kettlewell
+.\" Copyright (C) 2004-2008 Richard Kettlewell
.\"
-.\" This program is free software; you can redistribute it and/or modify
+.\" 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
+.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
-.\"
-.\" 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.
-.\"
+.\"
+.\" 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.
+.\"
.\" 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., 59 Temple Place, Suite 330, Boston, MA 02111-1307
-.\" USA
+.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
.\"
.TH disorder 1
.SH NAME
.SH SYNOPSIS
.B disorder
.RI [ OPTIONS ]
-.RB [ -- ]
+.RB [ \-\- ]
.RI [ COMMANDS ...]
.SH DESCRIPTION
.B disorder
daemon and then immediately disconnects.
This can be used to test whether the daemon is running.
Otherwise, it executes the commands specified.
+.PP
+This man page documents the command-line client.
+See \fBdisorderd\fR (8) for information about the server process
+and \fBdisorder_config\fR (5) for documentation of the configuration file.
.SH OPTIONS
.TP
-.B --config \fIPATH\fR, \fB-c \fIPATH
+.B \-\-config \fIPATH\fR, \fB\-c \fIPATH
Set the configuration file.
The default is
.IR pkgconfdir/config .
.TP
-.B --debug\fR, \fB-d
+.B \-\-debug\fR, \fB\-d
Enable debugging.
.TP
-.B --help\fR, \fB-h
+.B \-\-help\fR, \fB\-h
Display a usage message.
.TP
-.B --version\fR, \fB-V
+.B \-\-version\fR, \fB\-V
Display version number.
.TP
-.B --help-commands\fR, \fB-H
+.B \-\-help\-commands\fR, \fB\-H
List all known commands.
.SH COMMANDS
.TP
-.B adduser \fIUSER PASSWORD\fR [\fIRIGHTS\fR]
+.B adduser \fIUSERNAME PASSWORD\fR [\fIRIGHTS\fR]
Create a new user.
If \fIRIGHTS\fR is not specified then the \fBdefault_rights\fR
setting from the server's configuration file applies.
.TP
-.B authorize \fIUSER\fR [\fIRIGHTS\fR]
-Create \fIUSER\fR with a random password.
-\fIUSER\fR must be a UNIX login user (not just any old string).
+.B adopt \fIID\fR
+Adopts track \fIID\fR (in the queue).
+The track will show up as submitted by the calling user.
+.TP
+.B authorize \fIUSERNAME\fR [\fIRIGHTS\fR]
+Create user \fIUSERNAME\fR with a random password.
+User \fIUSERNAME\fR must be a UNIX login user (not just any old string).
If \fIRIGHTS\fR is not specified then the \fBdefault_rights\fR
setting from the server's configuration file applies.
.IP
-\fI~USER/.disorder/passwd\fR is created with the password in it, so the new
+\fI~USERNAME/.disorder/passwd\fR is created with the password in it, so the new
user should be able to log in immediately.
.IP
If writing the \fIpasswd\fR file fails then the user will already have been
created in DisOrder's user database.
Use \fBdisorder deluser\fR to remove them before trying again.
.TP
-.B deluser \fIUSER\fR
+.B deluser \fIUSERNAME\fR
Delete a user.
.TP
.B dirs \fIDIRECTORY\fR [\fB~\fIREGEXP\fR]
.B disable
Disable playing after the current track finishes.
.TP
-.B edituser \fIUSER PROPERTY VALUE
+.B edituser \fIUSERNAME PROPERTY VALUE
Set some property of a user.
.TP
.B enable
.TP
.B get \fITRACK\fR \fIKEY\fR
Display the preference \fIKEY\fR for \fITRACK\fR.
+See \fBdisorder_preferences\fR (5).
.TP
-.B get-global \fIKEY\fR
+.B get\-global \fIKEY\fR
Get a global preference.
+See \fBdisorder_preferences\fR (5).
.TP
-.B get-volume
+.B get\-volume
Display the current volume settings.
.TP
.B length \fITRACK\fR
values towards the tail.
.IP
Note that if you specify a negative value then the
-.B --
+.B \-\-
option separate (before all commands) becomes mandatory, as otherwise the
negative value is misinterpreted an an option.
.TP
.TP
.B prefs \fITRACK\fR
Display all the preferences for \fITRACK\fR.
+See \fBdisorder_preferences\fR (5).
.TP
.B queue
List the current queue.
The first entry in the list is the next track to play.
.TP
-.B random-disable
+.B random\-disable
Disable random play.
.TP
-.B random-enable
+.B random\-enable
Enable random play.
.TP
.B recent
.B resume
Resume the current track after a pause.
.TP
-.B rtp-address
+.B rtp\-address
Report the RTP brodcast address used by the server (if any).
.TP
+.B schedule-del \fIEVENT\fR
+Delete a scheduled event.
+.TP
+.B schedule-list
+List scheduled events.
+Each line contains the ID, a timestamp, 'N' or 'J' for normal or junk priority,
+the user, the action and action-specific data.
+.TP
+.B schedule-play \fIWHEN PRIORITY TRACK\fI
+Play \fITRACK\fR at time \fIWHEN\fR.
+Various time/date formats are supported depending on locale but the following
+three will always work:
+.RS
+.RS
+.TP
+.B "YYYY-MM-DD HH:MM:SS"
+.TP
+.B "HH:MM:SS"
+.TP
+.B "HH:MM"
+.RE
+.RE
+.IP
+\fIPRIORITY\fR should be \fBjunk\fR or \fBnormal\fR.
+This determines how the event is handled if it becomes due when the server is
+down.
+Junk events are just discarded in this case, while normal events will be
+executed when the server comes back up, even if this is much later.
+.TP
+.B schedule-set-global \fIWHEN PRIORITY NAME VALUE\fI
+Set global preference \fINAME\fR to \fIVALUE\fR at time \fIWHEN\fR.
+.TP
+.B schedule-unset-global \fIWHEN PRIORITY NAME\fI
+Unset global preference \fINAME\fR at time \fIWHEN\fR.
+.TP
.B scratch
Scratch the currently playing track.
.TP
-.B scratch-id \fIID\fR
+.B scratch\-id \fIID\fR
Scratch the currently playing track, provided it has the given ID.
.TP
.B search \fITERMS\fR
.TP
.B set \fITRACK\fR \fIKEY\fR \fIVALUE\fR
Set the preference \fIKEY\fR for \fITRACK\fR to \fIVALUE\fR.
+See \fBdisorder_preferences\fR (5).
.TP
-.B set-global \fIKEY\fR \fIVALUE\fR
+.B set\-global \fIKEY\fR \fIVALUE\fR
Set a global preference.
+See \fBdisorder_preferences\fR (5).
.TP
-.B set-volume \fBLEFT\fR \fBRIGHT\fR
+.B set\-volume \fBLEFT\fR \fBRIGHT\fR
Set the volume.
.TP
-.B setup-guest \fR[\fB--no-online-registration\fR]
+.B setup\-guest \fR[\fB\-\-no\-online\-registration\fR]
Create the "guest" user for use by the web interface.
This user will have no password and will only have the "read" and
"register" rights, the latter allowing new users to automatically
register themselves via the web interface.
.IP
-With the option \fB--no-online-registration\fR, the "register" right is
+With the option \fB\-\-no-online\-registration\fR, the "register" right is
suppressed and users must be manually created by an administrator.
.IP
If online registration is desired then \fBmail_sender\fR must be set in the
.TP
.B unset \fITRACK\fR \fIKEY\fR
Unset the preference \fIKEY\fR for \fITRACK\fR.
+See \fBdisorder_preferences\fR (5).
.TP
-.B unset-global \fIKEY\fR
+.B unset\-global \fIKEY\fR
Unset the global preference \fIKEY\fR.
+See \fBdisorder_preferences\fR (5).
.TP
-.B userinfo \fIUSER PROPERTY
+.B userinfo \fIUSERNAME PROPERTY
Get some property of a user.
.TP
.B users
tracks may be specified by name or by ID.
If you use the name and a track appears twice in the queue it is
undefined which is affected.
-.SH PREFERENCES
-Currently the following preferences are supported.
-Some are expected to be set by users, others updated automatically by plugins.
-.TP
-.B pick_at_random
-If this preference is present and set to "0" then the track will not
-be picked for random play.
-Otherwise it may be.
-.TP
-.B played
-A decimal integer giving the number times the track was played.
-This includes tracks that are scratched or were picked at random.
-.TP
-.B played_time
-The last time the track was played, as a \fBtime_t\fR converted to a
-decimal integer.
-.TP
-.B scratched
-The number of times the track has been scratched.
-.TP
-.B requested
-A decimal integer giving the number of times the track was requested.
-(Tracks that are removed before being played are not counted.)
-.TP
-.B tags
-Tags that apply to this track, separated by commas.
-Tags can contain any printing character except comma.
-Leading and trailing spaces are not significant but internal spaces are.
-.IP
-Using the
-.B required-tags
-and
-.B prohibited-tags
-global preferences, it is possible to limit the tracks that will be selected at
-random.
-.TP
-.B trackname_\fICONTEXT\fB_\fIPART\fR
-These preferences can be used to override the filename parsing rules
-to find a track name part.
-For backwards compatibility, \fBtrackname_\fIPART\fR will be used
-if the full version is not present.
-.TP
-.B unscratched
-The number of times the track has been played to completion without
-being scratched.
.SH NOTES
.B disorder
is locale-aware.
be different locally.
.SH ENVIRONMENT
.TP
-.B LOGNAME
-The default username.
-.TP
.B HOME
The user's home directory.
.TP
Communication socket for \fBdisorder\fR(1).
.SH "SEE ALSO"
\fBdisorderd\fR(8), \fBdisorder_config\fR(5), \fBsyslog\fR(3), \fBtime\fR(2),
-\fBpcrepattern\fR(3), \fBdisobedience\fR(1)
+\fBpcrepattern\fR(3), \fBdisobedience\fR(1), \fBdisorder.cgi\fR(8),
+\fBdisorder_preferences\fR(5)
.PP
"\fBpydoc disorder\fR" for the Python API documentation.
.\" Local Variables:
~mdw / disorder / blobdiff