chiark / gitweb /
'collection' no longer requires an encoding to be specified (or a module).
[disorder] / doc / disorder_config.5.in
index 744bf1309968f349fd77b35cbb66e87e53601947..ffabeb8d8d6dc273b5b73fc3e4256e29b90d6f2b 100644 (file)
@@ -1,4 +1,3 @@
-
 .\"
 .\" Copyright (C) 2004, 2005, 2006, 2007 Richard Kettlewell
 .\"
@@ -53,10 +52,70 @@ DisOrder distinguishes between multiple users.  This is for access control and
 reporting, not to provide different views of the world: i.e. preferences and so
 on are global.
 .PP
-It's possible to restrict a small number of operations to a specific subset of
-users.  However, it is assumed that every user is supposed to be able to do
-most operations - since the users are all sharing the same audio environment
-they are expected to cooperate with each other.
+Each user has an associated set of rights which contorl which commands they may
+execute.  Normally you would give all users most rights, and expect them to
+cooperate (they are after all presumed to be in a shared sound environment).
+.PP
+The full set of rights are:
+.TP
+.B read
+User can perform read-only operations
+.TP
+.B play
+User can add tracks to the queue
+.TP
+.B "move any"
+User can move any track
+.TP
+.B "move mine"
+User can move their own tracks
+.TP
+.B "move random"
+User can move randomly chosen tracks
+.TP
+.B "remove any"
+User can remove any track
+.TP
+.B "remove mine"
+User can remove their own tracks
+.TP
+.B "remove random"
+User can remove randomly chosen tracks
+.TP
+.B "scratch any"
+User can scratch any track
+.TP
+.B "scratch mine"
+User can scratch their own tracks
+.TP
+.B "scratch random"
+User can scratch randomly chosen tracks
+.TP
+.B volume
+User can change the volume
+.TP
+.B admin
+User can perform admin operations
+.TP
+.B rescan
+User can initiate a rescan
+.TP
+.B register
+User can register new users.  Normally only the
+.B guest
+user would have this right.
+.TP
+.B userinfo
+User can edit their own userinfo
+.TP
+.B prefs
+User can modify track preferences
+.TP
+.B "global prefs"
+User can modify global preferences
+.TP
+.B pause
+User can pause/resume 
 .PP
 Access control is entirely used-based.  If you configure DisOrder to listen for
 TCP/IP connections then it will accept a connection from anywhere provided the
@@ -72,11 +131,33 @@ override specific bits.
 The web interface connects to the DisOrder server like any other user, though
 it is given a special privilege to "become" any other user.  (Thus, any process
 with the same UID as the web interface is very powerful as far as DisOrder
-goes.)
+goes.  This model will be changed in a future version.)
 .PP
 Access control to the web interface is (currently) separate from DisOrder's own
 access control (HTTP authentication is required) but uses the same user
 namespace.
