X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/blobdiff_plain/ca83183166cfcc9e6cfa412a2d870746e9dad5ae..9646482db2f5429ce1bcbeaebeb85c9c1b9af87c:/doc/disorder.1.in

diff --git a/doc/disorder.1.in b/doc/disorder.1.in
index a05ca8c..784083c 100644
--- a/doc/disorder.1.in
+++ b/doc/disorder.1.in
@@ -1,20 +1,18 @@
 .\"
-.\" Copyright (C) 2004, 2005, 2006 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
@@ -22,16 +20,9 @@ disorder \- DisOrder jukebox client
 .SH SYNOPSIS
 .B disorder
 .RI [ OPTIONS ]
-.RB [ -- ]
+.RB [ \-\- ]
 .RI [ COMMANDS ...]
-.br
-.B disorder
-.B --length
-.RI [ OPTIONS ]
-.RB [ -- ]
-.IR PATH ...
 .SH DESCRIPTION
-Without the \fB--length\fR option,
 .B disorder
 is used to query the \fBdisorderd\fR(8) daemon from the command line.
 It may be used to request tracks, scratch tracks, query the current
@@ -39,40 +30,69 @@ state, etc, and by an administrator to shutdown or reconfigure the
 daemon.
 .PP
 If no commands are specified then \fBdisorder\fR connects to the
-daemon and then immediately disconnects.  This can be used to test
-whether the daemon is running.  Otherwise, it executes the commands
-specified.
+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
-Set the configuration file.  The default is
+.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 --length\fR, \fB-L
-Calculate the length in seconds of the files specified using the tracklength
-plugin.
-.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 \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 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~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 \fIUSERNAME\fR
+Delete a user.
+.TP
 .B dirs \fIDIRECTORY\fR [\fB~\fIREGEXP\fR]
 List all the directories in \fIDIRECTORY\fR.
 .IP
-An optional regexp may be specified, marked with an initial \fB~\fR.  Only
-directories with a basename matching the regexp will be returned.
+An optional regexp may be specified, marked with an initial \fB~\fR.
+Only directories with a basename matching the regexp will be returned.
 .TP
 .B disable
-Disables playing after the current track finishes.
+Disable playing after the current track finishes.
+.TP
+.B edituser \fIUSERNAME PROPERTY VALUE
+Set some property of a user.
 .TP
 .B enable
 (Re-)enable playing.
@@ -80,23 +100,25 @@ Disables playing after the current track finishes.
 .B files \fIDIRECTORY\fR [\fB~\fIREGEXP\fR]
 List all the files in \fIDIRECTORY\fR.
 .IP
-An optional regexp may be specified, marked with an initial \fB~\fR.  Only
-files with a basename matching the regexp will be returned.
+An optional regexp may be specified, marked with an initial \fB~\fR.
+Only files with a basename matching the regexp will be returned.
 .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
-Displays the current volume settings.
+.B get\-volume
+Display the current volume settings.
 .TP
 .B length \fITRACK\fR
-Reports the length of \fITRACK\fR in seconds.
+Display the length of \fITRACK\fR in seconds.
 .TP
 .B log
-Writes event log messages to standard output, until the server is terminated.
+Write event log messages to standard output, until the server is terminated.
 See \fBdisorder_protocol\fR (5) for details of the output syntax.
 .TP
 .B move \fITRACK\fR \fIDELTA\fR
@@ -104,22 +126,25 @@ Move
 .I TRACK
 by
 .I DELTA
-within the queue.  Positive values move towards the head of the queue, negative
+within the queue.
+Positive values move towards the head of the queue, negative
 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
 .B part \fITRACK\fR \fICONTEXT\fI \fIPART\fR
 Get a track name part.
 .IP
-\fICONTEXT\fR should be either \fBsort\fR or \fBdisplay\fR.  \fBpart\fR is the
-part of the name desired, typically \fBartist\fR, \fBalbum\fR or \fBtitle\fR.
+\fICONTEXT\fR should be either \fBsort\fR or \fBdisplay\fR.
+\fBpart\fR is the part of the name desired, typically \fBartist\fR,
+\fBalbum\fR or \fBtitle\fR.
 .TP
 .B pause
-Pause the current track.  (Note that not all players support pausing.)
+Pause the current track.
+(Note that not all players support pausing.)
 .TP
 .B play \fITRACKS\fR...
 Add \fITRACKS\fR to the end of the queue.
@@ -129,58 +154,123 @@ Report the currently playing track.
 .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.
+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
-List recently played tracks.  The first entry is the oldest track, the last
-entry is the most recently played one.
+List recently played tracks.
+The first entry is the oldest track, the last entry is the most
+recently played one.
+.TP
+.B reconfigure
+Make the daemon reload its configuration file.
 .TP
 .B remove \fITRACK\fR
 Remove a track from the queue.
 .TP
