are now split out to a new man page.
cgi/Makefile
libtests/index.html
libtests/t-eventdist
+doc/disorder_preferences.5
+doc/disorder_preferences.5.html
disorder-rescan.8 disobedience.1 disorderfm.1 disorder-speaker.8 \
disorder-playrtp.1 disorder-normalize.8 disorder-decode.8 \
disorder-stats.8 disorder-dbupgrade.8 disorder_templates.5 \
- disorder_actions.5 disorder_options.5 disorder.cgi.8
+ disorder_actions.5 disorder_options.5 disorder.cgi.8 \
+ disorder_preferences.5
noinst_MANS=tkdisorder.1
SEDFILES=disorder.1 disorderd.8 disorder_config.5 \
disorder-rescan.8 disobedience.1 disorderfm.1 disorder-playrtp.1 \
disorder-decode.8 disorder-stats.8 disorder-dbupgrade.8 \
disorder_options.5 disorder.cgi.8 disorder_templates.5 \
- disorder_actions.5
+ disorder_actions.5 disorder_preferences.5
include ${top_srcdir}/scripts/sedfiles.make
disorder-stats.8.in disorder-dbupgrade.8.in \
disorder_actions.5.head disorder_templates.5.head \
disorder_actions.5.tail disorder_templates.5.tail \
- disorder_options.5.in disorder.cgi.8.in
+ disorder_options.5.in disorder.cgi.8.in disorder_preferences.5.in
CLEANFILES=$(SEDFILES) $(HTMLMAN) $(TMPLMAN) \
disorder_actions.5.in disorder_templates.5.in
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
.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.
+See \fBdisorder_preferences\fR (5).
.TP
.B get\-volume
Display the current volume settings.
.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 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.
+See \fBdisorder_preferences\fR (5).
.TP
.B set\-volume \fBLEFT\fR \fBRIGHT\fR
Set the volume.
.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.
+See \fBdisorder_preferences\fR (5).
.TP
.B userinfo \fIUSERNAME PROPERTY
Get some property of a user.
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.
be different locally.
.SH ENVIRONMENT
.TP
-.B LOGNAME
-The default username.
-.TP
.B HOME
The user's home directory.
.TP
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_prefeferences\fR(5)
.PP
"\fBpydoc disorder\fR" for the Python API documentation.
.\" Local Variables:
Each track can have a set of preferences associated with it.
These are simple key-value pairs; they can be used for anything you
like, but a number of keys have specific meanings.
-See \fBdisorder\fR(1) for more details about these.
+See \fBdisorder_preferences\fR(5) for more details about these.
.SS "Track Names"
Track names are derived from filenames under the control of regular
expressions, rather than attempting to interpret format-specific embedded name
.SS "Server State"
A collection of global preferences define various bits of server state: whether
random play is enabled, what tags to check for when picking at random, etc.
+See \fBdisorder_preferences\fR(5) for more information.
.SS "Users And Access Control"
DisOrder distinguishes between multiple users.
This is for access control and reporting, not to provide different
.TP
.B username \fIUSERNAME\fR
Specify username.
-The default is taken from the environment variable \fBLOGNAME\fR.
+The default is inferred from the current UID.
.SS "Web Interface Configuration"
.\" TODO this section is misnamed really...
.TP
This must be the full URL, e.g. \fBhttp://myhost/cgi-bin/jukebox\fR and not
\fB/cgi-bin/jukebox\fR.
.SH "GLOBAL PREFERENCES"
-These are the values set with \fBset\-global\fR.
-.TP
-.B required\-tags
-If this is set an nonempty then randomly played tracks will always have at
-least one of the listed tags.
-.TP
-.B prohibited\-tags
-If this is set an nonempty then randomly played tracks will never have any of
-the listed tags.
-.TP
-.B playing
-If unset or \fByes\fR then play is enabled.
-Otherwise it is disabled.
-Use \fBdisable\fR rather than setting it directly.
-.TP
-.B random\-play
-If unset or \fByes\fR then random play is enabled.
-Otherwise it is disabled.
-Use \fBdisable\fR rather than setting it directly.
-.PP
-Global preferences starting '_' are read-only (in the sense that you cannot
-modify them; the server may modify them as part of its normal operation).
-They are:
-.TP
-.B _dbversion
-The database version string.
-This is used by DisOrder to detect when it must
-modify the database after an upgrade.
.SH "LIBAO DRIVER"
.SS "Raw Protocol Players"
Raw protocol players are expected to use the \fBdisorder\fR libao driver.
.SH "SEE ALSO"
\fBdisorder\fR(1), \fBsox\fR(1), \fBdisorderd\fR(8), \fBdisorder\-dump\fR(8),
\fBpcrepattern\fR(3), \fBdisorder_templates\fR(5), \fBdisorder_actions\fR(5),
-\fBdisorder.cgi\fR(8)
+\fBdisorder.cgi\fR(8), \fBdisorder_preferences\fR(5)
.\" Local Variables:
.\" mode:nroff
.\" fill-column:79
--- /dev/null
+.\"
+.\" Copyright (C) 2008 Richard Kettlewell
+.\"
+.\" 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
+.\" (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.
+.\"
+.\" 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
+.\"
+.TH disorder_preferences 5
+.SH NAME
+disorder_preferences \- DisOrder global and per-track preferences
+.SH "PER-TRACK 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 "GLOBAL PREFERENCES"
+These are the values set with \fBset\-global\fR.
+.TP
+.B required\-tags
+If this is set an nonempty then randomly played tracks will always have at
+least one of the listed tags.
+.TP
+.B prohibited\-tags
+If this is set an nonempty then randomly played tracks will never have any of
+the listed tags.
+.TP
+.B playing
+If unset or \fByes\fR then play is enabled.
+Otherwise it is disabled.
+Use \fBdisable\fR rather than setting it directly.
+.TP
+.B random\-play
+If unset or \fByes\fR then random play is enabled.
+Otherwise it is disabled.
+Use \fBdisable\fR rather than setting it directly.
+.PP
+Global preferences starting '_' are read-only (in the sense that you cannot
+modify them; the server may modify them as part of its normal operation).
+They are:
+.TP
+.B _dbversion
+The database version string.
+This is used by DisOrder to detect when it must
+modify the database after an upgrade.
+.SH "SEE ALSO"
+\fBdisorder\fR(1), \fBdisorderd\fR(8), \fBdisorder_config\fR(5)
+.\" Local Variables:
+.\" mode:nroff
+.\" fill-column:79
+.\" End:
box at the bottom can be used to selectivel enable or disable it
for individual tracks.</p>
+ <p>See <a
+ href="@url?action=disorder_preferences.5">disorder_preferences(5)</a>
+ for full documentation of track preferences.</p>
+
</div>
<h2 class=sectiontitle><a name=Login>Login</a></h2>
<p><a href="@url?action=disorder_templates.5">disorder_templates(5)</a> -
template language</p>
+ <p><a href="@url?action=disorder_preferences.5">disorder_preferences(5)</a> -
+ per-track and global preferences</p>
+
<p><a href="@url?action=disorder.1">disorder(1)</a> - command line
client</p>