+.SS "Searching And Tags"
+Search strings contain a list of search terms separated by spaces.  A search
+term can either be a single word or a tag, prefixed with "tag:".
+.PP
+Search words are compared without regard to letter case or accents; thus, all
+of the following will be considered to be equal to one another:
+.PP
+.nf
+  LATIN CAPITAL LETTER E
+  LATIN SMALL LETTER E
+  LATIN CAPITAL LETTER E WITH GRAVE
+  LATIN SMALL LETTER E WITH GRAVE
+  LATIN CAPITAL LETTER E plus COMBINING GRAVE ACCENT
+  LATIN SMALL LETTER E plus COMBINING GRAVE ACCENT
+.fi
+.PP
+The same rules apply to tags but in addition leading and trailing whitespace is
+disregarded and all whitespace sequences are treated as equal when they appear
+as internal whitespace.
+.PP
+Where several tags are listed, for instance the tags preference for a track,
+the tags are separated by commas.  Therefore tags may not contain commas.
 .SH "CONFIGURATION FILE"
 .SS "General Syntax"
 Lines are split into fields separated by whitespace (space, tab, line
@@ -112,6 +193,24 @@ it re-read it.  If there is anything wrong with it the daemon will
 record a log message and ignore the new config file.  (You should fix
 it before next terminating and restarting the daemon, as it cannot
 start up without a valid config file.)
+.SS "Configuration Files"
+Configuration files are read in the following order:
+.TP
+.I pkgconfdir/config
+.TP
+.I pkgconfdir/config.private
+Should be readable only by the jukebox group.  Not really useful any more and
+may be abolished in future.
+.TP
+.I pkgconfdir/config.\fRUSER
+Per-user system-controlled client configuration.  Optional but if it
+exists must be readable only by the relevant user.  Would normally
+contain a \fBpassword\fR directive.
+.TP
+.I ~\fRUSER\fI/.disorder/passwd
+Per-user client configuration.  Optional but if it exists must be
+readable only by the relevant user.  Would normally contain a
+\fBpassword\fR directive.
 .SS "Global Configuration"
 .TP
 .B home \fIDIRECTORY\fR
@@ -119,13 +218,17 @@ 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
@@ -144,7 +247,7 @@ automatically included, but should include the proper extension.
 .IP
 The default is \fB{/artist}{/album}{/title}{ext}\fR.
 .TP
-.B authorization_algorthm \fIALGORITHM\fR
+.B authorization_algorithm \fIALGORITHM\fR
 Defines the algorithm used to authenticate clients.  The valid options
 are sha1 (the default), sha256, sha384 and sha512.  See
 .BR disorder_protocol (5)
@@ -153,6 +256,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.
@@ -164,7 +269,8 @@ are:
 .RS
 .TP 8
 .B pcm
-Output level for the audio device.  This is probably what you want.
+Output level for the audio device.  This is probably what you want and is the
+default.
 .TP
 .B speaker
 Output level for the PC speaker, if that is connected to the sound card.
@@ -177,21 +283,42 @@ Master output level.  The OSS documentation recommends against using this, as
 it affects all output devices.
 .RE
 .IP
-You can also specify channels by number, if you know the right value.
+You can also specify channels by number, if you know the right value.  NB that
+volume setting only works on OSS systems (including ALSA, via emulation).
 .TP
 .B collection \fIMODULE\fR \fIENCODING\fR \fIROOT\fR
+.TP
+.B collection \fIMODULE\fR \fIROOT\fR
+.TP
+.B collection \fIROOT\fR
 Define a collection of tracks.
 .IP
 \fIMODULE\fR defines which plugin module should be used for this
-collection.  Use the supplied \fBfs\fR module for tracks that exists
-as ordinary files in the filesystem.
+collection.  Use the supplied \fBfs\fR module for tracks that exist
+as ordinary files in the filesystem.  If no \fIMODULE\fR is specified
+then \fBfs\fR is assumed.
+.IP
+\fIENCODING\fR defines the encoding of filenames in this collection.  For
+\fBfs\fR this would be the encoding you use for filenames.  Examples might be
+\fBiso-8859-1\fR or \fButf-8\fR.  If no encoding is specified then the current
+locale's character encoding is used.
 .IP
-\fIENCODING\fR defines the encoding of filenames in this collection.
-For \fBfs\fR this would be the encoding you use for filenames.
-Examples might be \fBiso-8859-1\fR or \fButf-8\fR.
+NB that this default depends on the locale the server runs in, which is not
+necessarily the same as that of ordinary users, depending how the system is
+configured.  It's best to explicitly specify it to be certain.
 .IP
 \fIROOT\fR is the root in the filesystem of the filenames and is
-passed to the plugin module.
+passed to the plugin module.  It must be an absolute path and should not
+end with a "/".
+.TP
+.B default_rights \fIRIGHTS\fR
+Defines the set of rights given to new users.  The argument is a
+comma-separated list of rights.  For the possible values see
+.B "Users And Access Control"
+above.
+.IP
+The default is to allow everything except \fBadmin\fR and \fBregister\fR
+(modified in legacy configurations by the obsolete \fBrestrict\fR directive).
 .TP
 .B device \fINAME\fR
 ALSA device to play raw-format audio.  Default is \fBdefault\fR, i.e. to use
@@ -214,17 +341,24 @@ Normally the server only listens on a UNIX domain socket.
 .TP
 .B lock yes\fR|\fBno
 Determines whether the server locks against concurrent operation.  Default is
-\fByes\fR.
+\fByes\fR.  There is no good reason to set this to \fBno\fR and the option will
+probably be removed in a future version.
 .TP
 .B mixer \fIPATH\fR
 The path to the mixer device, if you want access to the volume control,
-e.g. \fB/dev/mixer\fR.
+e.g. \fB/dev/mixer\fR (the default).
 .TP
-.B multicast_ttl \fIHOPS\fR
-Set the maximum number of hops to send multicast packets.  This only applies is
+.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 if
+\fBspeaker_backend\fR is set to \fBnetwork\fR and \fBbroadcast\fR is actually a
+multicast address.  The default is 1.
+.TP
 .B namepart \fIPART\fR \fIREGEXP\fR \fISUBST\fR [\fICONTEXT\fR [\fIREFLAGS\fR]]
 Determines how to extract trackname part \fIPART\fR from a 
 track name (with the collection root part removed).
@@ -249,7 +383,15 @@ that aren't in the original track name will lead to confusing results.
 .IP
 If you supply no \fBnamepart\fR directives at all then a default set will be
 supplied automatically.  But if you supply even one then you must supply all of
-them.  See the example config file for the defaults.
+them.  The defaults are equivalent to:
+.PP
+.nf
+namepart title  "/([0-9]+ *[-:] *)?([^/]+)\\.[a-zA-Z0-9]+$" $2 display
+namepart title  "/([^/]+)\\.[a-zA-Z0-9]+$"                  $1 sort
+namepart album  "/([^/]+)/[^/]+$"                          $1 *
+namepart artist "/([^/]+)/[^/]+/[^/]+$"                    $1 *
+namepart ext    "(\\.[a-zA-Z0-9]+)$"                        $1 *
+.fi
 .TP
 .B nice_rescan \fIPRIORITY\fR
 Set the recan subprocess priority.  The default is 10.
@@ -320,6 +462,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,7 +479,7 @@ to 3600, i.e. one hour.
 .TP
 .B queue_pad \fICOUNT\fR
 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.
+tracks will be added until the queue is at least this big.  The default is 10.
 .TP
 .B sample_format \fIBITS\fB/\fIRATE\fB/\fICHANNELS
 Describes the sample format expected by the \fBspeaker_command\fR (below).  The
@@ -380,8 +532,7 @@ 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.
+Use the OSS (/dev/dsp) API.  Not available on all platforms.
 .TP
 .B command
 Execute a command.  This is the default if
@@ -397,8 +548,9 @@ to receive and play the resulting stream on Linux and OS X.
 .TP
 .B sox_generation \fB0\fR|\fB1
 Determines whether calls to \fBsox\fR(1) should use \fB-b\fR, \fB-x\fR, etc (if
-the generation is 0) or \fB-\fIbits\fR, \fB-L\fR etc (if it is 1).  The default
-is 0.
+the generation is 0) or \fB-\fIbits\fR, \fB-L\fR etc (if it is 1).  See the
+documentation for your installed copy of \fBsox\fR to determine which you need.
+The default is 0.
 .TP
 .B speaker_command \fICOMMAND
 Causes the speaker subprocess to pipe audio data into shell command
@@ -413,20 +565,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.
@@ -434,10 +572,30 @@ 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.
+.IP
+There is a default set of stopwords built in, but this option can be used to
+augment or replace that list.
+.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.
+.TP
+.B user \fIUSER\fR
+Specifies the user to run as.  Only makes sense if invoked as root (or
+the target user).
 .SS "Client Configuration"
 .TP
 .B connect \fIHOST SERVICE\fR
@@ -445,15 +603,29 @@ Connect to the address specified by \fIHOST\fR and port specified by
 \fISERVICE\fR.
 .SS "Web Interface Configuration"
 .TP
+.B mail_sender \fIADDRESS\fR
+The email address that appears in the From: field of any mail messages sent by
+the web interface.  This must be set if you have online registration enabled.
+.TP
 .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 smtp_server \fIHOSTNAME\fR
+The hostname (or address) of the SMTP server to use for sending mail.  The
+default is 127.0.0.1.
+.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.
@@ -474,64 +646,39 @@ match then each is executed in order.
 .IP
 If you supply no \fBtransform\fR directives at all then a default set will be
 supplied automatically.  But if you supply even one then you must supply all of
-them.  See the example config file for the defaults.
+them.  The defaults are:
+.PP
+.nf
+transform track "^.*/([0-9]+ *[-:] *)?([^/]+)\\.[a-zA-Z0-9]+$" $2 display
+transform track "^.*/([^/]+)\\.[a-zA-Z0-9]+$"        $1 sort
+transform dir   "^.*/([^/]+)$"                      $1 *
+transform dir   "^(the) ([^/]*)"                    "$2 $1" sort i
+transform dir   "[[:punct:]]"                       "" sort g
+.fi
 .TP
 .B url \fIURL\fR
 Specifies the URL of the web interface.  This URL will be used in
-generated web pages.
+generated web pages.  The default is inferred at runtime, so this option no
+longer needs to be specified.
 .IP
 This must be the full URL, e.g. \fBhttp://myhost/cgi-bin/jukebox\fR and not
 \fB/cgi-bin/jukebox\fR.
 .SS "Authentication Configuration"
-.TP
-.B allow \fIUSERNAME\fR \fIPASSWORD\fR
-Specify a username/password pair.
+These options would normally be used in \fI~\fRUSER\fI/.disorder/passwd\fR or
+\fIpkgconfdir/config.\fRUSER.
 .TP
 .B password \fIPASSWORD\fR
 Specify password.
 .TP
-.B trust \fIUSERNAME\fR
-Allow \fIUSERNAME\fR to perform privileged operations such as shutting
-down or reconfiguring the daemon, or becoming another user.
-.TP
-.B user \fIUSER\fR
-Specifies the user to run as.  Only makes sense if invoked as root (or
-the target user).
-.TP
 .B username \fIUSERNAME\fR
 Specify username.  The default is taken from the environment variable
 \fBLOGNAME\fR.
-.PP
-Configuration files are read in the following order:
-.TP
-.I pkgconfdir/config
-.TP
-.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
-exists must be readable only by the relevant user.  Would normally
-contain a \fBpassword\fR directive.
-.TP
-.I ~\fRUSER\fI/.disorder/passwd
-Per-user client configuration.  Optional but if it exists must be
-readable only by the relevant user.  Would normally contain a
-\fBpassword\fR directive.
 .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.
-.IP
-Tags can contain any printing character except comma.  Leading and trailing
-spaces are not significant but internal spaces are.  Tags in a list are
-separated by commas.
 .TP
 .B prohibited-tags
 If this is set an nonempty then randomly played tracks will never have any of
@@ -544,6 +691,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.
@@ -615,9 +770,10 @@ Additionally, other standard files are included by these:
 Included at the end of the main content \fB<DIV>\fR element.
 .TP
 .B topbar.html
-Included at the start of the \fB<BODY>\fR element.  (This supplants
-\fBsidebar.html\fR, though the latter is still available; override label
-\fBmenu\fR to choose between them.)
+Included at the start of the \fB<BODY>\fR element.
+.TP
+.B topbarend.html
+Included at the end of the \fB<BODY>\fR element.
 .TP
 .B stdhead.html
 Included in the \fB<HEAD>\fR element.
@@ -683,7 +839,7 @@ If there are no arguments, or all the arguments are \fBtrue\fB, then expands to
 \fBtrue\fR, otherwise to \fBfalse\fR.
 .TP
 .B @arg:\fINAME\fB@
-Expands to the value of CGI script argument \fINAME\fR.
+Expands to the value of CGI argument \fINAME\fR.
 .TP
 .B @basename@
 The basename of the current directory component, in \fB@navigate@\fR.
@@ -717,7 +873,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
@@ -778,6 +934,10 @@ file for full documentation of the labels used by the standard templates.
 .B @length@
 Expands to the length of the current track.
 .TP
+.B @movable@
+Expands to \fBtrue\fR if the current track is movable, otherwise to
+\fBfalse\fR.
+.TP
 .B @navigate{\fIDIRECTORY\fB}{\fITEMPLATE\fB}
 Expands \fITEMPLATE\fR for each component of \fIDIRECTORY\fR in turn.
 Use \fB@dirname\fR and \fB@basename@\fR to get the components of the path to
@@ -812,12 +972,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.
@@ -853,9 +1019,25 @@ Expands to \fBtrue\fR if random play is currently enabled, otherwise to
 Expands \fITEMPLATE\fR repeatedly using the each recently played track in turn
 as the current track.  The most recently played track comes first.
 .TP
+.B @removable@
+Expands to \fBtrue\fR if the current track is removable, otherwise to
+\fBfalse\fR.
+.TP
 .B @resolve{\fITRACK\fB}@
 Resolve aliases for \fITRACK\fR and expands to the result.
 .TP
+.B @right{\fIRIGHT\fB}@
+Exapnds to \fBtrue\fR if the user has right \fIRIGHT\fR, otherwise to
+\fBfalse\fR.
+.TP
+.B @right{\fIRIGHT\fB}{\fITRUEPART\fB}{\fIFALSEPART\fB}@
+Expands to \fITRUEPART\fR if the user right \fIRIGHT\fR, otherwise to
+\fIFALSEPART\fR (which may be omitted).
+.TP
+.B @scratchable@
+Expands to \fBtrue\fR if the currently playing track is scratchable, otherwise
+to \fBfalse\fR.
+.TP
 .B @search{\fIPART\fB}\fR[\fB{\fICONTEXT\fB}\fR]\fB{\fITEMPLATE\fB}@
 Expands \fITEMPLATE\fR once for each group of search results that have
 a common value of track part \fIPART\fR.
@@ -952,11 +1134,14 @@ Expands to the canonical URL as defined in \fIpkgconfdir/config\fR.
 .B @urlquote{\fISTRING\fB}@
 URL-quote \fISTRING\fR.
 .TP
+.B @user@
+The current username.  This will be "guest" if nobody is logged in.
+.TP
 .B @version@
 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@