X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/blobdiff_plain/c0c23a60ef1189000787892f40f120240746e7a3..a4243347741f0f7079858e03bca8fc32990f525c:/doc/disorder_protocol.5.in

diff --git a/doc/disorder_protocol.5.in b/doc/disorder_protocol.5.in
index aa6b65e..0847050 100644
--- a/doc/disorder_protocol.5.in
+++ b/doc/disorder_protocol.5.in
@@ -69,7 +69,7 @@ Confirm user registration.
 This command can be used without logging in.
 .TP
 .B cookie \fICOOKIE
-Log a user back in using a cookie created with \fBmake-cookie\fR.
+Log a user back in using a cookie created with \fBmake\-cookie\fR.
 The response contains the username.
 .TP
 .B deluser \fIUSERNAME
@@ -91,6 +91,10 @@ Set a user property.
 With the \fBadmin\fR right any username and property may be specified.
 Otherwise the \fBuserinfo\fR right is required and only the
 \fBemail\fR and \fBpassword\fR properties may be set.
+.IP
+User properties are syntax-checked before setting.  For instance \fBemail\fR
+must contain an "@" sign or you will get an error.  (Setting an empty value for
+\fBemail\fR is allowed and removes the property.)
 .TP
 .B enable
 Re-enable further playing, and is the opposite of \fBdisable\fR.
@@ -114,7 +118,7 @@ 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.
 .TP
-.B get-global \fIKEY\fR
+.B get\-global \fIKEY\fR
 Get a global preference.
 .IP
 If the preference does not exist then the response code is 555.
@@ -131,7 +135,7 @@ i.e. it will not accumulate in a buffer somewhere).
 .IP
 See \fBEVENT LOG\fR below for more details.
 .TP
-.B make-cookie
+.B make\-cookie
 Returns an opaque string that can be used by the \fBcookie\fR command to log
 this user back in on another connection (until the cookie expires).
 .TP
@@ -212,15 +216,15 @@ Send back the current queue in a response body, one track to a line, the track
 at the head of the queue (i.e. next to be be played) first.
 See below for the track information syntax.
 .TP
-.B random-disable
+.B random\-disable
 Disable random play (but don't stop the current track).
 Requires the \fBglobal prefs\fR right.
 .TP
-.B random-enable
+.B random\-enable
 Enable random play.
 Requires the \fBglobal prefs\fR right.
 .TP
-.B random-enabled
+.B random\-enabled
 Report whether random play is enabled.
 The second field of the response line will be \fByes\fR or \fBno\fR.
 .TP
@@ -233,15 +237,15 @@ See below for the track information syntax.
 Request that DisOrder reconfigure itself.
 Requires the \fBadmin\fR right.
 .TP
-.B register \fIUSER PASSWORD EMAIL
+.B register \fIUSERNAME PASSWORD EMAIL
 Register a new user.
 Requires the \fBregister\fR right.
 The result contains a confirmation string; the user will be be able
 to log in until this has been presented back to the server via the
 \fBconfirm\fR command.
 .TP
-.B reminder \fIUSER\fR
-Send a password reminder to \fIUSER\fR.
+.B reminder \fIUSERNAME\fR
+Send a password reminder to user \fIUSERNAME\fR.
 If the user has no valid email address, or no password, or a
 reminder has been sent too recently, then no reminder will be sent.
 .TP
@@ -251,9 +255,21 @@ Requires one of the \fBremove mine\fR, \fBremove random\fR or
 \fBremove any\fR rights depending on how the
 track came to be added to the queue.
 .TP
-.B rescan
+.B rescan \fR[\fBwait\fR] \fR[\fBfresh\fR]
 Rescan all roots for new or obsolete tracks.
 Requires the \fBrescan\fR right.
+.IP
+If the \fBwait\fR flag is present then the response is delayed until the rescan
+completes.
+Otherwise the response arrives immediately.
+This is primarily intended for testing.
+.IP
+If the \fBfresh\fR flag is present a rescan is already underway then a second
+rescan will be started when it completes.
+The default behavior is to piggyback on the existing rescan.
+.IP
+NB that \fBfresh\fR is currently disabled in the server source, so using this
+flag will just provoke an error.
 .TP
 .B resolve \fITRACK\fR
 Resolve a track name, i.e. if this is an alias then return the real track name.
@@ -263,10 +279,10 @@ Resume the current track after a \fBpause\fR command.
 Requires the \fBpause\fR right.
 .TP
 .B revoke \fBcookie\fR
-Revoke a cookie previously created with \fBmake-cookie\fR.
+Revoke a cookie previously created with \fBmake\-cookie\fR.
 It will not be possible to use this cookie in the future.
 .TP
-.B rtp-address
+.B rtp\-address
 Report the RTP broadcast (or multicast) address, in the form \fIADDRESS
 PORT\fR.
 This command does not require authentication.
@@ -299,7 +315,7 @@ allow searching for phrases.
 Set a preference.
 Requires the \fBprefs\fR right.
 .TP
-.B set-global \fIKEY\fR \fIVALUE\fR
+.B set\-global \fIKEY\fR \fIVALUE\fR
 Set a global preference.
 Requires the \fBglobal prefs\fR right.
 .TP
@@ -313,16 +329,19 @@ Send the list of currently known tags in a response body.
 Unset a preference.
 Requires the \fBprefs\fR right.
 .TP
-.B \fBunset-global\fR \fIKEY\fR
+.B \fBunset\-global\fR \fIKEY\fR
 Unset a global preference.
 Requires the \fBglobal prefs\fR right.
 .TP
-.B user \fIUSER\fR \fIRESPONSE\fR
-Authenticate as \fIUSER\fR.
+.B user \fIUSERNAME\fR \fIRESPONSE\fR
+Authenticate as user \fIUSERNAME\fR.
 See
 .B AUTHENTICATION
 below.
 .TP
+.B userinfo \fIUSERNAME PROPERTY
+Get a user property.
+.TP
 .B users
 Send the list of currently known users in a response body.
 .TP
@@ -487,11 +506,11 @@ Completed playing \fITRACK\fR
 .B failed \fITRACK\fR \fIERROR\fR
 Completed playing \fITRACK\fR with an error status
 .TP
-.B moved \fIUSER\fR
-User \fIUSER\fR moved some track(s).
+.B moved \fIUSERNAME\fR
+User \fIUSERNAME\fR moved some track(s).
 Further details aren't included any more.
 .TP
-.B playing \fITRACK\fR [\fIUSER\fR]
+.B playing \fITRACK\fR [\fIUSERNAME\fR]
 Started playing \fITRACK\fR.
 .TP
 .B queue \fIQUEUE-ENTRY\fR...
@@ -503,16 +522,16 @@ Added \fIID\fR to the recently played list.
 .B recent_removed \fIID\fR
 Removed \fIID\fR from the recently played list.
 .TP
-.B removed \fIID\fR [\fIUSER\fR]
+.B removed \fIID\fR [\fIUSERNAME\fR]
 Queue entry \fIID\fR was removed.
-This is used both for explicit removal (when \fIUSER\fR is present)
+This is used both for explicit removal (when \fIUSERNAME\fR is present)
 and when playing a track (when it is absent).
 .TP
 .B rescanned
 A rescan completed.
 .TP
-.B scratched \fITRACK\fR \fIUSER\fR
-\fITRACK\fR was scratched by \fIUSER\fR.
+.B scratched \fITRACK\fR \fIUSERNAME\fR
+\fITRACK\fR was scratched by \fIUSERNAME\fR.
 .TP
 .B state \fIKEYWORD\fR
 Some state change occurred.