Add SHELL=bash debian/rules for benefit of systems with rubbish default

[disorder] / doc / disorder_protocol.5.in

diff --git a/doc/disorder_protocol.5.in b/doc/disorder_protocol.5.in
index f4c5b2fbfd446c744c484383229d0ef1f5f0aa71..b42ebd5f4ec5e0c88c7e16a2af4e44eaa07fe980 100644 (file)
--- a/doc/disorder_protocol.5.in
+++ b/doc/disorder_protocol.5.in
@@ -1,20 +1,18 @@
 .\"
 .\" Copyright (C) 2004-2008 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
 .\" 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.
 .\" (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
 .\" 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_protocol 5
 .SH NAME
 .\"
 .TH disorder_protocol 5
 .SH NAME


@@ -59,6 +57,10 @@ then the \fBdefault_rights\fR setting applies instead.
 Requires the \fBadmin\fR right, and only works on local
 connections.
 .TP
 Requires the \fBadmin\fR right, and only works on local
 connections.
 .TP

+.B adopt \fIID\fR
+Adopts a randomly picked track, leaving it in a similar state to if it was
+picked by this user.  Requires the \fBplay\fR right.
+.TP

 .B allfiles \fIDIRECTORY\fR [\fIREGEXP\fR]
 List all the files and directories in \fIDIRECTORY\fR in a response body.
 If \fIREGEXP\fR is present only matching files and directories are returned.
 .B allfiles \fIDIRECTORY\fR [\fIREGEXP\fR]
 List all the files and directories in \fIDIRECTORY\fR in a response body.
 If \fIREGEXP\fR is present only matching files and directories are returned.


@@ -236,6 +238,11 @@ See below for the track information syntax.
 .B reconfigure
 Request that DisOrder reconfigure itself.
 Requires the \fBadmin\fR right.
 .B reconfigure
 Request that DisOrder reconfigure itself.
 Requires the \fBadmin\fR right.

+.IP
+Not all configuration options can be modified during the lifetime of the
+server; of those that can't, some will just be ignored if they change while
+others will cause the new configuration to be rejected.
+See \fBdisorder_config\fR(5) for details.

 .TP
 .B register \fIUSERNAME PASSWORD EMAIL
 Register a new user.
 .TP
 .B register \fIUSERNAME PASSWORD EMAIL
 Register a new user.


@@ -497,6 +504,26 @@ The time the track was played at.
 .B scratched
 The user that scratched the track.
 .TP
 .B scratched
 The user that scratched the track.
 .TP

+.B origin
+The origin of the track.  Valid origins are:
+.RS
+.TP 12
+.B adopted
+The track was originally randomly picked but has been adopted by a user.
+.TP
+.B picked
+The track was picked by a user.
+.TP
+.B random
+The track was randomly picked.
+.TP
+.B scheduled
+The track was played from a scheduled action.
+.TP
+.B scratch
+The track is a scratch sound.
+.RE
+.TP

 .B state
 The current track state.
 Valid states are:
 .B state
 The current track state.
 Valid states are:


@@ -505,12 +532,6 @@ Valid states are:
 .B failed
 The player failed (exited with nonzero status but wasn't scratched).
 .TP
 .B failed
 The player failed (exited with nonzero status but wasn't scratched).
 .TP

-.B isscratch
-The track is actually a scratch.
-.TP
-.B no_player
-No player could be found for the track.
-.TP

 .B ok
 The track was played without any problems.
 .TP
 .B ok
 The track was played without any problems.
 .TP


@@ -520,6 +541,9 @@ The track was scratched.
 .B started
 The track is currently playing.
 .TP
 .B started
 The track is currently playing.
 .TP

+.B paused
+Track is playing but paused.
+.TP

 .B unplayed
 In the queue, hasn't been played yet.
 .TP
 .B unplayed
 In the queue, hasn't been played yet.
 .TP


@@ -538,6 +562,9 @@ The time the track was added to the queue.
 .TP
 .B wstat
 The wait status of the player in decimal.
 .TP
 .B wstat
 The wait status of the player in decimal.

+.PP
+Note that \fBorigin\fR is new with DisOrder 4.3, and obsoletes some old
+\fBstate\fR values.

 .SH NOTES
 Times are decimal integers using the server's \fBtime_t\fR.
 .PP
 .SH NOTES
 Times are decimal integers using the server's \fBtime_t\fR.
 .PP


@@ -555,6 +582,9 @@ keyword followed by (optionally) parameters.
 The parameters are quoted in the usual DisOrder way.
 Currently the following keywords are used:
 .TP
 The parameters are quoted in the usual DisOrder way.
 Currently the following keywords are used:
 .TP

+.B adopted \fIID\fR \fIUSERNAME\fR
+\fIUSERNAME\fR adopted track \fIID\fR.
+.TP

 .B completed \fITRACK\fR
 Completed playing \fITRACK\fR
 .TP
 .B completed \fITRACK\fR
 Completed playing \fITRACK\fR
 .TP


@@ -620,6 +650,9 @@ A track started playing.
 .B resume
 The current track was resumed.
 .TP
 .B resume
 The current track was resumed.
 .TP

+.B rights_changed \fIRIGHTS\fR
+User's rights were changed.
+.TP

 .B scratched
 The current track was scratched.
 .PP
 .B scratched
 The current track was scratched.
 .PP


@@ -627,6 +660,18 @@ To simplify client implementation, \fBstate\fR commands reflecting the current
 state are sent at the start of the log.
 .RE
 .TP
 state are sent at the start of the log.
 .RE
 .TP

+.B user_add \fIUSERNAME\fR
+A user was created.
+.TP
+.B user_delete \fIUSERNAME\fR
+A user was deleted.
+.TP
+.B user_edit \fIUSERNAME\fR \fIPROPERTY\fR
+Some property of a user was edited.
+.TP
+.B user_confirm \fIUSERNAME\fR
+A user's login was confirmed (via the web interface).
+.TP

 .B volume \fILEFT\fR \fIRIGHT\fR
 The volume changed.
 .PP
 .B volume \fILEFT\fR \fIRIGHT\fR
 The volume changed.
 .PP


@@ -634,6 +679,9 @@ The volume changed.
 is as defined in
 .B "TRACK INFORMATION"
 above.
 is as defined in
 .B "TRACK INFORMATION"
 above.

+.PP
+The \fBuser-*\fR messages are only sent to admin users, and are not sent over
+non-local connections unless \fBremote_userman\fR is enabled.

 .SH "CHARACTER ENCODING"
 All data sent by both server and client is encoded using UTF-8.
 Moreover it must be valid UTF-8, i.e. non-minimal sequences are not
 .SH "CHARACTER ENCODING"
 All data sent by both server and client is encoded using UTF-8.
 Moreover it must be valid UTF-8, i.e. non-minimal sequences are not