.B home \fIDIRECTORY\fR
The home directory for state files. Defaults to
.IR pkgstatedir .
+The server will create this directory on startup if it does not exist.
.TP
-.B plugin \fIPATH\fR
+.B plugins \fIPATH\fR
Adds a directory to the plugin path. (This is also used by the web
interface.)
.IP
Plugins are opened the first time they are required and never after,
so after changing a plugin you must restart the server before it is
guaranteed to take effect.
+.IP
+If
+.B plugins
+is used without arguments the plugin path is cleared.
.SS "Server Configuration"
.TP
.B alias \fIPATTERN\fR
.RE
.IP
If multiple player commands match a track then the first match is used.
+.IP
+For the server to be able to calculate track lengths, there should be a
+.B tracklength
+command corresponding to each
+.B player
+command.
+.IP
+If
+.B player
+is used without arguments, the list of players is cleared.
.TP
.B prefsync \fISECONDS\fR
The interval at which the preferences log file will be synchronised. Defaults
The target size of the queue. If random play is enabled then randomly picked
tracks will be added until the queue is at least this big.
.TP
+.B restrict \fR[\fBscratch\fR] [\fBremove\fR] [\fBmove\fR]
+Determine which operations are restricted to the submitter of a
+track. By default, no operations are restricted, i.e. anyone can
+scratch or remove anything.
+.IP
+If \fBrestrict scratch\fR or \fBrestrict remove\fR are set then only the user
+that submitted a track can scratch or remove it, respectively.
+.IP
+If \fBrestrict move\fR is set then only trusted users can move tracks around in
+the queue.
+.IP
+If \fBrestrict\fR is used more than once then only the final use has any
+effect.
+.TP
.B sample_format \fIBITS\fB/\fIRATE\fB/\fICHANNELS
Describes the sample format expected by the \fBspeaker_command\fR (below). The
components of the format specification are as follows:
.B sox
is not installed then this will not work.
.TP
-.B restrict \fR[\fBscratch\fR] [\fBremove\fR] [\fBmove\fR]
-Determine which operations are restricted to the submitter of a
-track. By default, no operations are restricted, i.e. anyone can
-scratch or remove anything.
-.IP
-If \fBrestrict scratch\fR or \fBrestrict remove\fR are set then only the user
-that submitted a track can scratch or remove it, respectively.
-.IP
-If \fBrestrict move\fR is set then only trusted users can move tracks around in
-the queue.
-.IP
-If \fBrestrict\fR is used more than once then only the final use has any
-effect.
-.TP
.B scratch \fIPATH\fR
Specifies a scratch. When a track is scratched, a scratch track is
played at random.
.IP
At least for the time being, path names of scratches must be encoded using
UTF-8 (which means that ASCII will do).
+.IP
+If \fBscratch\fR is used without arguments then the list of scratches is
+cleared.
.TP
.B stopword \fIWORD\fR ...
Specifies one or more stopwords that should not take part in searches
over track names.
+.IP
+If \fBstopword\fR is used without arguments then the list of stopwords is
+cleared.
+.TP
+.B tracklength \fIPATTERN\fR \fIMODULE\fR
+Specifies the module used to calculate the length of files matching
+\fIPATTERN\fR. \fIMODULE\fR specifies which plugin module to use.
+.IP
+If \fBtracklength\fR is used without arguments then the list of modules is
+cleared.
.SS "Client Configuration"
.TP
.B connect \fIHOST SERVICE\fR
.B refresh \fISECONDS\fR
Specifies the maximum refresh period in seconds. Default 15.
.TP
+.B short_display \fICHARACTERS\fR
+Defines the maximum number of characters to include in a \fBshort\fR name
+part. Default 30.
+.TP
.B templates \fIPATH\fR ...
Specifies the directory containing templates used by the web
interface. If a template appears in more than one template directory
then the one in the earliest directory specified is chosen.
.IP
See below for further details.
+.IP
+If \fBtemplates\fR is used without arguments then the template path is cleared.
.TP
.B transform \fITYPE\fR \fIREGEXP\fR \fISUBST\fR [\fICONTEXT\fR [\fIREFLAGS\fR]]
Determines how names are sorted and displayed in track choice displays.
.TP
.B allow \fIUSERNAME\fR \fIPASSWORD\fR
Specify a username/password pair.
+.IP
+If
+.B allow
+is used without arguments, the list of allowed users is cleared.
.TP
.B password \fIPASSWORD\fR
Specify password.
.B trust \fIUSERNAME\fR
Allow \fIUSERNAME\fR to perform privileged operations such as shutting
down or reconfiguring the daemon, or becoming another user.
+.IP
+If \fBtrust\fR is used without arguments then the list of trusted users is
+cleared.
.TP
.B user \fIUSER\fR
Specifies the user to run as. Only makes sense if invoked as root (or
.I pkgconfdir/config.private
Should be readable only by the jukebox group, and contain \fBallow\fR
commands for authorised users.
+.IP
+If this file does not exist at startup then the server will create it with a
+randomly chosen password for the root user.
.TP
.I pkgconfdir/config.\fRUSER
Per-user system-controlled client configuration. Optional but if it
.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.
argument to \fBchoose\fR.
.TP
.B @files{\fITEMPLATE\fB}
-Expands \fITEMPLATE\fB once for each file indicated by the \fBdirectory\fR CGI
+Expands \fITEMPLATE\fR once for each file indicated by the \fBdirectory\fR CGI
arg if it is present, or otherwise for the list of files counted by \fBfiles\fR
with names \fB0_file\fR, \fB1_file\fR etc.
.TP
.TP
.B @part{\fICONTEXT\fB}{\fIPART\fB}@
Expands to track name part \fIPART\fR using context \fICONTEXT\fR for the
-current track. The context may be omitted (and normally would be) and defaults
+current track. The context may be omitted and defaults
to \fBdisplay\fR.
+.IP
+The special context \fBshort\fR is equivalent to \fBdisplay\fR but limited to
+the \fBshort_display\fR limit.
.TP
.B @part{\fICONTEXT\fB}{\fIPART\fB}{\fITRACK\fB}@
Expands to track name part \fIPART\fR using context \fICONTEXT\fR for
\fITRACK\fR. In this usage the context may not be omitted.
+.IP
+The special context \fBshort\fR is equivalent to \fBdisplay\fR but limited to
+the \fBshort_display\fR limit.
.TP
.B @paused@
Expands to \fBtrue\fR if the current track is paused, else \fBfalse\fR.
Expands to \fBdisorder.cgi\fR's version string.
.TP
.B @volume:\fISPEAKER\fB@
-The volume on the left or right speaker. \fISPEAKER\fR must be \fBleft\fB or
+The volume on the left or right speaker. \fISPEAKER\fR must be \fBleft\fR or
\fBright\fR.
.TP
.B @when@
~mdw / disorder / blobdiff