From: Richard Kettlewell Date: Sun, 13 Jul 2008 15:03:35 +0000 (+0100) Subject: Variuos bits of documentation improvement. In particular preferences X-Git-Tag: 4.2~7 X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/commitdiff_plain/3d1452ab8e309d156ac4bd1619087ffbe78ef311?ds=inline Variuos bits of documentation improvement. In particular preferences are now split out to a new man page. --- diff --git a/.bzrignore b/.bzrignore index 22ff521..a4501f9 100644 --- a/.bzrignore +++ b/.bzrignore @@ -195,3 +195,5 @@ libtests/Makefile cgi/Makefile libtests/index.html libtests/t-eventdist +doc/disorder_preferences.5 +doc/disorder_preferences.5.html diff --git a/doc/Makefile.am b/doc/Makefile.am index bf5dae3..27f3639 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -25,7 +25,8 @@ man_MANS=disorderd.8 disorder.1 disorder.3 disorder_config.5 disorder-dump.8 \ 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 \ @@ -33,7 +34,7 @@ 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 @@ -90,7 +91,7 @@ EXTRA_DIST=disorderd.8.in disorder.1.in disorder_config.5.in \ 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 diff --git a/doc/disorder.1.in b/doc/disorder.1.in index 9de40a9..9f9d80f 100644 --- a/doc/disorder.1.in +++ b/doc/disorder.1.in @@ -35,6 +35,10 @@ If no commands are specified then \fBdisorder\fR connects to the 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 @@ -99,9 +103,11 @@ Only files with a basename matching the regexp will be returned. .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. @@ -146,6 +152,7 @@ Report the currently playing track. .TP .B prefs \fITRACK\fR Display all the preferences for \fITRACK\fR. +See \fBdisorder_preferences\fR (5). .TP .B queue List the current queue. @@ -238,9 +245,11 @@ For example: .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. @@ -269,9 +278,11 @@ List known tags. .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. @@ -289,67 +300,6 @@ and 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. @@ -406,9 +356,6 @@ The README recommends using \fBjukebox\fR for this purpose but it could be different locally. .SH ENVIRONMENT .TP -.B LOGNAME -The default username. -.TP .B HOME The user's home directory. .TP @@ -428,7 +375,8 @@ Per-user password file 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: diff --git a/doc/disorder_config.5.in b/doc/disorder_config.5.in index ea3a4bf..20c9e8b 100644 --- a/doc/disorder_config.5.in +++ b/doc/disorder_config.5.in @@ -37,7 +37,7 @@ See \fBdisorder\fR(3) for more details about this. 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 @@ -50,6 +50,7 @@ the displayed track titles are not lexically sorted. .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 @@ -712,7 +713,7 @@ Specify password. .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 @@ -780,34 +781,6 @@ 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. .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. @@ -863,7 +836,7 @@ name and \fBext\fR which is the filename extension, including the initial dot .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 diff --git a/doc/disorder_preferences.5.in b/doc/disorder_preferences.5.in new file mode 100644 index 0000000..4aca881 --- /dev/null +++ b/doc/disorder_preferences.5.in @@ -0,0 +1,117 @@ +.\" +.\" 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: diff --git a/templates/help.tmpl b/templates/help.tmpl index 5e8169e..ecc66f2 100644 --- a/templates/help.tmpl +++ b/templates/help.tmpl @@ -261,6 +261,10 @@ USA box at the bottom can be used to selectivel enable or disable it for individual tracks.

+

See disorder_preferences(5) + for full documentation of track preferences.

+

Login

@@ -329,6 +333,9 @@ USA

disorder_templates(5) - template language

+

disorder_preferences(5) - + per-track and global preferences

+

disorder(1) - command line client