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

[disorder] / doc / disorder.1.in

diff --git a/doc/disorder.1.in b/doc/disorder.1.in
index 9de40a96d4756128f6d51477c67c8819f7e16859..afa1eaa800b87d56d8de89869a94a33ef74b873c 100644 (file)
--- a/doc/disorder.1.in
+++ b/doc/disorder.1.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 1
 .SH NAME
 .\"
 .TH disorder 1
 .SH NAME


@@ -35,6 +33,10 @@ 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
 .SH OPTIONS
 .TP
 .B \-\-config \fIPATH\fR, \fB\-c \fIPATH


@@ -60,6 +62,10 @@ Create a new user.
 If \fIRIGHTS\fR is not specified then the \fBdefault_rights\fR
 setting from the server's configuration file applies.
 .TP
 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).
 .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).


@@ -99,9 +105,11 @@ 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.
 .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
 Get a global preference.
 .TP
 .B get\-global \fIKEY\fR
 Get a global preference.

+See \fBdisorder_preferences\fR (5).

 .TP
 .B get\-volume
 Display the current volume settings.
 .TP
 .B get\-volume
 Display the current volume settings.


@@ -146,6 +154,7 @@ Report the currently playing track.
 .TP
 .B prefs \fITRACK\fR
 Display all the preferences for \fITRACK\fR.
 .TP
 .B prefs \fITRACK\fR
 Display all the preferences for \fITRACK\fR.

+See \fBdisorder_preferences\fR (5).

 .TP
 .B queue
 List the current queue.
 .TP
 .B queue
 List the current queue.


@@ -164,6 +173,11 @@ recently played one.
 .TP
 .B reconfigure
 Make the daemon reload its configuration file.
 .TP
 .B reconfigure
 Make the daemon reload its configuration file.

+.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 remove \fITRACK\fR
 Remove a track from the queue.
 .TP
 .B remove \fITRACK\fR
 Remove a track from the queue.


@@ -238,9 +252,11 @@ For example:
 .TP
 .B set \fITRACK\fR \fIKEY\fR \fIVALUE\fR
 Set the preference \fIKEY\fR for \fITRACK\fR to \fIVALUE\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
 Set a global preference.
 .TP
 .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
 Set the volume.


@@ -269,9 +285,11 @@ List known tags.
 .TP
 .B unset \fITRACK\fR \fIKEY\fR
 Unset the preference \fIKEY\fR for \fITRACK\fR.
 .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
 Unset the global preference \fIKEY\fR.
 .TP
 .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 userinfo \fIUSERNAME PROPERTY
 Get some property of a user.


@@ -289,67 +307,6 @@ and
 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.
 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.
-.TP
-.B weight
-The weight for this track.  Weights are non-negative integers which determine
-the relative likelihood of a track being picked at random (i.e. if track A has
-twice the weight of track B then it is twice as likely to be picked at random).
-A track with weight 0 will not be picked at random, though \fBpick_at_random\fR
-is a more sensible way to configure this.
-.IP
-The default weight, used if no weight is set or the weight value is invalid, is
-90000.  Note that many other factors than track weight affect whether a track
-will be played - tracks already in the queue will not be picked at random for
-instance.
-.IP
-The maximum allowed weight is 2147483647.  If you set a larger value it will be
-clamped to this value.  Negative weights will be completely ignored and the
-default value used instead.

 .SH NOTES
 .B disorder
 is locale-aware.
 .SH NOTES
 .B disorder
 is locale-aware.


@@ -406,9 +363,6 @@ The README recommends using \fBjukebox\fR for this purpose but it could
 be different locally.
 .SH ENVIRONMENT
 .TP
 be different locally.
 .SH ENVIRONMENT
 .TP

-.B LOGNAME
-The default username.
-.TP

 .B HOME
 The user's home directory.
 .TP
 .B HOME
 The user's home directory.
 .TP


@@ -428,7 +382,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),
 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), \fBdisorder.cgi\fR(8)
+\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:
 .PP
 "\fBpydoc disorder\fR" for the Python API documentation.
 .\" Local Variables: