X-Git-Url: https://git.distorted.org.uk/~mdw/disorder/blobdiff_plain/d5b6ffd76a65b9a09a4aef9e39e342e1462f5eea..61941295f0eb457edc89f0337f732ff071838b6a:/doc/disorder_config.5.in

diff --git a/doc/disorder_config.5.in b/doc/disorder_config.5.in
index 8fea1ec..2b57c79 100644
--- a/doc/disorder_config.5.in
+++ b/doc/disorder_config.5.in
@@ -1,3 +1,4 @@
+
 .\"
 .\" Copyright (C) 2004, 2005, 2006, 2007 Richard Kettlewell
 .\"
@@ -116,14 +117,19 @@ start up without a valid config file.)
 .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
@@ -151,6 +157,8 @@ for more details.
 .B broadcast \fIADDRESS\fR \fIPORT\fR
 Transmit sound data to \fIADDRESS\fR using UDP port \fIPORT\fR.  This implies
 \fBspeaker_backend network\fR.
+.IP
+See also \fBmulticast_loop\fR and \fBmulticast_ttl\fR.
 .TP
 .B broadcast_from \fIADDRESS\fR \fIPORT\fR
 Sets the (local) source address used by \fBbroadcast\fR.
@@ -218,8 +226,14 @@ Determines whether the server locks against concurrent operation.  Default is
 The path to the mixer device, if you want access to the volume control,
 e.g. \fB/dev/mixer\fR.
 .TP
+.B multicast_loop yes\fR|\fBno
+Determines whether multicast packets are loop backed to the sending host.  The
+default is \fByes\fR.  This only applies if
+\fBspeaker_backend\fR is set to \fBnetwork\fR and \fBbroadcast\fR is actually a
+multicast address.
+.TP
 .B multicast_ttl \fIHOPS\fR
-Set the maximum number of hops to send multicast packets.  This only applies is
+Set the maximum number of hops to send multicast packets.  This only applies if
 \fBspeaker_backend\fR is set to \fBnetwork\fR and \fBbroadcast\fR is actually a
 multicast address.
 .TP
@@ -318,6 +332,16 @@ the shell quoting rules.
 .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
@@ -327,6 +351,20 @@ to 3600, i.e. one hour.
 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:
@@ -345,6 +383,16 @@ The number of channels.
 .PP
 The default is
 .BR 16/44100/2 .
+.PP
+With the
+.B network
+backend the sample format is forced to
+.B 16b/44100/2
+and with the
+.B coreaudio
+backend it is forced to
+.BR 16/44100/2 ,
+in both cases regardless of what is specified in the configuration file.
 .RE
 .TP
 .B signal \fINAME\fR
@@ -363,10 +411,18 @@ available:
 Use the ALSA API.  This is only available on Linux systems, on which it is the
 default.
 .TP
+.B coreaudio
+Use Apple Core Audio.  This only available on OS X systems, on which it is the
+default.
+.TP
+.B oss
+Use the OSS (/dev/dsp) API.  Not available on all platforms.  Not well
+maintained at the moment.
+.TP
 .B command
 Execute a command.  This is the default if
 .B speaker_command
-is specified, or (currently) on non-Linux systems.
+is specified, or if no native is available.
 .TP
 .B network
 Transmit audio over the network.  This is the default if
@@ -393,20 +449,6 @@ is invoked to translate it.  If
 .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.
@@ -414,10 +456,23 @@ Scratches are played using the same logic as other tracks.
 .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
@@ -428,12 +483,18 @@ Connect to the address specified by \fIHOST\fR and port specified by
 .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.
@@ -466,6 +527,10 @@ This must be the full URL, e.g. \fBhttp://myhost/cgi-bin/jukebox\fR and not
 .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.
@@ -473,6 +538,9 @@ 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
@@ -489,6 +557,9 @@ Configuration files are read in the following order:
 .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
@@ -521,6 +592,14 @@ If unset or \fByes\fR then play is enabled.  Otherwise it is disabled.  Use
 .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.
@@ -694,7 +773,7 @@ Expands to the filename of the current file or directory, inside the template
 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
@@ -789,12 +868,18 @@ an even or odd position in \fB@queue@\fR, \fB@recent@\fR or \fB@files@\fR.
 .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.
@@ -933,7 +1018,7 @@ URL-quote \fISTRING\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@