Minor Lintian fixes

[disorder] / doc / disorder_protocol.5.in

diff --git a/doc/disorder_protocol.5.in b/doc/disorder_protocol.5.in
index c258b0bb449c32e5358525a4433f67bab0680ab0..bb95ff01e584ebaa68b842e23e1f26769ae28263 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


@@ -66,6 +64,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.


@@ -120,7 +122,7 @@ List all the files in \fIDIRECTORY\fR in a response body.
 If \fIREGEXP\fR is present only matching files are returned.
 .TP
 .B get \fITRACK\fR \fIPREF\fR
 If \fIREGEXP\fR is present only matching files are returned.
 .TP
 .B get \fITRACK\fR \fIPREF\fR

-Getsa preference value.
+Gets a preference value.

 On success the second field of the response line will have the value.
 .IP
 If the track or preference do not exist then the response code is 555.
 On success the second field of the response line will have the value.
 .IP
 If the track or preference do not exist then the response code is 555.


@@ -169,7 +171,7 @@ depending on how the tracks came to be added to the queue.
 .TP
 .B new \fR[\fIMAX\fR]
 Send the most recently added \fIMAX\fR tracks in a response body.
 .TP
 .B new \fR[\fIMAX\fR]
 Send the most recently added \fIMAX\fR tracks in a response body.

-If the argument is ommitted, the \fBnew_max\fR most recent tracks are
+If the argument is omitted, the \fBnew_max\fR most recent tracks are

 listed (see \fBdisorder_config\fR(5)).
 .TP
 .B nop
 listed (see \fBdisorder_config\fR(5)).
 .TP
 .B nop


@@ -205,6 +207,16 @@ Add a track to the queue.
 The response contains the queue ID of the track.
 Requires the \fBplay\fR right.
 .TP
 The response contains the queue ID of the track.
 Requires the \fBplay\fR right.
 .TP

+.B playafter \fITARGET\fR \fITRACK\fR ...
+Add all the tracks in the \fITRACK\fR list to the queue after \fITARGET\fR
+(which should be a track ID).
+If \fITARGET\fR is the empty string then the listed tracks are put
+at the head of the queue.
+.IP
+Currently the success result does \fInot\fR include the new track IDs.
+.IP
+Requires the \fBplay\fR right.
+.TP

 .B playing
 Report what track is playing.
 .IP
 .B playing
 Report what track is playing.
 .IP


@@ -220,6 +232,7 @@ Requires permission to modify that playlist and the \fBplay\fR right.
 .B playlist-get \fIPLAYLIST\fR
 Get the contents of a playlist, in a response body.
 Requires permission to read that playlist and the \fBread\fR right.
 .B playlist-get \fIPLAYLIST\fR
 Get the contents of a playlist, in a response body.
 Requires permission to read that playlist and the \fBread\fR right.

+If the playlist does not exist the response is 555.

 .TP
 .B playlist-get-share \fIPLAYLIST\fR
 Get the sharing status of a playlist.
 .TP
 .B playlist-get-share \fIPLAYLIST\fR
 Get the sharing status of a playlist.


@@ -280,6 +293,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.


@@ -458,7 +476,7 @@ With two parameters sets each side independently.
 Setting the volume requires the \fBvolume\fR right.
 .SH RESPONSES
 Responses are three-digit codes.
 Setting the volume requires the \fBvolume\fR right.
 .SH RESPONSES
 Responses are three-digit codes.

-The first digit distinguishes errors from succesful responses:
+The first digit distinguishes errors from successful responses:

 .TP
 .B 2
 Operation succeeded.
 .TP
 .B 2
 Operation succeeded.


@@ -541,6 +559,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:


@@ -549,12 +587,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


@@ -564,6 +596,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


@@ -582,6 +617,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


@@ -599,6 +637,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


@@ -612,6 +653,21 @@ Further details aren't included any more.
 .B playing \fITRACK\fR [\fIUSERNAME\fR]
 Started playing \fITRACK\fR.
 .TP
 .B playing \fITRACK\fR [\fIUSERNAME\fR]
 Started playing \fITRACK\fR.
 .TP

+.B playlist_created \fIPLAYLIST\fR \fISHARING\fR
+Sent when a playlist is created.
+For private playlists this is intended to be sent only to the owner (but
+this is not currently implemented).
+.TP
+.B playlist_deleted \fIPLAYLIST\fR
+Sent when a playlist is deleted.
+For private playlists this is intended to be sent only to the owner (but
+this is not currently implemented).
+.TP
+.B playlist_modified \fIPLAYLIST\fR \fISHARING\fR
+Sent when a playlist is modified (either its contents or its sharing status).
+For private playlists this is intended to be sent only to the owner (but
+this is not currently implemented).
+.TP

 .B queue \fIQUEUE-ENTRY\fR...
 Added \fITRACK\fR to the queue.
 .TP
 .B queue \fIQUEUE-ENTRY\fR...
 Added \fITRACK\fR to the queue.
 .TP


@@ -673,7 +729,7 @@ The current track was scratched.
 To simplify client implementation, \fBstate\fR commands reflecting the current
 state are sent at the start of the log.
 .RE
 To simplify client implementation, \fBstate\fR commands reflecting the current
 state are sent at the start of the log.
 .RE

-.TB
+.TP

 .B user_add \fIUSERNAME\fR
 A user was created.
 .TP
 .B user_add \fIUSERNAME\fR
 A user was created.
 .TP