+.B rescan
+Rescan the filesystem for new tracks.
+There is an automatic daily rescan but if you've just added some tracks
+and want them to show up immediately, use this command.
+.TP
 .B resolve \fITRACK\fR
 Resolve aliases for \fITRACK\fR and print out the real track name.
 .TP
 .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
-Search for tracks containing all of the listed terms.  The terms are
-separated by spaces and form a single argument, so must be quoted,
-for example:
+Search for tracks containing all of the listed terms.
+The terms are separated by spaces and form a single argument,
+so must be quoted, for example:
 .IP
 .B "disorder search 'bowie china'"
 .IP
 You can limit the search to tracks with a particular tag, too, using the
-\fBtag:\fR modifier.  For example:
+\fBtag:\fR modifier.
+For example:
 .IP
 .B "disorder search 'love tag:depressing'"
 .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
+Set the volume.
 .TP
-.B set-volume \fBLEFT\fR \fBRIGHT\fR
-Sets the volume.
+.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
+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
+configuration file.
+See \fBdisorder_config\fR(5).
+.TP
+.B shutdown
+Shut down the daemon.
 .TP
 .B stats
 List server statistics.
@@ -190,9 +280,17 @@ List known tags.
 .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 \fIUSERNAME PROPERTY
+Get some property of a user.
+.TP
+.B users
+List known users.
 .TP
 .B version
 Report the daemon's version number.
@@ -201,92 +299,32 @@ For
 .B move
 and
 .BR remove ,
-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.
-.SS "Privileged Commands"
-These commands are only available to privileged users.
-.TP
-.B become \fIUSER\fR
-Become another user.
-.TP
-.B reconfigure
-Make the daemon reload its configuration file.
-.TP
-.B rescan
-Rescan the filesystem for new tracks.  There is an automatic daily rescan but
-if you've just added some tracks and want them to show up immediately, use this
-command.
-.TP
-.B shutdown
-Shut down the daemon.
-.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 "Superuser Commands"
-These commands will (generally) only work for root, who must be a privileged
-user.
-.TP
-.B authorize \fIUSER\fR
-Chooses a password for \fIUSER\fR and adds it to \fIconfig.private\fR.  Also
-creates an appropriate \fIconfig.USER\fR, be owned by the user.
-.IP
-If at least one \fBauthorize\fR command succeeds then the server is
-automatically told to re-read its configuration.
+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 NOTES
 .B disorder
-is locale-aware.  If you do not set the locale correctly then it may
-not handle non-ASCII data properly.
+is locale-aware.
+If you do not set the locale correctly then it may not handle non-ASCII
+data properly.
+.PP
+The client determines which user to attempt to authenticate as by examining the
+current UID.
+This can be overridden in a per-user configuration file, see
+\fBdisorder_config\fR(5).
 .PP
-The client determines which user to attempt to authenticate as by
-examining the current UID.
+See \fBdisorder_protocol\fR(5) for the rights required to run each command.
+(For instance, \fBshutdown\fR requires the \fBadmin\fR right, which most users
+would not normally have.)
 .PP
 This program is not intended to run in a setuid environment.
 .PP
 The regexp syntax used by the \fBfiles\fR and \fBdirs\fR commands use the
-syntax described in \fBpcrepattern\fR(3).  Matching is case-independent.  It is
-strongly recommended that you quote regexps, since they often contain
-characters treated specially by the shell.  For example:
+syntax described in \fBpcrepattern\fR(3).
+Matching is case-independent.
+It is strongly recommended that you quote regexps, since they often
+contain characters treated specially by the shell.
+For example:
 .PP
 .B "disorder dirs /Music ~'^(?!the [^t])t'"
 .SH TROUBLESHOOTING
@@ -304,8 +342,8 @@ though this depends on local configuration.
 .B .
 Is the track in a known format?  Have a look at
 .I pkgconfdir/config
-for the formats recognized by the local installation.  The filename matching is
-case-sensitive.
+for the formats recognized by the local installation.
+The filename matching is case-sensitive.
 .TP
 .B .
 Do permissions on the track allow the server to read it?
@@ -315,22 +353,22 @@ Do the permissions on the containing directories allow the server to read and
 execute them?
 .PP
 The user the server runs as is determined by the \fBuser\fR directive in the
-configuration file.  The README recommends using \fBjukebox\fR for this purpose
-but it could be different locally.
+configuration file.
+The README recommends using \fBjukebox\fR for this purpose but it could
+be different locally.
 .SH ENVIRONMENT
 .TP
-.B LOGNAME
-The default username.
-.TP
 .B HOME
 The user's home directory.
 .TP
 .B LC_ALL\fR, \fBLANG\fR, etc
-Current locale.  See \fBlocale\fR(7).
+Current locale.
+See \fBlocale\fR(7).
 .SH FILES
 .TP
 .I pkgconfdir/config
-Global configuration file.  See \fBdisorder_config\fR(5).
+Global configuration file.
+See \fBdisorder_config\fR(5).
 .TP
 .I ~/.disorder/passwd
 Per-user password file
@@ -339,7 +377,8 @@ Per-user password file
 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: