@image expansion

[disorder] / doc / disorder_config.5.in

diff --git a/doc/disorder_config.5.in b/doc/disorder_config.5.in
index 097feb8069b9db639fb0240d75d55f78eac9214e..c9b20618a381435dce735b0c309b0e836024fcf7 100644 (file)
--- a/doc/disorder_config.5.in
+++ b/doc/disorder_config.5.in
@@ -214,12 +214,12 @@ Configuration files are read in the following order:
 Should be readable only by the jukebox group.
 Not really useful any more and will be abolished in future.
 .TP
 Should be readable only by the jukebox group.
 Not really useful any more and will be abolished in future.
 .TP

-.I ~\fRUSER\fI/.disorder/passwd
+.I ~\fRUSERNAME\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.
 .TP
 Per-user client configuration.
 Optional but if it exists must be readable only by the relevant user.
 Would normally contain a \fBpassword\fR directive.
 .TP

-.I pkgconfdir/config.\fRUSER
+.I pkgconfdir/config.\fRUSERNAME

 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.
 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.


@@ -355,7 +355,7 @@ 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.
 .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.
+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
 If no encoding is specified then the current locale's character encoding
 is used.
 .IP


@@ -368,6 +368,15 @@ It's best to explicitly specify it to be certain.
 passed to the plugin module.
 It must be an absolute path and should not end with a "/".
 .TP
 passed to the plugin module.
 It must be an absolute path and should not end with a "/".
 .TP

+.B cookie_key_lifetime \fISECONDS\fR
+Lifetime of the signing key used in constructing cookies.  The default is one
+week.
+.TP
+.B cookie_login_lifetime \fISECONDS\fR
+Lifetime of a cookie enforced by the server.  When the cookie expires the user
+will have to log in again even if their browser has remembered the cookie that
+long.  The default is one day.
+.TP

 .B default_rights \fIRIGHTS\fR
 Defines the set of rights given to new users.
 The argument is a comma-separated list of rights.
 .B default_rights \fIRIGHTS\fR
 Defines the set of rights given to new users.
 The argument is a comma-separated list of rights.


@@ -395,6 +404,9 @@ default is.
 .B gap \fISECONDS\fR
 Specifies the number of seconds to leave between tracks.
 The default is 0.
 .B gap \fISECONDS\fR
 Specifies the number of seconds to leave between tracks.
 The default is 0.

+.IP
+NB this option currently DOES NOT WORK.  If there is genuine demand it might be
+reinstated.

 .TP
 .B history \fIINTEGER\fR
 Specifies the number of recently played tracks to remember (including
 .TP
 .B history \fIINTEGER\fR
 Specifies the number of recently played tracks to remember (including


@@ -509,20 +521,20 @@ The maximum days that a track can survive in the database of newly added
 tracks.
 The default is 31.
 .TP
 tracks.
 The default is 31.
 .TP

-.B player \fIPATTERN\fR \fIMODULE\fR [\fIOPTIONS.. [\fB--\fR]] \fIARGS\fR...
+.B player \fIPATTERN\fR \fIMODULE\fR [\fIOPTIONS.. [\fB\-\-\fR]] \fIARGS\fR...

 Specifies the player for files matching the glob \fIPATTERN\fR.
 \fIMODULE\fR specifies which plugin module to use.
 .IP
 The following options are supported:
 .RS
 .TP
 Specifies the player for files matching the glob \fIPATTERN\fR.
 \fIMODULE\fR specifies which plugin module to use.
 .IP
 The following options are supported:
 .RS
 .TP

-.B --wait-for-device\fR[\fB=\fIDEVICE\fR]
+.B \-\-wait\-for\-device\fR[\fB=\fIDEVICE\fR]

 Waits (for up to a couple of seconds) for the default, or specified, libao
 device to become openable.
 .TP
 Waits (for up to a couple of seconds) for the default, or specified, libao
 device to become openable.
 .TP

-.B --
+.B \-\-

 Defines the end of the list of options.
 Defines the end of the list of options.

-Needed if the first argument to the plugin starts with a "-".
+Needed if the first argument to the plugin starts with a "\-".

 .RE
 .IP
 The following are the standard modules:
 .RE
 .IP
 The following are the standard modules:


@@ -581,6 +593,16 @@ The default is 10.
 The minimum number of seconds that must elapse between password reminders.
 The default is 600, i.e. 10 minutes.
 .TP
 The minimum number of seconds that must elapse between password reminders.
 The default is 600, i.e. 10 minutes.
 .TP

+.B remote_userman yes\fR|\fBno
+User management over TCP connection is only allowed if this is set to
+\fByes\fR.  By default it is set to \fBno\fR.
+.TP
+.B replay_min \fISECONDS\fR
+The minimum number of seconds that must elapse after a track has been played
+before it can be picked at random.  The default is 8 hours.  If this is set to
+0 then there is no limit, though current \fBdisorder-choose\fR will not pick
+anything currently listed in the recently-played list.
+.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 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:


@@ -621,8 +643,8 @@ Signals are specified by their full C name, i.e. \fBSIGINT\fR and not \fBINT\fR
 or \fBInterrupted\fR or whatever.
 .TP
 .B sox_generation \fB0\fR|\fB1
 or \fBInterrupted\fR or whatever.
 .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).
+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).

 See the documentation for your installed copy of \fBsox\fR to determine
 which you need.
 The default is 0.
 See the documentation for your installed copy of \fBsox\fR to determine
 which you need.
 The default is 0.


@@ -673,7 +695,7 @@ Specifies the module used to calculate the length of files matching
 If \fBtracklength\fR is used without arguments then the list of modules is
 cleared.
 .TP
 If \fBtracklength\fR is used without arguments then the list of modules is
 cleared.
 .TP

-.B user \fIUSER\fR
+.B user \fIUSERNAME\fR

 Specifies the user to run as.
 Only makes sense if invoked as root (or the target user).
 .SS "Client Configuration"
 Specifies the user to run as.
 Only makes sense if invoked as root (or the target user).
 .SS "Client Configuration"


@@ -750,8 +772,9 @@ longer needs to be specified.
 This must be the full URL, e.g. \fBhttp://myhost/cgi-bin/jukebox\fR and not
 \fB/cgi-bin/jukebox\fR.
 .SS "Authentication Configuration"
 This must be the full URL, e.g. \fBhttp://myhost/cgi-bin/jukebox\fR and not
 \fB/cgi-bin/jukebox\fR.
 .SS "Authentication Configuration"

-These options would normally be used in \fI~\fRUSER\fI/.disorder/passwd\fR or
-\fIpkgconfdir/config.\fRUSER.
+These options would normally be used in \fI~\fRUSERNAME\fI/.disorder/passwd\fR
+or
+\fIpkgconfdir/config.\fRUSERNAME.

 .TP
 .B password \fIPASSWORD\fR
 Specify password.
 .TP
 .B password \fIPASSWORD\fR
 Specify password.


@@ -760,13 +783,13 @@ Specify password.
 Specify username.
 The default is taken from the environment variable \fBLOGNAME\fR.
 .SH "GLOBAL PREFERENCES"
 Specify username.
 The default is taken from the environment variable \fBLOGNAME\fR.
 .SH "GLOBAL PREFERENCES"

-These are the values set with \fBset-global\fR.
+These are the values set with \fBset\-global\fR.

 .TP
 .TP

-.B required-tags
+.B required\-tags

 If this is set an nonempty then randomly played tracks will always have at
 least one of the listed tags.
 .TP
 If this is set an nonempty then randomly played tracks will always have at
 least one of the listed tags.
 .TP

-.B prohibited-tags
+.B prohibited\-tags

 If this is set an nonempty then randomly played tracks will never have any of
 the listed tags.
 .TP
 If this is set an nonempty then randomly played tracks will never have any of
 the listed tags.
 .TP


@@ -775,7 +798,7 @@ If unset or \fByes\fR then play is enabled.
 Otherwise it is disabled.
 Use \fBdisable\fR rather than setting it directly.
 .TP
 Otherwise it is disabled.
 Use \fBdisable\fR rather than setting it directly.
 .TP

-.B random-play
+.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.
 If unset or \fByes\fR then random play is enabled.
 Otherwise it is disabled.
 Use \fBdisable\fR rather than setting it directly.


@@ -884,14 +907,20 @@ character reference, e.g. \fBý\fR.
 Use \fB@\fR to insert a literal \fB@\fR without falling foul of
 the expansion syntax.
 .SS "Expansion Syntax"
 Use \fB@\fR to insert a literal \fB@\fR without falling foul of
 the expansion syntax.
 .SS "Expansion Syntax"

-Expansions are surrounded by at ("@") symbols take the form of a keyword
-followed by zero or more arguments.
-Arguments may either be quoted by curly brackets ("{" and "}") or separated
+An expansion starts with an at ("@") symbol and takes the form of an expansion
+name followed by zero or more arguments.
+.PP
+Arguments can be quoted by curly brackets ("{" and "}") or separated

 by colons (":").
 Both kinds may be mixed in a single expansion, though doing so seems
 likely to cause confusion.
 The descriptions below contain suggested forms for each expansion.
 .PP
 by colons (":").
 Both kinds may be mixed in a single expansion, though doing so seems
 likely to cause confusion.
 The descriptions below contain suggested forms for each expansion.
 .PP

+An expansion is terminated by another "@" symbol, but this is optional in the
+specific case that the last argument is quoted by curly brackets and it is
+followed by whitespace and then some character that is not "{" (since that
+could be interpreted as a further argument).
+.PP

 Leading and trailing whitespace in unquoted arguments is ignored, as is
 whitespace (including newlines) following a close bracket ("}").
 .PP
 Leading and trailing whitespace in unquoted arguments is ignored, as is
 whitespace (including newlines) following a close bracket ("}").
 .PP


@@ -1122,7 +1151,7 @@ Expands \fITEMPLATE\fR repeatedly using the each track on the queue in turn as
 the current track.
 The track at the head of the queue comes first.
 .TP
 the current track.
 The track at the head of the queue comes first.
 .TP

-.B @random-enabled@
+.B @random\-enabled@

 Expands to \fBtrue\fR if random play is currently enabled, otherwise to
 \fBfalse\fR.
 .TP
 Expands to \fBtrue\fR if random play is currently enabled, otherwise to
 \fBfalse\fR.
 .TP


@@ -1168,7 +1197,7 @@ Usually you want \fBdisplay\fR for everything except the title and
 If you use \fBsort\fR for artist and album then you are likely to get
 strange effects.
 .TP
 If you use \fBsort\fR for artist and album then you are likely to get
 strange effects.
 .TP

-.B @server-version@
+.B @server\-version@

 Expands to the server's version string.
 .TP
 .B @shell{\fICOMMAND\fB}@
 Expands to the server's version string.
 .TP
 .B @shell{\fICOMMAND\fB}@


@@ -1376,10 +1405,10 @@ Expands the \fBplaying.html\fR template rather than redirecting.
 .IP
 This is the default if \fBaction\fR is missing.
 .TP
 .IP
 This is the default if \fBaction\fR is missing.
 .TP

-.B "random-disable"
+.B "random\-disable"

 Disables random play.
 .TP
 Disables random play.
 .TP

-.B "random-enable"
+.B "random\-enable"

 Enables random play.
 .TP
 .B "disable"
 Enables random play.
 .TP
 .B "disable"


@@ -1454,7 +1483,7 @@ In addition there are two built-in parts, \fBpath\fR which is the whole path
 name and \fBext\fR which is the filename extension, including the initial dot
 (or the empty string if there is not extension).
 .SH "SEE ALSO"
 name and \fBext\fR which is the filename extension, including the initial dot
 (or the empty string if there is not extension).
 .SH "SEE ALSO"

-\fBdisorder\fR(1), \fBsox\fR(1), \fBdisorderd\fR(8), \fBdisorder-dump\fR(8),
+\fBdisorder\fR(1), \fBsox\fR(1), \fBdisorderd\fR(8), \fBdisorder\-dump\fR(8),

 \fBpcrepattern\fR(3)
 .\" Local Variables:
 .\" mode:nroff
 \fBpcrepattern\fR(3)
 .\" Local Variables:
 .\" mode:nroff