From c0c23a60ef1189000787892f40f120240746e7a3 Mon Sep 17 00:00:00 2001 Message-Id: From: Mark Wooding Date: Sun, 24 Feb 2008 18:59:03 +0000 Subject: [PATCH] Put a newline after end-of-sentence "." in man pages. I'm advised that groff handles this specially. Organization: Straylight/Edgeware From: Richard Kettlewell --- doc/disobedience.1.in | 155 +++++---- doc/disorder-dbupgrade.8.in | 24 +- doc/disorder-deadlock.8.in | 11 +- doc/disorder-decode.8.in | 4 +- doc/disorder-dump.8.in | 43 +-- doc/disorder-normalize.8 | 10 +- doc/disorder-playrtp.1.in | 42 ++- doc/disorder-rescan.8.in | 11 +- doc/disorder-speaker.8 | 9 +- doc/disorder-stats.8.in | 10 +- doc/disorder.1.in | 136 ++++---- doc/disorder.3 | 124 +++---- doc/disorder_config.5.in | 630 ++++++++++++++++++++---------------- doc/disorder_protocol.5.in | 303 +++++++++-------- doc/disorderd.8.in | 46 ++- doc/disorderfm.1.in | 28 +- doc/tkdisorder.1 | 12 +- 17 files changed, 914 insertions(+), 684 deletions(-) diff --git a/doc/disobedience.1.in b/doc/disobedience.1.in index cc17756..b6c3f73 100644 --- a/doc/disobedience.1.in +++ b/doc/disobedience.1.in @@ -41,7 +41,8 @@ This has the following options: Select all tracks in whichever of the Queue or Recent tabs are showing. .TP .B Properties -Edit the details of the selected tracks. See +Edit the details of the selected tracks. +See .B "Properties Window" below. .SS "Control Menu" @@ -54,11 +55,12 @@ Interrupts the currently playing track. Pause and resume the current track. .TP .B "Random play" -Enable and disable random play. Does not take effect until the currently -playing track finishes. +Enable and disable random play. +Does not take effect until the currently playing track finishes. .TP .B "Network player" -Enables or disables network play. See +Enables or disables network play. +See .B "NETWORK PLAY" below. .SS "Help Menu" @@ -74,42 +76,48 @@ The scratch button, a red cross, can be used to interrupt the currently playing track. .TP .B "Random play button" -The random play button can be used to enable and disable random play. It does -not take effect until the currently playing track finishes. +The random play button can be used to enable and disable random play. +It does not take effect until the currently playing track finishes. .TP .B "Play button" -The play button controls whether tracks will be played at all. As above it -does not take effect until the currently playing track finishes. +The play button controls whether tracks will be played at all. +As above it does not take effect until the currently playing track finishes. .TP .B "Network play button" -The network play buttons enables or disables network play. See +The network play buttons enables or disables network play. +See .B "NETWORK PLAY" below. .TP .B "Volume slider" The volume slider indicates the current volume level and can be used to adjust -it. 0 is silent and 10 is maximum volume. +it. +0 is silent and 10 is maximum volume. .TP .B "Balance slider" The balance slider indicates the current balance and can be used to adjust it. -1 means only the left speaker, 0 means both speakers at equal volume and +1 means the only the right speaker. .SS "Queue Tab" -This displays the currently playing track and the queue. The currently playing -track is at the top and has a green background. Queued tracks appear below it -and have alternating red and white backgrounds. +This displays the currently playing track and the queue. +The currently playing track is at the top and has a green background. +Queued tracks appear below it and have alternating red and white backgrounds. .PP -The left button can be use to select and deselect tracks. On its own it just -selects the pointed track and deselects everything else. With CTRL it flips -the state of the pointed track without affecting anything else. With SHIFT it -selects every track from the last click to the current position and deselects -everything else. With both CTRL and SHIFT it selects everything from the last -click to the current position without deselecting anything. +The left button can be use to select and deselect tracks. +On its own it just selects the pointed track and deselects everything else. +With CTRL it flips the state of the pointed track without affecting anything +else. +With SHIFT it selects every track from the last click to the current position +and deselects everything else. +With both CTRL and SHIFT it selects everything from the last click to the +current position without deselecting anything. .PP -The right button pops up a menu. This has the following options: +The right button pops up a menu. +This has the following options: .TP .B Properties -Edit the details of the selected tracks. See +Edit the details of the selected tracks. +See .B "Properties Window" below. .TP @@ -117,19 +125,21 @@ below. Select all tracks. .TP .B Scratch -Interrupt the currently playing track. (Note that this appears even if you -right click over a queued track rather than the currently playing track.) +Interrupt the currently playing track. +(Note that this appears even if you right click over a queued track rather +than the currently playing track.) .TP .B Remove Remove the selected tracks from the queue. .SS "Recent Tab" This displays recently played tracks, the most recent at the top. .PP -The left button functions as above. The right button pops up a menu with the -following options: +The left button functions as above. +The right button pops up a menu with the following options: .TP .B Properties -Edit the details of the selected tracks. See +Edit the details of the selected tracks. +See .B "Properties Window" below. .TP @@ -138,24 +148,26 @@ Select all tracks. .SS "Choose Tab" This displays all the tracks known to the server in a tree structure. .PP -Directories are represented with an arrow to their left. This can be clicked -to reveal or hide the contents of the directory. The top level "directories" -break up tracks by their first letter. +Directories are represented with an arrow to their left. +This can be clicked to reveal or hide the contents of the directory. +The top level "directories" break up tracks by their first letter. .PP -Playable files are represented by their name. If they are playing or in the -queue then a notes icon appears next to them. +Playable files are represented by their name. +If they are playing or in the queue then a notes icon appears next to them. .PP -Left clicking on a file will select it. As with the queue tab you can use -SHIFT and CTRL to select multiple files. +Left clicking on a file will select it. +As with the queue tab you can use SHIFT and CTRL to select multiple files. .PP -The text box at the top is a search form. If you enter search terms here then -tracks containing all those words will be highlighted. You can also -limit the results to tracks with particular tags, by including \fBtag:\fITAG\fR -for each tag. +The text box at the top is a search form. +If you enter search terms here then tracks containing all those words will be +highlighted. +You can also limit the results to tracks with particular tags, by including +\fBtag:\fITAG\fR for each tag. .PP -To start a new search just edit the contents of the search box. The cancel -button to its right clears the current search. The up and down arrows will -scroll the window to make the previous or next search result visible. +To start a new search just edit the contents of the search box. +The cancel button to its right clears the current search. +The up and down arrows will scroll the window to make the previous or next +search result visible. .PP Right clicking over a track will pop up a menu with the following options: .TP @@ -163,7 +175,8 @@ Right clicking over a track will pop up a menu with the following options: Play selected tracks. .TP .B Properties -Edit properties of selected tracks. See +Edit properties of selected tracks. +See .B "Properties Window" below. .PP @@ -183,16 +196,17 @@ Select all the tracks in the directory (and deselect everything else). Note that these options do not apply recursively - only the tracks in the relevant directory are affected, not those in its subdirectories. .SS "Added Tab" -This displays a list of tracks recently added to the server's database. The -most recently added track is at the top. +This displays a list of tracks recently added to the server's database. +The most recently added track is at the top. .PP -Left clicking a track will select it. CTRL and SHIFT work as above to select -muliple files. +Left clicking a track will select it. +CTRL and SHIFT work as above to select muliple files. .PP Right clicking over a track will pop up a menu with the following options: .TP .B "Track properties" -Edit properties of selected tracks. See +Edit properties of selected tracks. +See .B "Properties Window" below. .TP @@ -203,7 +217,8 @@ Play selected tracks. Select all tracks. .SS "Login Details Window" The login details window allows you to edit the connection details and -authorization information used by Disobedience. It has four text entry fields: +authorization information used by Disobedience. +It has four text entry fields: .TP .B Hostname The host to connect to. @@ -215,14 +230,16 @@ The service name or port number to connect to. The user name to log in as. .TP .B Password -The password to use when logging in. Note that this is NOT your login password -but is your password to the DisOrder server. +The password to use when logging in. +Note that this is NOT your login password but is your password to the +DisOrder server. .PP It has three buttons: .TP .B Login This button attempts to (re-)connect to the server with the currently displayed -settings. The settings are not saved. +settings. +The settings are not saved. .TP .B Save This button saves the current settings in @@ -237,17 +254,18 @@ edited. The Artist, Album and Title fields determine how the tracks appear in the queue and recently played tabs. .PP -The Tags field determine which tags apply to the track. Tags are separated by -commas and can contain any printing characters except comma. +The Tags field determine which tags apply to the track. +Tags are separated by commas and can contain any printing characters except +comma. .PP The Random checkbox determines whether the track will be picked at random. Random play is enabled for every track by default, but it can be turned off here. .PP The double-headed arrow to the right of each preference will propagate its -value to all the other tracks in the window. For instance, this can be used to -efficiently correct the artist or album fields, or bulk-disable random play for -many tracks. +value to all the other tracks in the window. +For instance, this can be used to efficiently correct the artist or album +fields, or bulk-disable random play for many tracks. .PP Press "OK" to confirm all changes and close the window, "Apply" to confirm changes but keep the window open and "Cancel" to close the window and discard @@ -265,7 +283,8 @@ Quit. .SH "NETWORK PLAY" Network play uses a background .BR disorder-playrtp (1) -process. If you quit Disobedience the player will continue playing and can be +process. +If you quit Disobedience the player will continue playing and can be disabled from a later run of Disobedience. .PP The player will log to @@ -277,7 +296,8 @@ You can stop it without running Disobedience by the command .SH OPTIONS .TP .B --config \fIPATH\fR, \fB-c \fIPATH -Set the configuration file. The default is +Set the configuration file. +The default is .IR pkgconfdir/config . .TP .B --debug\fR, \fB-d @@ -289,8 +309,9 @@ Display a usage message. .B --version\fR, \fB-V Display version number. .SS "GTK+ Options" -Additional options are supported by the GTK+ library. Refer to GTK+ -documentation for further information. Under X11 they include: +Additional options are supported by the GTK+ library. +Refer to GTK+ documentation for further information. +Under X11 they include: .TP .B --display \fIDISPLAY\fR The X display to use. @@ -308,21 +329,23 @@ on the same host as the server then no additional configuration should be required. .PP If it is running on a different host then the easiest way to set it up is to -use the login details window in Disobedience. Enter the connection details, -use Login to connect to the server, and then use Save to store them for future -sessions. +use the login details window in Disobedience. +Enter the connection details, use Login to connect to the server, and then +use Save to store them for future sessions. .PP The other clients read their configuration from the same location so after setting up with Disobedience, tools such as .BR disorder (1) should work as well. .SH BUGS -Disobedience is newly introduced with DisOrder 2.0. There are bound to be -bugs. Please send feedback. +Disobedience is newly introduced with DisOrder 2.0. +There are bound to be bugs. +Please send feedback. .PP There is no particular provision for multiple users of the same computer -sharing a single \fBdisorder-playrtp\fR process. This shouldn't be too much of -a problem in practice but something could perhaps be done given demand. +sharing a single \fBdisorder-playrtp\fR process. +This shouldn't be too much of a problem in practice but something could +perhaps be done given demand. .SH FILES .TP .I ~/.disorder/HOSTNAME-rtp diff --git a/doc/disorder-dbupgrade.8.in b/doc/disorder-dbupgrade.8.in index 3a6c2d7..d7d8460 100644 --- a/doc/disorder-dbupgrade.8.in +++ b/doc/disorder-dbupgrade.8.in @@ -25,17 +25,20 @@ disorder-dbupgrade \- DisOrder Database Upgrader .RI [ PATH ...] .SH DESCRIPTION .B disorder-dbupgrade -is DisOrder's database upgrader. It is invoked by DisOrder when -necessary and does not normally need to be invoked manually. +is DisOrder's database upgrader. +It is invoked by DisOrder when necessary and does not normally need to +be invoked manually. .SH OPTIONS .TP .B --delete-bad-keys\fR, -x -If invalid keys are found in the database then delete them. See +If invalid keys are found in the database then delete them. +See .B "INVALID KEYS" below. .TP .B --fail-bad-keys\fR, -X -If invalid keys are found in the database then fail. See +If invalid keys are found in the database then fail. +See .B "INVALID KEYS" below. .TP @@ -46,10 +49,12 @@ Set the configuration file. Enable debugging. .TP .B --syslog -Log to syslog. This is the default if stderr is not a terminal. +Log to syslog. +This is the default if stderr is not a terminal. .TP .B --no-syslog -Do not log to syslog. This is the default if stderr is a terminal. +Do not log to syslog. +This is the default if stderr is a terminal. .TP .B --help\fR, \fB-h Display a usage message. @@ -58,9 +63,10 @@ Display a usage message. Display version number. .SH "INVALID KEYS" An invalid key is one that is not valid UTF-8 or cannot be converted -to NFC for some reason. By default a warning message is issued and -they are left in the database (if doing so will not compromise its -integrity). The +to NFC for some reason. +By default a warning message is issued and they are left in the +database (if doing so will not compromise its integrity). +The .B -x option can be used to delete them if they are known to be harmless. .SH "SEE ALSO" diff --git a/doc/disorder-deadlock.8.in b/doc/disorder-deadlock.8.in index df6db6f..7f7ad24 100644 --- a/doc/disorder-deadlock.8.in +++ b/doc/disorder-deadlock.8.in @@ -24,8 +24,9 @@ disorder-deadlock \- DisOrder deadlock manager .RI [ OPTIONS ] .SH DESCRIPTION .B disorder-deadlock -is DisOrder's deadlock manager. It is automatically started by the -server and does not need to be invoked manually. +is DisOrder's deadlock manager. +It is automatically started by the server and does not need to +be invoked manually. .SH OPTIONS .TP .B --config \fIPATH\fR, \fB-c \fIPATH @@ -35,10 +36,12 @@ Set the configuration file. Enable debugging. .TP .B --syslog -Log to syslog. This is the default if stderr is not a terminal. +Log to syslog. +This is the default if stderr is not a terminal. .TP .B --no-syslog -Do not log to syslog. This is the default if stderr is a terminal. +Do not log to syslog. +This is the default if stderr is a terminal. .TP .B --help\fR, \fB-h Display a usage message. diff --git a/doc/disorder-decode.8.in b/doc/disorder-decode.8.in index f4ae673..32700f3 100644 --- a/doc/disorder-decode.8.in +++ b/doc/disorder-decode.8.in @@ -25,8 +25,8 @@ disorder-decode \- DisOrder audio decoder .I PATH .SH DESCRIPTION .B disorder-decode -converts MP3, OGG, FLAC and WAV files into DisOrders "raw" format. It is -therefore suitable for use as an +converts MP3, OGG, FLAC and WAV files into DisOrders "raw" format. +It is therefore suitable for use as an .B execraw player. .PP diff --git a/doc/disorder-dump.8.in b/doc/disorder-dump.8.in index fe7e8b4..0f13bc8 100644 --- a/doc/disorder-dump.8.in +++ b/doc/disorder-dump.8.in @@ -34,30 +34,32 @@ is used to dump and restore preferences data. .SH OPTIONS .TP .B --dump -Write preferences data to \fIPATH\fR. This can safely be used whether -or not the server is running. +Write preferences data to \fIPATH\fR. +This can safely be used whether or not the server is running. .TP .B --undump Read preferences data from \fIPATH\fR, replacing (unrecoverably) the -current settings. This should normally only be done while the server -is not running. +current settings. +This should normally only be done while the server is not running. .IP If the server is running then it may hang while the undump completes. .TP .B --recover -Perform database recovery at startup. The server should not be -running if this option is used. +Perform database recovery at startup. +The server should not be running if this option is used. .TP .B --recompute-aliases -Recompute aliases without dumping or undumping the databases. Under -normal circumstances this is never necessary. +Recompute aliases without dumping or undumping the databases. +Under normal circumstances this is never necessary. .TP .B --remove-pathless Remove tracks with no associated path when undumping or when -recomputing aliases. In normal use such tracks are all aliases. +recomputing aliases. +In normal use such tracks are all aliases. .TP .B --config \fIPATH\fR, \fB-c \fIPATH -Set the configuration file. The default is +Set the configuration file. +The default is .IR /etc/disorder/config . .TP .B --debug\fR @@ -76,11 +78,11 @@ Taking a backup of the non-regeneratable parts of DisOrder's databases. .TP .B . Indoctrinating one DisOrder server with the preference values of -another. +another. .PP The output file is versioned, so versions produced from a future -version of DisOrder may be rejected by \fB--undump\fR. It has an end -marker so truncated inputs will also be rejected. +version of DisOrder may be rejected by \fB--undump\fR. +It has an end marker so truncated inputs will also be rejected. .PP The input or output file must be a regular file, as it may be rewound and re-read or re-written multiple times. @@ -89,21 +91,22 @@ The dump or undump operation is carried out inside a single transaction, so it should seem atomic from the point of view of anything else accessing the databases. .PP -The server performs normal database recovery on startup. However if -the database needs normal recovery before an undump can succeed and +The server performs normal database recovery on startup. +However if the database needs normal recovery before an undump can succeed and you don't want to start the server for some reason then the .B --recover -operation is available for this purpose. No other process should be -accessing the database at the time. +operation is available for this purpose. +No other process should be accessing the database at the time. .PP DisOrder does not currently support catastrophic recovery. .PP -This program requires write access to DisOrder's databases. Ideally -therefore it should be run as the same user as the server or as root. +This program requires write access to DisOrder's databases. +Ideally therefore it should be run as the same user as the server or as root. .SH FILES .TP .I pkgconfdir/config -Global configuration file. See \fBdisorder_config\fR(5). +Global configuration file. +See \fBdisorder_config\fR(5). .SH "SEE ALSO" \fBdisorder\fR(1), \fBdisorder_config\fR(5), \fBdisorderd\fR(8) .\" Local Variables: diff --git a/doc/disorder-normalize.8 b/doc/disorder-normalize.8 index 7629439..9db6650 100644 --- a/doc/disorder-normalize.8 +++ b/doc/disorder-normalize.8 @@ -25,8 +25,8 @@ disorder-normalize \- DisOrder audio normalization process .B disorder-normalize is used by .BR disorderd (8) -to convert audio data to a consistent encoding. It is not intended to -be used by ordinary users. +to convert audio data to a consistent encoding. +It is not intended to be used by ordinary users. .SH OPTIONS .TP .B --config \fIPATH\fR, \fB-c \fIPATH @@ -36,10 +36,12 @@ Set the configuration file. Enable debugging. .TP .B --syslog -Log to syslog. This is the default if stderr is not a terminal. +Log to syslog. +This is the default if stderr is not a terminal. .TP .B --no-syslog -Do not log to syslog. This is the default if stderr is a terminal. +Do not log to syslog. +This is the default if stderr is a terminal. .TP .B --help\fR, \fB-h Display a usage message. diff --git a/doc/disorder-playrtp.1.in b/doc/disorder-playrtp.1.in index bdd05ec..16d128a 100644 --- a/doc/disorder-playrtp.1.in +++ b/doc/disorder-playrtp.1.in @@ -52,15 +52,18 @@ Use OSS to play sound. Use Core Audio to play sound. .TP .B --device \fIDEVICE\fR, \fB-D \fIDEVICE\fR -Specifies the audio device to use. The exact meaning of this is -platform-dependent; on Linux it is the ALSA device name. +Specifies the audio device to use. +The exact meaning of this is platform-dependent; on Linux it is the +ALSA device name. .TP .B --config \fIPATH\fR, \fB-C \fIPATH -Set the configuration file. The default is +Set the configuration file. +The default is .IR pkgconfdir/config . .TP .B --socket \fIPATH\fR, \fB-s \fIPATH -Set the control socket. Normally this would not be used manually. +Set the control socket. +Normally this would not be used manually. .TP .B --help\fR, \fB-h Display a usage message. @@ -71,29 +74,33 @@ Display version number. You shouldn't need to use these options. .TP .B --min \fIFRAMES\fR, \fB-m \fIFRAMES\fR -Specifies the buffer low watermark in frames. If the number of frames falls -below this value then playing will be stopped until the buffer fills up. +Specifies the buffer low watermark in frames. +If the number of frames falls below this value then playing will be +stopped until the buffer fills up. .TP .B --buffer \fIFRAMES\fR, \fB-b \fIFRAMES\fR -Specifies the buffer high watermark in frames. Once there are this many frames -in the buffer, playing will be (re-)started. +Specifies the buffer high watermark in frames. +Once there are this many frames in the buffer, playing will be (re-)started. .TP .B --max \fIFRAMES\fR, \fB-x \fIFRAMES\fR -Specifies the maximum buffer size in frames. If there are this many frames in -the buffer then reading from the network socket will be suspended. The default -is four times the \fB--buffer\fR value. +Specifies the maximum buffer size in frames. +If there are this many frames in the buffer then reading from the +network socket will be suspended. +The default is four times the \fB--buffer\fR value. .TP .B --rcvbuf \fIBYTES\fR, \fB-R \fIBYTES\fR -Specifies socket receive buffer size. The default is 131072 (128Kbytes). The -buffer size will not be reduced below the operating system's default. +Specifies socket receive buffer size. +The default is 131072 (128Kbytes). +The buffer size will not be reduced below the operating system's default. .SH "REMOTE CONTROL" The .B --socket option is used by Disobedience to control a background .B disorder-playrtp -daemon. The socket will be created as a UNIX domain stream socket. When a -connection is received a single line is read from it. The following commands -are known: +daemon. +The socket will be created as a UNIX domain stream socket. +When a connection is received a single line is read from it. +The following commands are known: .TP .B stop Causes @@ -103,7 +110,8 @@ to terminate. .B query Causes the string "running" to be sent back. .PP -Other commands are ignored. After the first command the connection is closed. +Other commands are ignored. +After the first command the connection is closed. Only one connection at a time will be serviced. .PP This protocol is not guaranteed to be stable. diff --git a/doc/disorder-rescan.8.in b/doc/disorder-rescan.8.in index 6a204de..bfcf307 100644 --- a/doc/disorder-rescan.8.in +++ b/doc/disorder-rescan.8.in @@ -25,8 +25,9 @@ disorder-rescan \- DisOrder rescanner .RI [ PATH ...] .SH DESCRIPTION .B disorder-rescan -is DisOrder's database rescanner. It is invoked by DisOrder when -necessary and does not need to be invoked manually. +is DisOrder's database rescanner. +It is invoked by DisOrder when necessary and does not need to be +invoked manually. .SH OPTIONS .TP .B --config \fIPATH\fR, \fB-c \fIPATH @@ -36,10 +37,12 @@ Set the configuration file. Enable debugging. .TP .B --syslog -Log to syslog. This is the default if stderr is not a terminal. +Log to syslog. +This is the default if stderr is not a terminal. .TP .B --no-syslog -Do not log to syslog. This is the default if stderr is a terminal. +Do not log to syslog. +This is the default if stderr is a terminal. .TP .B --help\fR, \fB-h Display a usage message. diff --git a/doc/disorder-speaker.8 b/doc/disorder-speaker.8 index b3b2208..0963983 100644 --- a/doc/disorder-speaker.8 +++ b/doc/disorder-speaker.8 @@ -26,7 +26,8 @@ disorder-speaker \- DisOrder output process is used by .BR disorderd (8) to play digital audio with buffering and avoiding gaps between -tracks. It is not intended for direct invocation. +tracks. +It is not intended for direct invocation. .SH OPTIONS .TP .B --config \fIPATH\fR, \fB-c \fIPATH @@ -36,10 +37,12 @@ Set the configuration file. Enable debugging. .TP .B --syslog -Log to syslog. This is the default if stderr is not a terminal. +Log to syslog. +This is the default if stderr is not a terminal. .TP .B --no-syslog -Do not log to syslog. This is the default if stderr is a terminal. +Do not log to syslog. +This is the default if stderr is a terminal. .TP .B --help\fR, \fB-h Display a usage message. diff --git a/doc/disorder-stats.8.in b/doc/disorder-stats.8.in index 4719a3e..683da7e 100644 --- a/doc/disorder-stats.8.in +++ b/doc/disorder-stats.8.in @@ -24,8 +24,8 @@ disorder-stats \- DisOrder statistics .RI [ OPTIONS ] .SH DESCRIPTION .B disorder-stats -reports server statistics. It is used by the server and would not -normally be invoked manually. +reports server statistics. +It is used by the server and would not normally be invoked manually. .SH OPTIONS .TP .B --config \fIPATH\fR, \fB-c \fIPATH @@ -35,10 +35,12 @@ Set the configuration file. Enable debugging. .TP .B --syslog -Log to syslog. This is the default if stderr is not a terminal. +Log to syslog. +This is the default if stderr is not a terminal. .TP .B --no-syslog -Do not log to syslog. This is the default if stderr is a terminal. +Do not log to syslog. +This is the default if stderr is a terminal. .TP .B --help\fR, \fB-h Display a usage message. diff --git a/doc/disorder.1.in b/doc/disorder.1.in index 7a443b7..142ab70 100644 --- a/doc/disorder.1.in +++ b/doc/disorder.1.in @@ -32,13 +32,14 @@ state, etc, and by an administrator to shutdown or reconfigure the daemon. .PP 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. +daemon and then immediately disconnects. +This can be used to test whether the daemon is running. +Otherwise, it executes the commands specified. .SH OPTIONS .TP .B --config \fIPATH\fR, \fB-c \fIPATH -Set the configuration file. The default is +Set the configuration file. +The default is .IR pkgconfdir/config . .TP .B --debug\fR, \fB-d @@ -55,20 +56,22 @@ List all known commands. .SH COMMANDS .TP .B adduser \fIUSER PASSWORD\fR [\fIRIGHTS\fR] -Create a new user. If \fIRIGHTS\fR is not specified then the -\fBdefault_rights\fR setting from the server's configuration file applies. +Create a new user. +If \fIRIGHTS\fR is not specified then the \fBdefault_rights\fR +setting from the server's configuration file applies. .TP .B authorize \fIUSER\fR [\fIRIGHTS\fR] -Create \fIUSER\fR with a random password. \fIUSER\fR must be a UNIX login -user (not just any old string). If \fIRIGHTS\fR is not specified then the -\fBdefault_rights\fR setting from the server's configuration file applies. +Create \fIUSER\fR with a random password. +\fIUSER\fR must be a UNIX login user (not just any old string). +If \fIRIGHTS\fR is not specified then the \fBdefault_rights\fR +setting from the server's configuration file applies. .IP \fI~USER/.disorder/passwd\fR is created with the password in it, so the new user should be able to log in immediately. .IP If writing the \fIpasswd\fR file fails then the user will already have been -created in DisOrder's user database. Use \fBdisorder deluser\fR to remove them -before trying again. +created in DisOrder's user database. +Use \fBdisorder deluser\fR to remove them before trying again. .TP .B deluser \fIUSER\fR Delete a user. @@ -76,8 +79,8 @@ Delete a user. .B dirs \fIDIRECTORY\fR [\fB~\fIREGEXP\fR] List all the directories in \fIDIRECTORY\fR. .IP -An optional regexp may be specified, marked with an initial \fB~\fR. Only -directories with a basename matching the regexp will be returned. +An optional regexp may be specified, marked with an initial \fB~\fR. +Only directories with a basename matching the regexp will be returned. .TP .B disable Disable playing after the current track finishes. @@ -91,8 +94,8 @@ Set some property of a user. .B files \fIDIRECTORY\fR [\fB~\fIREGEXP\fR] List all the files in \fIDIRECTORY\fR. .IP -An optional regexp may be specified, marked with an initial \fB~\fR. Only -files with a basename matching the regexp will be returned. +An optional regexp may be specified, marked with an initial \fB~\fR. +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. @@ -115,7 +118,8 @@ Move .I TRACK by .I DELTA -within the queue. Positive values move towards the head of the queue, negative +within the queue. +Positive values move towards the head of the queue, negative values towards the tail. .IP Note that if you specify a negative value then the @@ -126,11 +130,13 @@ negative value is misinterpreted an an option. .B part \fITRACK\fR \fICONTEXT\fI \fIPART\fR Get a track name part. .IP -\fICONTEXT\fR should be either \fBsort\fR or \fBdisplay\fR. \fBpart\fR is the -part of the name desired, typically \fBartist\fR, \fBalbum\fR or \fBtitle\fR. +\fICONTEXT\fR should be either \fBsort\fR or \fBdisplay\fR. +\fBpart\fR is the part of the name desired, typically \fBartist\fR, +\fBalbum\fR or \fBtitle\fR. .TP .B pause -Pause the current track. (Note that not all players support pausing.) +Pause the current track. +(Note that not all players support pausing.) .TP .B play \fITRACKS\fR... Add \fITRACKS\fR to the end of the queue. @@ -142,7 +148,8 @@ Report the currently playing track. Display all the preferences for \fITRACK\fR. .TP .B queue -List the current queue. The first entry in the list is the next track to play. +List the current queue. +The first entry in the list is the next track to play. .TP .B random-disable Disable random play. @@ -151,8 +158,9 @@ Disable random play. Enable random play. .TP .B recent -List recently played tracks. The first entry is the oldest track, the last -entry is the most recently played one. +List recently played tracks. +The first entry is the oldest track, the last entry is the most +recently played one. .TP .B reconfigure Make the daemon reload its configuration file. @@ -161,9 +169,9 @@ Make the daemon reload its configuration file. Remove a track from the queue. .TP .B rescan -Rescan the filesystem for new tracks. There is an automatic daily rescan but -if you've just added some tracks and want them to show up immediately, use this -command. +Rescan the filesystem for new tracks. +There is an automatic daily rescan but if you've just added some tracks +and want them to show up immediately, use this command. .TP .B resolve \fITRACK\fR Resolve aliases for \fITRACK\fR and print out the real track name. @@ -181,14 +189,15 @@ Scratch the currently playing track. Scratch the currently playing track, provided it has the given ID. .TP .B search \fITERMS\fR -Search for tracks containing all of the listed terms. The terms are -separated by spaces and form a single argument, so must be quoted, -for example: +Search for tracks containing all of the listed terms. +The terms are separated by spaces and form a single argument, +so must be quoted, for example: .IP .B "disorder search 'bowie china'" .IP You can limit the search to tracks with a particular tag, too, using the -\fBtag:\fR modifier. For example: +\fBtag:\fR modifier. +For example: .IP .B "disorder search 'love tag:depressing'" .TP @@ -202,15 +211,17 @@ Set a global preference. Set the volume. .TP .B setup-guest \fR[\fB--no-online-registration\fR] -Create the "guest" user for use by the web interface. This user will have no -password and will only have the "read" and "register" rights, the latter -allowing new users to automatically register themselves via the web interface. +Create the "guest" user for use by the web interface. +This user will have no password and will only have the "read" and +"register" rights, the latter allowing new users to automatically +register themselves via the web interface. .IP With the option \fB--no-online-registration\fR, the "register" right is suppressed and users must be manually created by an administrator. .IP If online registration is desired then \fBmail_sender\fR must be set in the -configuration file. See \fBdisorder_config\fR(5). +configuration file. +See \fBdisorder_config\fR(5). .TP .B shutdown Shut down the daemon. @@ -240,19 +251,21 @@ For .B move and .BR remove , -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. +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. +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. +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. +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 @@ -266,9 +279,9 @@ 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. +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 @@ -279,20 +292,22 @@ 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. +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. .SH NOTES .B disorder -is locale-aware. If you do not set the locale correctly then it may -not handle non-ASCII data properly. +is locale-aware. +If you do not set the locale correctly then it may not handle non-ASCII +data properly. .PP The client determines which user to attempt to authenticate as by examining the -current UID. This can be overridden in a per-user configuration file, see +current UID. +This can be overridden in a per-user configuration file, see \fBdisorder_config\fR(5). .PP See \fBdisorder_protocol\fR(5) for the rights required to run each command. @@ -302,9 +317,11 @@ would not normally have.) This program is not intended to run in a setuid environment. .PP The regexp syntax used by the \fBfiles\fR and \fBdirs\fR commands use the -syntax described in \fBpcrepattern\fR(3). Matching is case-independent. It is -strongly recommended that you quote regexps, since they often contain -characters treated specially by the shell. For example: +syntax described in \fBpcrepattern\fR(3). +Matching is case-independent. +It is strongly recommended that you quote regexps, since they often +contain characters treated specially by the shell. +For example: .PP .B "disorder dirs /Music ~'^(?!the [^t])t'" .SH TROUBLESHOOTING @@ -322,8 +339,8 @@ though this depends on local configuration. .B . Is the track in a known format? Have a look at .I pkgconfdir/config -for the formats recognized by the local installation. The filename matching is -case-sensitive. +for the formats recognized by the local installation. +The filename matching is case-sensitive. .TP .B . Do permissions on the track allow the server to read it? @@ -333,8 +350,9 @@ Do the permissions on the containing directories allow the server to read and execute them? .PP The user the server runs as is determined by the \fBuser\fR directive in the -configuration file. The README recommends using \fBjukebox\fR for this purpose -but it could be different locally. +configuration file. +The README recommends using \fBjukebox\fR for this purpose but it could +be different locally. .SH ENVIRONMENT .TP .B LOGNAME @@ -344,11 +362,13 @@ The default username. The user's home directory. .TP .B LC_ALL\fR, \fBLANG\fR, etc -Current locale. See \fBlocale\fR(7). +Current locale. +See \fBlocale\fR(7). .SH FILES .TP .I pkgconfdir/config -Global configuration file. See \fBdisorder_config\fR(5). +Global configuration file. +See \fBdisorder_config\fR(5). .TP .I ~/.disorder/passwd Per-user password file diff --git a/doc/disorder.3 b/doc/disorder.3 index b4d811d..d425770 100644 --- a/doc/disorder.3 +++ b/doc/disorder.3 @@ -28,9 +28,9 @@ The first half of this man page describes the functions DisOrder provides to plugins; the second half describes the functions that plugins must provide. .SH "MEMORY ALLOCATION" -DisOrder uses a garbage collector internally. Therefore it is recommended that -plugins use the provided memory allocation interface, rather than calling -\fBmalloc\fR(3) etc directly. +DisOrder uses a garbage collector internally. +Therefore it is recommended that plugins use the provided memory +allocation interface, rather than calling \fBmalloc\fR(3) etc directly. .PP .nf \fBvoid *disorder_malloc(size_t); @@ -54,7 +54,8 @@ except that they never fail and you must not put any pointer values in the allocated memory. .IP They may still return a null pointer if asked for a 0-sized -allocation. They do not guarantee to zero out the memory allocated. +allocation. +They do not guarantee to zero out the memory allocated. .PP .nf \fBchar *disorder_strdup(const char *); @@ -85,22 +86,24 @@ some other encoding. .SH LOGGING Standard error doesn't reliably go anywhere in current versions of DisOrder, and whether syslog is to be used varies depending on how the program is -invoked. Therefore plugins should use these functions to log any errors or +invoked. +Therefore plugins should use these functions to log any errors or informational messages. .PP .nf \fBvoid disorder_error(int errno_value, const char *fmt, ...); .fi .IP -Log an error message. If \fBerrno_value\fR is not 0 then the relevant +Log an error message. +If \fBerrno_value\fR is not 0 then the relevant string is included in the error message. .PP .nf \fBvoid disorder_fatal(int errno_value, const char *fmt, ...); .fi .IP -Log an error message and then terminate the process. If -\fBerrno_value\fR is not 0 then the relevant string is included in the +Log an error message and then terminate the process. +If \fBerrno_value\fR is not 0 then the relevant string is included in the error message. .IP .B disorder_fatal @@ -133,7 +136,8 @@ not. .fi .IP This function looks up the value of \fBkey\fR for \fBtrack\fR and -returns a pointer to a copy of it. Do not bother to free the pointer. +returns a pointer to a copy of it. +Do not bother to free the pointer. If the track or key are not found a null pointer is returned. .PP .nf @@ -143,14 +147,16 @@ If the track or key are not found a null pointer is returned. .fi .IP This function sets the value of \fBkey\fR for \fBtrack\fR to -\fBvalue\fR. On success, 0 is returned; on error, -1 is returned. +\fBvalue\fR. +On success, 0 is returned; on error, -1 is returned. .IP If \fBvalue\fR is a null pointer then the preference is deleted. .IP Values starting with an underscore are stored in the tracks database, and are lost if the track is deleted; they should only ever have -values that can be regenerated on demand. Other values are stored in -the prefs database and never get automatically deleted. +values that can be regenerated on demand. +Other values are stored in the prefs database and never get +automatically deleted. .PP .nf \fBconst char *disorder_track_random(void) @@ -162,8 +168,9 @@ Aliases are never returned. Only available in server plugins. .SH "PLUGIN FUNCTIONS" This section describes the functions that you must implement to write various -plugins. All of the plugins have at least one standard implementation -available in the DisOrder source. +plugins. +All of the plugins have at least one standard implementation available +in the DisOrder source. .PP Some functions are listed as only available in server plugins. Currently this means that they are not even defined outside the @@ -178,9 +185,10 @@ These are server plugins defined by the \fBtracklength\fR directive. const char *path); .fi .IP -Called to calculate the length of a track. \fBtrack\fR is the track -name (UTF-8) and \fBpath\fR is the path name if there was one, or a -null pointer otherwise. \fBpath\fR will be the same byte string return from +Called to calculate the length of a track. +\fBtrack\fR is the track name (UTF-8) and \fBpath\fR is the path +name if there was one, or a null pointer otherwise. +\fBpath\fR will be the same byte string return from the scanner plugin, and so presumably encoded according to the filesystem encoding. .IP @@ -205,8 +213,9 @@ This is a server plugin. const char *submitter); .fi .IP -Called when \fBtrack\fR is about to be played. \fBsubmitter\fR identifies the -submitter or is a null pointer if the track was picked for random play. +Called when \fBtrack\fR is about to be played. +\fBsubmitter\fR identifies the submitter or is a null pointer if +the track was picked for random play. .PP .nf \fBvoid disorder_notify_scratch(const char *track, @@ -215,10 +224,10 @@ submitter or is a null pointer if the track was picked for random play. int seconds); .fi .IP -Called when \fBtrack\fR is scratched by \fBscratcher\fR. \fBsubmitter\fR -identifies the submitter or is a null pointer if the track was picked for -random play. \fBseconds\fR is the number of seconds since the track started -playing. +Called when \fBtrack\fR is scratched by \fBscratcher\fR. +\fBsubmitter\fR identifies the submitter or is a null pointer if +the track was picked for random play. +\fBseconds\fR is the number of seconds since the track started playing. .PP .nf \fBvoid disorder_notify_not_scratched(const char *track, @@ -226,8 +235,9 @@ playing. .fi .IP Called when \fBtrack\fR completes without being scratched (an error might have -occurred though). \fBsubmitter\fR identifies the submitter or is a null -pointer if the track was picked for random play. +occurred though). +\fBsubmitter\fR identifies the submitter or is a null pointer if the +track was picked for random play. .PP .nf \fBvoid disorder_notify_queue(const char *track, @@ -235,7 +245,8 @@ pointer if the track was picked for random play. .fi .IP Called when \fBtrack\fR is added to the queue by \fBsubmitter\fR -(which is never a null pointer). Not called for scratches. +(which is never a null pointer). +Not called for scratches. .PP .nf \fBvoid disorder_notify_queue_remove(const char *track, @@ -276,8 +287,8 @@ chosen via the configuration file. \fBvoid disorder_scan(const char *root); .fi .IP -Write a list of files below \fBroot\fR to standard output. Each -filename should be in the encoding defined for this root in the +Write a list of files below \fBroot\fR to standard output. +Each filename should be in the encoding defined for this root in the configuration file and should be terminated by character 0. .IP It is up to the plugin implementor whether they prefer to use stdio or @@ -291,9 +302,9 @@ match them back up to the right collection to call \fBint disorder_check(const char *root, const char *path); .fi .IP -Check whether file \fBpath\fR under \fBroot\fR still exists. Should -return 1 if it exists, 0 if it does not and -1 on error. This is run -in the main server process. +Check whether file \fBpath\fR under \fBroot\fR still exists. +Should return 1 if it exists, 0 if it does not and -1 on error. +This is run in the main server process. .PP Both scan and recheck are executed inside a subprocess, so it will not break the server if they block for an extended period (though of @@ -307,9 +318,10 @@ chosen via the configuration file. extern const unsigned long disorder_player_type; .fi .IP -This defines the player type and capabilities. It should consist of a -single type value ORed with any number of capability values. The -following are known type values: +This defines the player type and capabilities. +It should consist of a single type value ORed with any number of +capability values. +The following are known type values: .RS .TP .B DISORDER_PLAYER_STANDALONE @@ -336,8 +348,8 @@ Supports the pause and resume calls. .fi .IP Called before a track is played, if \fB_PREFORK\fR is set. -\fBtrack\fR is the name of the track in UTF-8. This function must -never block, as it runs inside the main loop of the server. +\fBtrack\fR is the name of the track in UTF-8. +This function must never block, as it runs inside the main loop of the server. .IP The return value will be passed to the functions below as \fBdata\fR. On error, a null pointer should be returned. @@ -347,8 +359,8 @@ On error, a null pointer should be returned. .fi .IP Called after a track has been completed, if \fB_PREFORK\fR is set, for -instance to release the memory used by \fBdata\fR. This function must -never block, as it runs inside the main loop of the server. +instance to release the memory used by \fBdata\fR. +This function must never block, as it runs inside the main loop of the server. .PP .nf \fBvoid disorder_play_track(const char *const *parameters, @@ -363,8 +375,9 @@ Play a track. \fBpath\fR is the path name as originally encoded in the filesystem. This is the value you should ultimately pass to \fBopen\fR(2). .IP -\fBtrack\fR is the path name converted to UTF-8. This value (possibly -converted to some other encoding) should be used in any logs, etc. +\fBtrack\fR is the path name converted to UTF-8. +This value (possibly converted to some other encoding) should be used +in any logs, etc. .IP If there is no meaningful path, or if the track is a scratch (where no filename encoding information is available), \fBpath\fR will be equal @@ -377,16 +390,16 @@ This function is always called inside a fork, and it should not return until playing has finished. .IP DisOrder sends the subprocess a signal if the track is to be scratched -(and when \fBdisorderd\fR is shut down). By default this signal is -\fBSIGKILL\fR but it can be reconfigured. +(and when \fBdisorderd\fR is shut down). +By default this signal is \fBSIGKILL\fR but it can be reconfigured. .PP .nf \fBint disorder_play_pause(long *playedp, void *data); .fi .IP -Pauses the current track, for players that support pausing. This -function must never block, as it runs inside the main loop of the +Pauses the current track, for players that support pausing. +This function must never block, as it runs inside the main loop of the server. .IP On success, should return 0 and set \fB*playedp\fR to the number of @@ -399,33 +412,34 @@ On error, should return -1. \fBvoid disorder_play_resume(void *data); .fi .IP -Resume playing the current track after a pause. This function must -never block, as it runs inside the main loop of the server. +Resume playing the current track after a pause. +This function must never block, as it runs inside the main loop of the server. .SH NOTES There is no special DisOrder library to link against; the symbols are -exported by the executables themselves. +exported by the executables themselves. (You should NOT try to link against \fB-ldisorder\fR.) Plugins must be separately linked against any other libraries they require, even if the DisOrder executables are already linked against them. .PP The easiest approach is probably to develop the plugin inside the -DisOrder tree; then you can just use DisOrder's build system. This -might also make it easier to submit patches if you write something of +DisOrder tree; then you can just use DisOrder's build system. +This might also make it easier to submit patches if you write something of general utility. .PP Failing that you can use Libtool, if you make sure to pass the -\fB-module\fR option. For current versions of DisOrder you only need -the shared object itself, not the \fB.la\fR file. +\fB-module\fR option. +For current versions of DisOrder you only need the shared object +itself, not the \fB.la\fR file. .PP If you know the right runes for your toolchain you could also build the modules more directly. .PP It is possible, up to a point, to implement several plugin interfaces -from within a single shared object. If you ever use any of the -functions that are listed as only being available in server plugins, -though, then you can only use the resulting shared object as a server -plugin. +from within a single shared object. +If you ever use any of the functions that are listed as only being +available in server plugins, though, then you can only use the +resulting shared object as a server plugin. .SH "SEE ALSO" .BR disorderd (8), .BR disorder (1), diff --git a/doc/disorder_config.5.in b/doc/disorder_config.5.in index bf7876c..097feb8 100644 --- a/doc/disorder_config.5.in +++ b/doc/disorder_config.5.in @@ -21,9 +21,9 @@ pkgconfdir/config - DisOrder jukebox configuration .SH DESCRIPTION The purpose of DisOrder is to organize and play digital audio files, under the -control of multiple users. \fIpkgconfdir/config\fR is the primary -configuration file but this man page currently documents all of its various -configuration files. +control of multiple users. +\fIpkgconfdir/config\fR is the primary configuration file but this +man page currently documents all of its various configuration files. .SS Tracks DisOrder can be configured with multiple collections of tracks, indexing them by their filename, and picking players on the basis of filename patterns (for @@ -31,15 +31,18 @@ instance, "*.mp3"). .PP Although the model is of filenames, it is not inherent that there are corresponding real files - merely that they can be interpreted by the chosen -player. See \fBdisorder\fR(3) for more details about this. +player. +See \fBdisorder\fR(3) for more details about this. .PP -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. +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. .SS "Track Names" Track names are derived from filenames under the control of regular expressions, rather than attempting to interpret format-specific embedded name -information. They can be overridden by setting preferences. +information. +They can be overridden by setting preferences. .PP Names for display are distinguished from names for sorting, so with the right underlying filenames an album can be displayed in its original order even if @@ -48,12 +51,13 @@ the displayed track titles are not lexically sorted. 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. .SS "Users And Access Control" -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. +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 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 +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: @@ -101,7 +105,8 @@ User can perform admin operations User can initiate a rescan .TP .B register -User can register new users. Normally only the +User can register new users. +Normally only the .B guest user would have this right. .TP @@ -117,28 +122,32 @@ User can modify global preferences .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 -right password is available. Passwords are never transmitted over TCP/IP -connections in clear, but everything else is. The expected model is that -host-based access control is imposed at the network layer. +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 right password is +available. +Passwords are never transmitted over TCP/IP connections in clear, +but everything else is. +The expected model is that host-based access control is imposed at +the network layer. .SS "Web Interface" The web interface is controlled by a collection of template files, one for each -kind of page, and a collection of option files. These are split up and -separate from the main configuration file to make it more convenient to -override specific bits. +kind of page, and a collection of option files. +These are split up and separate from the main configuration file to +make it more convenient to override specific bits. .PP 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. This model will be changed in a future version.) +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. +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:". +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: @@ -157,18 +166,19 @@ 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. +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 -feed, carriage return, form feed). Comments are started by the number -sign ("#"). +feed, carriage return, form feed). +Comments are started by the number sign ("#"). .PP Fields may be unquoted (in which case they may not contain spaces and may not start with a quotation mark or apostrophe) or quoted by either -quotation marks or apostrophes. Inside quoted fields every character -stands for itself, except that a backslash can only appear as part of -one of the following escape sequences: +quotation marks or apostrophes. +Inside quoted fields every character stands for itself, except that +a backslash can only appear as part of one of the following escape sequences: .TP .B \e\e Backslash @@ -186,44 +196,47 @@ Line feed No other escape sequences are allowed. .PP Within any line the first field is a configuration command and any -further fields are parameters. Lines with no fields are ignored. +further fields are parameters. +Lines with no fields are ignored. .PP After editing the config file use \fBdisorder reconfigure\fR to make -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.) +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 -will be abolished in future. +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 -Per-user client configuration. Optional but if it exists must be -readable only by the relevant user. Would normally contain a -\fBpassword\fR directive. +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 -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. .IP The prefererred location for per-user passwords is \fI~/.disorder/passwd\fR and -\fBdisorder authorize\fR writes there now. +\fBdisorder authorize\fR writes there now. .SS "Global Configuration" .TP .B home \fIDIRECTORY\fR -The home directory for state files. Defaults to +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 plugins \fIPATH\fR -Adds a directory to the plugin path. (This is also used by the web -interface.) +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 @@ -251,42 +264,46 @@ automatically included, but should include the proper extension. The default is \fB{/artist}{/album}{/title}{ext}\fR. .TP .B api \fINAME\fR -Selects the backend used to play sound and to set the volume. The following -options are available: +Selects the backend used to play sound and to set the volume. +The following options are available: .RS .TP .B alsa -Use the ALSA API. This is only available on Linux systems, on which it is the -default. +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. +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. +Use the OSS (/dev/dsp) API. +Not available on all platforms. .TP .B command -Execute a command. This is the default if +Execute a command. +This is the default if .B speaker_command is specified, or if no native is available. .TP .B network -Transmit audio over the network. This is the default if -\fBbroadcast\fR is specified. You can use +Transmit audio over the network. +This is the default if \fBbroadcast\fR is specified. +You can use .BR disorder-playrtp (1) to receive and play the resulting stream on Linux and OS X. .RE .TP .B authorization_algorithm \fIALGORITHM\fR -Defines the algorithm used to authenticate clients. The valid options -are sha1 (the default), sha256, sha384 and sha512. See +Defines the algorithm used to authenticate clients. +The valid options are sha1 (the default), sha256, sha384 and sha512. +See .BR disorder_protocol (5) for more details. .TP .B broadcast \fIADDRESS\fR \fIPORT\fR -Transmit sound data to \fIADDRESS\fR using UDP port \fIPORT\fR. This implies -\fBapi network\fR. +Transmit sound data to \fIADDRESS\fR using UDP port \fIPORT\fR. +This implies \fBapi network\fR. .IP See also \fBmulticast_loop\fR and \fBmulticast_ttl\fR. .TP @@ -300,8 +317,8 @@ For \fBapi oss\fR the possible values are: .RS .TP 8 .B pcm -Output level for the audio device. This is probably what you want and is the -default. +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. @@ -310,14 +327,16 @@ Output level for the PC speaker, if that is connected to the sound card. Output level for alternative codec device. .TP .B vol -Master output level. The OSS documentation recommends against using this, as -it affects all output devices. +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. .IP -For \fBapi alsa\fR, this is the name of the mixer control to use. The default -is \fBPCM\fR. Use \fBamixer scontrols\fR or similar to get a full list. +For \fBapi alsa\fR, this is the name of the mixer control to use. +The default is \fBPCM\fR. +Use \fBamixer scontrols\fR or similar to get a full list. .IP For \fBapi coreaudio\fR, volume setting is not currently supported. .TP @@ -329,26 +348,30 @@ For \fBapi coreaudio\fR, volume setting is not currently supported. 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 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. +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 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. +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. It must be an absolute path and should not -end with a "/". +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 +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 @@ -358,8 +381,9 @@ The default is to allow everything except \fBadmin\fR and \fBregister\fR .B device \fINAME\fR Sound output device. .IP -For \fBapi oss\fR this is the path to the device to use. If it is set to -\fBdefault\fR then \fI/dev/dsp\fR and \fI/dev/audio\fR will be tried. +For \fBapi oss\fR this is the path to the device to use. +If it is set to \fBdefault\fR then \fI/dev/dsp\fR and \fI/dev/audio\fR +will be tried. .IP For \fBapi alsa\fR this is the device name to use. .IP @@ -369,8 +393,8 @@ The default is \fBdefault\fR, which is intended to map to whatever the system's default is. .TP .B gap \fISECONDS\fR -Specifies the number of seconds to leave between tracks. The default -is 0. +Specifies the number of seconds to leave between tracks. +The default is 0. .TP .B history \fIINTEGER\fR Specifies the number of recently played tracks to remember (including @@ -378,14 +402,15 @@ failed tracks and scratches). .TP .B listen \fR[\fIHOST\fR] \fISERVICE\fR Listen for connections on the address specified by \fIHOST\fR and port -specified by \fISERVICE\fR. If \fIHOST\fR is omitted then listens on all -local addresses. +specified by \fISERVICE\fR. +If \fIHOST\fR is omitted then listens on all local addresses. .IP 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. There is no good reason to set this to \fBno\fR and the option will +Determines whether the server locks against concurrent operation. +Default is \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 \fIDEVICE\fR @@ -395,36 +420,38 @@ The mixer device name, if it needs to be specified separately from For \fBapi oss\fR this should be the path to the mixer device and the default is \fI/dev/mixer\fR. .IP -For \fBapi alsa\fR, this is the index of the mixer control to use. The default -is 0. +For \fBapi alsa\fR, this is the index of the mixer control to use. +The default is 0. .IP For \fBapi coreaudio\fR, volume setting is not currently supported. .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 -\fBapi\fR is set to \fBnetwork\fR and \fBbroadcast\fR is actually a -multicast address. +Determines whether multicast packets are loop backed to the sending host. +The default is \fByes\fR. +This only applies if \fBapi\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 -\fBapi\fR is set to \fBnetwork\fR and \fBbroadcast\fR is actually a -multicast address. The default is 1. +Set the maximum number of hops to send multicast packets. +This only applies if \fBapi\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). Used in \fB@recent@\fR, \fB@playing@\fR and \fB@search@\fR. .IP -Track names can be different in different contexts. For instance the sort -string might include an initial track number, but this would be stripped for -the display string. \fICONTEXT\fR should be a glob pattern matching the +Track names can be different in different contexts. +For instance the sort string might include an initial track number, +but this would be stripped for the display string. +\fICONTEXT\fR should be a glob pattern matching the contexts in which this directive will be used. .IP Valid contexts are \fBsort\fR and \fBdisplay\fR. .IP -All the \fBnamepart\fR directives are considered in order. The -first directive for the right part, that matches the desired context, +All the \fBnamepart\fR directives are considered in order. +The first directive for the right part, that matches the desired context, and with a \fIREGEXP\fR that matches the track is used, and the value chosen is constructed from \fISUBST\fR according to the substitution rules below. @@ -434,8 +461,9 @@ not (currently) the results of \fBnamepart\fR, so generating words via this opti 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. The defaults are equivalent to: +supplied automatically. +But if you supply even one then you must supply all of them. +The defaults are equivalent to: .PP .nf namepart title "/([0-9]+ *[-:] *)?([^/]+)\\.[a-zA-Z0-9]+$" $2 display @@ -446,35 +474,44 @@ namepart ext "(\\.[a-zA-Z0-9]+)$" $1 * .fi .TP .B new_max \fIMAX\fR -The maximum number of tracks to list when reporting newly noticed tracks. The -default is 100. +The maximum number of tracks to list when reporting newly noticed tracks. +The default is 100. .TP .B nice_rescan \fIPRIORITY\fR -Set the recan subprocess priority. The default is 10. +Set the recan subprocess priority. +The default is 10. .IP (Note that higher values mean the process gets less CPU time; UNIX priority values are backwards.) .TP .B nice_server \fIPRIORITY\fR -Set the server priority. This is applied to the server at startup time (and -not when you reload configuration). The server does not use much CPU itself -but this value is inherited by programs it executes. If you have limited CPU -then it might help to set this to a small negative value. The default is 0. +Set the server priority. +This is applied to the server at startup time (and not when you reload +configuration). +The server does not use much CPU itself but this value is inherited +by programs it executes. +If you have limited CPU then it might help to set this to a small +negative value. +The default is 0. .TP .B nice_speaker \fIPRIORITY\fR -Set the speaker process priority. This is applied to the speaker process at -startup time (and not when you reload the configuration). The speaker process -is not massively CPU intensive by today's standards but depends on reasonably -timely scheduling. If you have limited CPU then it might help to set this to a -small negative value. The default is 0. +Set the speaker process priority. +This is applied to the speaker process at startup time (and not when +you reload the configuration). +The speaker process is not massively CPU intensive by today's +standards but depends on reasonably timely scheduling. +If you have limited CPU then it might help to set this to a small +negative value. +The default is 0. .TP .B noticed_history The maximum days that a track can survive in the database of newly added -tracks. The default is 31. +tracks. +The default is 31. .TP .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. +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 @@ -484,8 +521,8 @@ Waits (for up to a couple of seconds) for the default, or specified, libao device to become openable. .TP .B -- -Defines the end of the list of options. Needed if the first argument to the -plugin starts with a "-". +Defines the end of the list of options. +Needed if the first argument to the plugin starts with a "-". .RE .IP The following are the standard modules: @@ -501,16 +538,17 @@ The command is expected to know how to open its own sound device. Identical to the \fBexec\fR except that the player is expected to use the DisOrder raw player protocol. .BR disorder-decode (8) -can decode several common audio file formats to this format. If your favourite -format is not supported, but you have a player which uses libao, there is also -a libao driver which supports this format; see below for more information about -this. +can decode several common audio file formats to this format. +If your favourite format is not supported, but you have a player +which uses libao, there is also a libao driver which supports this format; +see below for more information about this. .TP .B shell \fR[\fISHELL\fR] \fICOMMAND\fR -The command is executed using the shell. If \fISHELL\fR is specified then that -is used, otherwise \fBsh\fR will be used. In either case the \fBPATH\fR -environment variable is searched for the shell executable if it is not an -absolute path. The track name is stored in the environment variable +The command is executed using the shell. +If \fISHELL\fR is specified then that is used, otherwise \fBsh\fR will be used. +In either case the \fBPATH\fR environment variable is searched for the shell +executable if it is not an absolute path. +The track name is stored in the environment variable \fBTRACK\fR. .IP Be careful of the interaction between the configuration file quoting rules and @@ -530,26 +568,29 @@ If 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 -to 3600, i.e. one hour. +The interval at which the preferences log file will be synchronised. +Defaults 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. The default is 10. +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. +The default is 10. .TP .B reminder_interval \fISECONDS\fR -The minimum number of seconds that must elapse between password reminders. The -default is 600, i.e. 10 minutes. +The minimum number of seconds that must elapse between password reminders. +The default is 600, i.e. 10 minutes. .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: +Describes the sample format expected by the \fBspeaker_command\fR (below). +The components of the format specification are as follows: .RS .TP 10 .I BITS -The number of bits per sample. Optionally, may be suffixed by \fBb\fR or -\fBl\fR for big-endian and little-endian words. If neither is used the native -byte order is assumed. +The number of bits per sample. +Optionally, may be suffixed by \fBb\fR or \fBl\fR for big-endian and +little-endian words. +If neither is used the native byte order is assumed. .TP .I RATE The number of samples per second. @@ -573,15 +614,17 @@ in both cases regardless of what is specified in the configuration file. .TP .B signal \fINAME\fR Defines the signal to be sent to track player process groups when tracks are -scratched. The default is \fBSIGKILL\fR. +scratched. +The default is \fBSIGKILL\fR. .IP 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 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 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_backend \fINAME @@ -589,20 +632,21 @@ This is an alias for \fBapi\fR; see above. .TP .B speaker_command \fICOMMAND Causes the speaker subprocess to pipe audio data into shell command -\fICOMMAND\fR, rather than writing to a local sound card. The sample format is -determine by +\fICOMMAND\fR, rather than writing to a local sound card. +The sample format is determine by .B sample_format above. .IP Note that if the sample format is wrong then .BR sox (1) -is invoked to translate it. If +is invoked to translate it. +If .B sox is not installed then this will not work. .TP .B scratch \fIPATH\fR -Specifies a scratch. When a track is scratched, a scratch track is -played at random. +Specifies a scratch. +When a track is scratched, a scratch track is played at random. 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 @@ -623,14 +667,15 @@ 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. +\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). +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 @@ -640,22 +685,26 @@ Connect to the address specified by \fIHOST\fR and port specified by .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. +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. +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. +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. +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 +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. @@ -668,20 +717,21 @@ Determines how names are sorted and displayed in track choice displays. \fITYPE\fR is the type of transformation; usually \fBtrack\fR or \fBdir\fR but you can define your own. .IP -\fICONTEXT\fR is a glob pattern matching the context. Standard contexts are -\fBsort\fR (which determines how directory names are sorted) and \fBdisplay\fR -(which determines how they are displayed). Again, you can define your -own. +\fICONTEXT\fR is a glob pattern matching the context. +Standard contexts are \fBsort\fR (which determines how directory names +are sorted) and \fBdisplay\fR (which determines how they are displayed). +Again, you can define your own. .IP -All the \fBtransform\fR directives are considered in order. If -the \fITYPE\fR, \fIREGEXP\fR and the \fICONTEXT\fR match +All the \fBtransform\fR directives are considered in order. +If the \fITYPE\fR, \fIREGEXP\fR and the \fICONTEXT\fR match then a new track name is constructed from -\fISUBST\fR according to the substitution rules below. If several -match then each is executed in order. +\fISUBST\fR according to the substitution rules below. +If several 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. The defaults are: +supplied automatically. +But if you supply even one then you must supply all of them. +The defaults are: .PP .nf transform track "^.*/([0-9]+ *[-:] *)?([^/]+)\\.[a-zA-Z0-9]+$" $2 display @@ -692,8 +742,9 @@ 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. The default is inferred at runtime, so this option no +Specifies the URL of the web interface. +This URL will be used in 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 @@ -706,8 +757,8 @@ These options would normally be used in \fI~\fRUSER\fI/.disorder/passwd\fR or Specify password. .TP .B username \fIUSERNAME\fR -Specify username. The default is taken from the environment variable -\fBLOGNAME\fR. +Specify username. +The default is taken from the environment variable \fBLOGNAME\fR. .SH "GLOBAL PREFERENCES" These are the values set with \fBset-global\fR. .TP @@ -720,19 +771,22 @@ 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. +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. +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: +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 +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" @@ -743,18 +797,20 @@ driver and pass options to it. The known driver options are: .TP .B fd -The file descriptor to write to. If this is not specified then the driver -looks like the environment variable \fBDISORDER_RAW_FD\fR. If that is not set -then the default is 1 (i.e. standard output). +The file descriptor to write to. +If this is not specified then the driver looks like the environment +variable \fBDISORDER_RAW_FD\fR. +If that is not set then the default is 1 (i.e. standard output). .TP .B fragile If this is set to a nonzero value then the driver will call \fB_exit\fR(2) if a -write to the output file descriptor fails. This is a workaround for buggy -players such as \fBogg123\fR that ignore write errors. +write to the output file descriptor fails. +This is a workaround for buggy players such as \fBogg123\fR that ignore +write errors. .SH "WEB TEMPLATES" When \fBdisorder.cgi\fR wants to generate a page for an action it searches the -directories specified with \fBtemplates\fR for a matching file. It is -suggested that you leave the distributed templates unchanged and put +directories specified with \fBtemplates\fR for a matching file. +It is suggested that you leave the distributed templates unchanged and put any customisations in an earlier entry in the template path. .PP The supplied templates are: @@ -763,8 +819,8 @@ The supplied templates are: Display information about DisOrder. .TP .B choose.html -Navigates through the track database to choose a track to play. The -\fBdir\fR argument gives the directory to look in; if it is missing +Navigates through the track database to choose a track to play. +The \fBdir\fR argument gives the directory to look in; if it is missing then the root directory is used. .TP .B choosealpha.html @@ -780,13 +836,14 @@ the queue. Gets an HTTP \fBRefresh\fR header. .IP If the \fBmgmt\fR CGI argument is set to \fBtrue\fR then we include extra -buttons for moving tracks up and down in the queue. There is some logic in -\fBdisorder.cgi\fR to ensure that \fBmgmt=true\fR is preserved across refreshes -and redirects back into itself, but URLs embedded in web pages must include it -explicitly. +buttons for moving tracks up and down in the queue. +There is some logic in \fBdisorder.cgi\fR to ensure that \fBmgmt=true\fR +is preserved across refreshes and redirects back into itself, but +URLs embedded in web pages must include it explicitly. .TP .B prefs.html -Views preferences. If the \fBfile\fR, \fBname\fR and \fBvalue\fR arguments are +Views preferences. +If the \fBfile\fR, \fBname\fR and \fBvalue\fR arguments are all set then that preference is modified; if \fBfile\fR and \fBname\fR are set but not \fBvalue\fR then the preference is deleted. .TP @@ -814,30 +871,33 @@ Included at the end of the \fB\fR element. Included in the \fB\fR element. .TP .B stylesheet.html -Contains the default DisOrder stylesheet. You can override this by editing the -CSS or by replacing it all with a \fB\fR to an external stylesheet. +Contains the default DisOrder stylesheet. +You can override this by editing the CSS or by replacing it all with +a \fB\fR to an external stylesheet. .PP Templates are ASCII files containing HTML documents, with an expansion syntax to enable data supplied by the implementation to be inserted. .PP If you want to use characters outside the ASCII range, use either the appropriate HTML entity, e.g. \fBé\fR, or an SGML numeric -character reference, e.g. \fBý\fR. Use \fB@\fR to insert a -literal \fB@\fR without falling foul of the expansion syntax. +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" 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 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. +followed by zero or more arguments. +Arguments may either 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 Leading and trailing whitespace in unquoted arguments is ignored, as is whitespace (including newlines) following a close bracket ("}"). .PP Arguments are recursively expanded before being interpreted, except for -\fITEMPLATE\fR arguments. These are expanded (possibly more than once) to -produce the final expansion. +\fITEMPLATE\fR arguments. +These are expanded (possibly more than once) to produce the final expansion. (More than once means the same argument being expanded more than once for different tracks or whatever, not the result of the first expansion itself being re-expanded.) @@ -861,7 +921,8 @@ The following expansion keywords are defined: Ignored. .TP .B @action@ -The current action. This reports +The current action. +This reports .B manage if the action is really .B playing @@ -927,16 +988,16 @@ Expands to the (possibly relative) URL for image \fINAME\fR. .IP If there is a label \fBimages.\fINAME\fR then that will be the image base name. Otherwise the image base name is \fINAME\fB.png\fR or just \fINAME\fR if it -alraedy has an extension. Thus labels may be defined to give images role -names. +alraedy has an extension. +Thus labels may be defined to give images role names. .IP -If there is a label \fBurl.static\fR then that is the base URL for images. If -it is not defined then \fB/disorder\fR is used as a default. +If there is a label \fBurl.static\fR then that is the base URL for images. +If it is not defined then \fB/disorder\fR is used as a default. .TP .B @include:\fIPATH\fB@ -Include the named file as if it were a template file. If \fIPATH\fR -starts with a \fB/\fR then it is used as-is; otherwise, ".html" is -appended and the template path is searched. +Include the named file as if it were a template file. +If \fIPATH\fR starts with a \fB/\fR then it is used as-is; +otherwise, ".html" is appended and the template path is searched. .TP .B @index@ Expands to the index of the current file in \fB@queue@\fR, \fB@recent@\fR or @@ -974,8 +1035,9 @@ Expands to \fBtrue\fR if the recently played list has any tracks in it, otherwise to \fBfalse\fR. .TP .B @label:\fINAME\fR\fB@ -Expands to the value of label \fINAME\fR. See the shipped \fIoptions.labels\fR -file for full documentation of the labels used by the standard templates. +Expands to the value of label \fINAME\fR. +See the shipped \fIoptions.labels\fR file for full documentation of the +labels used by the standard templates. .TP .B @length@ Expands to the length of the current track. @@ -995,7 +1057,8 @@ Expands to \fBtrue\fR if \fIA\fR and \fIB\fR differ, otherwise to \fBfalse\fR. .TP .B @new{\fITEMPLATE\fB} Expands \fITEMPLATE\fR for each track in the newly added tracks list, starting -with the most recent. Used in \fBnew.html\fR. +with the most recent. +Used in \fBnew.html\fR. .TP .B @nfiles@ Expands to the number of files from \fB@files\fR (above). @@ -1018,15 +1081,16 @@ 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 defaults -to \fBdisplay\fR. +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. +\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. @@ -1055,7 +1119,8 @@ argument of \fB@prefs@\fR. .TP .B @queue{\fITEMPLATE\fB}@ 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. +the current track. +The track at the head of the queue comes first. .TP .B @random-enabled@ Expands to \fBtrue\fR if random play is currently enabled, otherwise to @@ -1063,7 +1128,8 @@ Expands to \fBtrue\fR if random play is currently enabled, otherwise to .TP .B @recent{\fITEMPLATE\fB}@ Expands \fITEMPLATE\fR repeatedly using the each recently played track in turn -as the current track. The most recently played track comes first. +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 @@ -1095,22 +1161,26 @@ and within the template will apply to one of the tracks in the group. .IP If \fICONTEXT\fR is specified it should be either \fBsort\fR or \fBdisplay\fR, -and determines the context for \fIPART\fR. The default is \fBsort\fR. Usually -you want \fBdisplay\fR for everything except the title and \fBsort\fR for the -title. If you use \fBsort\fR for artist and album then you are likely to get +and determines the context for \fIPART\fR. +The default is \fBsort\fR. +Usually you want \fBdisplay\fR for everything except the title and +\fBsort\fR for the title. +If you use \fBsort\fR for artist and album then you are likely to get strange effects. .TP .B @server-version@ Expands to the server's version string. .TP .B @shell{\fICOMMAND\fB}@ -Expands to the output of \fICOMMAND\fR executed via the shell. \fBsh\fR is -searched for using \fBPATH\fR. If the command fails then this is logged but -otherwise ignored. +Expands to the output of \fICOMMAND\fR executed via the shell. +\fBsh\fR is searched for using \fBPATH\fR. +If the command fails then this is logged but otherwise ignored. .TP .B @state@ In \fB@queue@\fR and \fB@recent@\fR, expands to the state of the current -track. Otherwise the empty string. Known states are: +track. +Otherwise the empty string. +Known states are: .RS .TP 12 .B failed @@ -1154,9 +1224,11 @@ This track is currently playing. Expands to the server statistics. .TP .B @thisurl@ -Expands to the URL of the current page. Typically used in +Expands to the URL of the current page. +Typically used in .B back -arguments. If there is a +arguments. +If there is a .B nonce argument then it is changed to a fresh value. .TP @@ -1181,7 +1253,8 @@ Expands to the canonical URL as defined in \fIpkgconfdir/config\fR. URL-quote \fISTRING\fR. .TP .B @user@ -The current username. This will be "guest" if nobody is logged in. +The current username. +This will be "guest" if nobody is logged in. .TP .B @userinfo{\fIPROPERTY\fB}@ Look up a property of the logged-in user. @@ -1190,8 +1263,8 @@ Look up a property of the logged-in user. 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\fR or -\fBright\fR. +The volume on the left or right speaker. +\fISPEAKER\fR must be \fBleft\fR or \fBright\fR. .TP .B @when@ When the current track was played (or when it is expected to be played, if it @@ -1201,8 +1274,9 @@ has not been played yet) Who submitted the current track. .SH "WEB OPTIONS" This is a file called \fIoptions\fR, searched for in the same manner -as templates. It includes numerous options for the control of the web -interface. The general syntax is the same as the main configuration +as templates. +It includes numerous options for the control of the web interface. +The general syntax is the same as the main configuration file, except that it should be encoded using UTF-8 (though this might change to the current locale's character encoding; stick to ASCII to be safe). @@ -1211,49 +1285,52 @@ The shipped \fIoptions\fR file includes four standard options files. In order, they are: .TP .I options.labels -The default labels file. You wouldn't normally edit this directly - instead -supply your own commands in \fIoptions.user\fR. Have a look at the shipped -version of the file for documentation of labels used by the standard templates. +The default labels file. +You wouldn't normally edit this directly - instead supply your own commands +in \fIoptions.user\fR. +Have a look at the shipped version of the file for documentation of +labels used by the standard templates. .TP .I options.user -A user options file. Here you should put any overrides for the default -labels and any extra labels required by your modified templates. +A user options file. +Here you should put any overrides for the default labels and any +extra labels required by your modified templates. .PP Valid directives are: .TP .B columns \fINAME\fR \fIHEADING\fR... -Defines the columns used in \fB@playing@\fR and \fB@recent@\fB. \fINAME\fR -must be either \fBplaying\fR, \fBrecent\fR or \fBsearch\fR. -\fIHEADING\fR... is a list of -heading names. If a column is defined more than once then the last definitions -is used. +Defines the columns used in \fB@playing@\fR and \fB@recent@\fB. +\fINAME\fR must be either \fBplaying\fR, \fBrecent\fR or \fBsearch\fR. +\fIHEADING\fR... is a list of heading names. +If a column is defined more than once then the last definitions is used. .IP The heading names \fBbutton\fR, \fBlength\fR, \fBwhen\fR and \fBwho\fR are built in. .TP .B include \fIPATH\fR -Includes another file. If \fIPATH\fR starts with a \fB/\fR then it is -taken as is, otherwise it is searched for in the template path. +Includes another file. +If \fIPATH\fR starts with a \fB/\fR then it is taken as is, otherwise +it is searched for in the template path. .TP .B label \fINAME\fR \fIVALUE\fR -Define a label. If a label is defined more than once then the last definition -is used. +Define a label. +If a label is defined more than once then the last definition is used. .SS Labels Some labels are defined inside \fBdisorder.cgi\fR and others by the -default templates. You can define your own labels and use them inside -a template. +default templates. +You can define your own labels and use them inside a template. .PP When an undefined label is expanded, if it has a dot in its name then -the part after the final dot is used as its value. Otherwise the -whole name is used as the value. +the part after the final dot is used as its value. +Otherwise the whole name is used as the value. .PP Labels are no longer documented here, see the shipped \fIoptions.labels\fR file instead. .SH "REGEXP SUBSTITUTION RULES" -Regexps are PCRE regexps, as defined in \fBpcrepattern\fR(3). The -only option used is \fBPCRE_UTF8\fR. Remember that the configuration -file syntax means you have to escape backslashes and quotes inside -quoted strings. +Regexps are PCRE regexps, as defined in \fBpcrepattern\fR(3). +The only option used is \fBPCRE_UTF8\fR. +Remember that the configuration file syntax means you have to +escape backslashes and quotes inside quoted strings. .PP In a \fISUBST\fR string the following sequences are interpreted specially: @@ -1271,12 +1348,13 @@ All other pairs starting with \fB$\fR are undefined (and might be used for something else in the future, so don't rely on the current behaviour.) .PP -If \fBi\fR is present in \fIREFLAGS\fR then the match is case-independent. If -\fBg\fR is present then all matches are replaced, otherwise only the first +If \fBi\fR is present in \fIREFLAGS\fR then the match is case-independent. +If \fBg\fR is present then all matches are replaced, otherwise only the first match is replaced. .SH "ACTIONS" What the web interface actually does is terminated by the \fBaction\fR CGI -argument. The values listed below are supported. +argument. +The values listed below are supported. .PP Except as specified, all actions redirect back to the \fBplaying.html\fR template unless the \fBback\fR argument is present, in which case the URL it @@ -1293,8 +1371,8 @@ Play track \fBfile\fR, or if that is missing then play all the tracks in .TP .B "playing" Don't change any state, but instead compute a suitable refresh time and include -that in an HTTP header. Expands the \fBplaying.html\fR template rather than -redirecting. +that in an HTTP header. +Expands the \fBplaying.html\fR template rather than redirecting. .IP This is the default if \fBaction\fR is missing. .TP @@ -1320,13 +1398,13 @@ Remove track \fBid\fR. Resumes play after a pause. .TP .B "scratch" -Scratch the playing track. If \fBid\fR is present it must match the playing -track. +Scratch the playing track. +If \fBid\fR is present it must match the playing track. .TP .B "volume" Change the volume by \fBdelta\fR, or if that is missing then set it to the -values of \fBleft\fR and \fBright\fR. Expands to the \fBvolume.html\fR template -rather than redirecting. +values of \fBleft\fR and \fBright\fR. +Expands to the \fBvolume.html\fR template rather than redirecting. .TP .B "prefs" Adjust preferences from the \fBprefs.html\fR template (which it then expands @@ -1334,13 +1412,16 @@ rather than redirecting). .IP If .B parts -is set then the cooked interface is assumed. The value of +is set then the cooked interface is assumed. +The value of .B parts -is used to determine which trackname preferences are set. By default the +is used to determine which trackname preferences are set. +By default the .B display context is adjusted but this can be overridden with the .B context -argument. Also the +argument. +Also the .B random argument is checked; if it is set then random play is enabled for that track, otherwise it is disabled. @@ -1356,17 +1437,18 @@ Otherwise if just the argument is set then that preference is deleted. .IP It is recommended that links to the \fBprefs\fR action use \fB@resolve@\fR to -enure that the real track name is always used. Otherwise if the preferences -page is used to adjust a trackname_ preference, the alias may change, leading -to the URL going stale. +enure that the real track name is always used. +Otherwise if the preferences page is used to adjust a trackname_ preference, +the alias may change, leading to the URL going stale. .TP .B "error" This action is generated automatically when an error occurs connecting to the -server. The \fBerror\fR label is set to an indication of what the error is. +server. +The \fBerror\fR label is set to an indication of what the error is. .SH "TRACK NAME PARTS" The traditional track name parts are \fBartist\fR, \fBalbum\fR and \fBtitle\fR, -with the obvious intended meaning. These are controlled by configuration and -by \fBtrackname_\fR preferences. +with the obvious intended meaning. +These are controlled by configuration and by \fBtrackname_\fR preferences. .PP 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 diff --git a/doc/disorder_protocol.5.in b/doc/disorder_protocol.5.in index 56fd094..aa6b65e 100644 --- a/doc/disorder_protocol.5.in +++ b/doc/disorder_protocol.5.in @@ -23,10 +23,11 @@ disorder_protocol \- DisOrder communication protocol The DisOrder client and server communicate via the protocol described in this man page. .PP -The protocol is liable to change without notice. You are recommended to check -the implementation before believing this document. +The protocol is liable to change without notice. +You are recommended to check the implementation before believing this document. .SH "GENERAL SYNTAX" -Everything is encoded using UTF-8. See +Everything is encoded using UTF-8. +See .B "CHARACTER ENCODING" below for more detail on character encoding issues. .PP @@ -41,19 +42,21 @@ lines, with any initial full stop doubled up, and are terminated by a line consisting of a full stop and a line feed. .SH COMMANDS Commands always have a command name as the first field of the line; responses -always have a 3-digit response code as the first field. See below for more -details about this field. +always have a 3-digit response code as the first field. +See below for more details about this field. .PP All commands require the connection to have been already authenticated unless -stated otherwise. If not stated otherwise, the \fBread\fR right is sufficient -to execute the command. +stated otherwise. +If not stated otherwise, the \fBread\fR right is sufficient to execute +the command. .PP Neither commands nor responses have a body unless stated otherwise. .TP .B adduser \fIUSERNAME PASSWORD \fR[\fIRIGHTS\fR] -Create a new user with the given username and password. The new user's rights -list can be specified; if it is not then the \fBdefault_rights\fR setting -applies instead. Requires the \fBadmin\fR right, and only works on local +Create a new user with the given username and password. +The new user's rights list can be specified; if it is not +then the \fBdefault_rights\fR setting applies instead. +Requires the \fBadmin\fR right, and only works on local connections. .TP .B allfiles \fIDIRECTORY\fR [\fIREGEXP\fR] @@ -61,49 +64,53 @@ List all the files and directories in \fIDIRECTORY\fR in a response body. If \fIREGEXP\fR is present only matching files and directories are returned. .TP .B confirm \fICONFIRMATION -Confirm user registration. \fICONFIRMATION\fR is as returned from -\fBregister\fR below. This command can be used without logging in. +Confirm user registration. +\fICONFIRMATION\fR is as returned from \fBregister\fR below. +This command can be used without logging in. .TP .B cookie \fICOOKIE -Log a user back in using a cookie created with \fBmake-cookie\fR. The response -contains the username. +Log a user back in using a cookie created with \fBmake-cookie\fR. +The response contains the username. .TP .B deluser \fIUSERNAME -Delete the named user. Requires the \fBadmin\fR right, and only works on -local connections. +Delete the named user. +Requires the \fBadmin\fR right, and only works on local connections. .TP .B dirs \fIDIRECTORY\fR [\fIREGEXP\fR] List all the directories in \fIDIRECTORY\fR in a response body. If \fIREGEXP\fR is present only matching directories are returned. .TP .B disable \fR[\fBnow\fR] -Disable further playing. If the optional \fBnow\fR argument is present then -the current track is stopped. Requires the \fBglobal prefs\fR right. +Disable further playing. +If the optional \fBnow\fR argument is present then the current track +is stopped. +Requires the \fBglobal prefs\fR right. .TP .B edituser \fIUSERNAME PROPERTY VALUE -Set a user property. With the \fBadmin\fR right any username and property may -be specified. Otherwise the \fBuserinfo\fR right is required and only the +Set a user property. +With the \fBadmin\fR right any username and property may be specified. +Otherwise the \fBuserinfo\fR right is required and only the \fBemail\fR and \fBpassword\fR properties may be set. .TP .B enable -Re-enable further playing, and is the opposite of \fBdisable\fR. Requires the -\fBglobal prefs\fR right. +Re-enable further playing, and is the opposite of \fBdisable\fR. +Requires the \fBglobal prefs\fR right. .TP .B enabled -Report whether playing is enabled. The second field of the response line will -be \fByes\fR or \fBno\fR. +Report whether playing is enabled. +The second field of the response line will be \fByes\fR or \fBno\fR. .TP .B exists \fITRACK\fR -Report whether the named track exists. The second field of the response line -will be \fByes\fR or \fBno\fR. +Report whether the named track exists. +The second field of the response line will be \fByes\fR or \fBno\fR. .TP .B files \fIDIRECTORY\fR [\fIREGEXP\fR] List all the files in \fIDIRECTORY\fR in a response body. If \fIREGEXP\fR is present only matching files are returned. .TP .B get \fITRACK\fR \fIPREF\fR -Getsa preference value. On success the second field of the response line will -have the value. +Getsa preference value. +On success the second field of the response line will have the value. .IP If the track or preference do not exist then the response code is 555. .TP @@ -113,13 +120,14 @@ Get a global preference. If the preference does not exist then the response code is 555. .TP .B length \fITRACK\fR -Get the length of the track in seconds. On success the second field of the -response line will have the value. +Get the length of the track in seconds. +On success the second field of the response line will have the value. .TP .B log -Send event log messages in a response body. The command will never terminate. -Any further data sent to the server will be discarded (explicitly; i.e. it will -not accumulate in a buffer somewhere). +Send event log messages in a response body. +The command will never terminate. +Any further data sent to the server will be discarded (explicitly; +i.e. it will not accumulate in a buffer somewhere). .IP See \fBEVENT LOG\fR below for more details. .TP @@ -128,18 +136,20 @@ Returns an opaque string that can be used by the \fBcookie\fR command to log this user back in on another connection (until the cookie expires). .TP .B move \fITRACK\fR \fIDELTA\fR -Move a track in the queue. The track may be identified by ID (preferred) or -name (which might cause confusion if it's there twice). \fIDELTA\fR should be -an negative or positive integer and indicates how many steps towards the head -of the queue the track should be moved. +Move a track in the queue. +The track may be identified by ID (preferred) or name (which might cause +confusion if it's there twice). +\fIDELTA\fR should be an negative or positive integer and indicates how +many steps towards the head of the queue the track should be moved. .IP Requires one of the \fBmove mine\fR, \fBmove random\fR or \fBmove any\fR rights depending on how the track came to be added to the queue. .TP .B moveafter \fITARGET\fR \fIID\fR ... -Move all the tracks in the \fIID\fR list after ID \fITARGET\fR. If -\fITARGET\fR is the empty string then the listed tracks are put at the head of -the queue. If \fITARGET\fR is listed in the ID list then the tracks are moved +Move all the tracks in the \fIID\fR list after ID \fITARGET\fR. +If \fITARGET\fR is the empty string then the listed tracks are put +at the head of the queue. +If \fITARGET\fR is listed in the ID list then the tracks are moved to just after the first non-listed track before it, or to the head if there is no such track. .IP @@ -147,18 +157,20 @@ Requires one of the \fBmove mine\fR, \fBmove random\fR or \fBmove any\fR rights depending on how the tracks came to be added to the queue. .TP .B new \fR[\fIMAX\fR] -Send the most recently added \fIMAX\fR tracks in a response body. If the -argument is ommitted, the \fBnew_max\fR most recent tracks are listed (see -\fBdisorder_config\fR(5)). +Send the most recently added \fIMAX\fR tracks in a response body. +If the argument is ommitted, the \fBnew_max\fR most recent tracks are +listed (see \fBdisorder_config\fR(5)). .TP .B nop -Do nothing. Used by +Do nothing. +Used by .BR disobedience (1) -as a keepalive measure. This command does not require authentication. +as a keepalive measure. +This command does not require authentication. .TP .B part \fITRACK\fR \fICONTEXT\fI \fIPART\fR -Get a track name part. Returns an empty string if a name part cannot be -constructed. +Get a track name part. +Returns an empty string if a name part cannot be constructed. .IP .I CONTEXT is one of @@ -174,10 +186,12 @@ or .BR title . .TP .B pause -Pause the current track. Requires the \fBpause\fR right. +Pause the current track. +Requires the \fBpause\fR right. .TP .B play \fITRACK\fR -Add a track to the queue. The response contains the queue ID of the track. +Add a track to the queue. +The response contains the queue ID of the track. Requires the \fBplay\fR right. .TP .B playing @@ -195,74 +209,82 @@ name of the pref and the second the value. .TP .B queue Send back the current queue in a response body, one track to a line, the track -at the head of the queue (i.e. next to be be played) first. See below for the -track information syntax. +at the head of the queue (i.e. next to be be played) first. +See below for the track information syntax. .TP .B random-disable -Disable random play (but don't stop the current track). Requires the \fBglobal -prefs\fR right. +Disable random play (but don't stop the current track). +Requires the \fBglobal prefs\fR right. .TP .B random-enable -Enable random play. Requires the \fBglobal prefs\fR right. +Enable random play. +Requires the \fBglobal prefs\fR right. .TP .B random-enabled -Report whether random play is enabled. The second field of the response line -will be \fByes\fR or \fBno\fR. +Report whether random play is enabled. +The second field of the response line will be \fByes\fR or \fBno\fR. .TP .B recent Send back the current recently-played list in a response body, one track to a -line, the track most recently played last. See below for the track -information syntax. +line, the track most recently played last. +See below for the track information syntax. .TP .B reconfigure -Request that DisOrder reconfigure itself. Requires the \fBadmin\fR right. -command. +Request that DisOrder reconfigure itself. +Requires the \fBadmin\fR right. .TP .B register \fIUSER PASSWORD EMAIL -Register a new user. Requires the \fBregister\fR right. The result contains a -confirmation string; the user will be be able to log in until this has been -presented back to the server via the \fBconfirm\fR command. +Register a new user. +Requires the \fBregister\fR right. +The result contains a confirmation string; the user will be be able +to log in until this has been presented back to the server via the +\fBconfirm\fR command. .TP .B reminder \fIUSER\fR -Send a password reminder to \fIUSER\fR. If the user has no valid email -address, or no password, or a reminder has been sent too recently, then no -reminder will be sent. +Send a password reminder to \fIUSER\fR. +If the user has no valid email address, or no password, or a +reminder has been sent too recently, then no reminder will be sent. .TP .B remove \fIID\fR -Remove the track identified by \fIID\fR. Requires one of the \fBremove -mine\fR, \fBremove random\fR or \fBremove any\fR rights depending on how the +Remove the track identified by \fIID\fR. +Requires one of the \fBremove mine\fR, \fBremove random\fR or +\fBremove any\fR rights depending on how the track came to be added to the queue. .TP .B rescan -Rescan all roots for new or obsolete tracks. Requires the \fBrescan\fR right. +Rescan all roots for new or obsolete tracks. +Requires the \fBrescan\fR right. .TP .B resolve \fITRACK\fR Resolve a track name, i.e. if this is an alias then return the real track name. .TP .B resume -Resume the current track after a \fBpause\fR command. Requires the \fBpause\fR -right. +Resume the current track after a \fBpause\fR command. +Requires the \fBpause\fR right. .TP .B revoke \fBcookie\fR -Revoke a cookie previously created with \fBmake-cookie\fR. It will not be -possible to use this cookie in the future. +Revoke a cookie previously created with \fBmake-cookie\fR. +It will not be possible to use this cookie in the future. .TP .B rtp-address Report the RTP broadcast (or multicast) address, in the form \fIADDRESS -PORT\fR. This command does not require authentication. +PORT\fR. +This command does not require authentication. .TP .B scratch \fR[\fIID\fR] Remove the track identified by \fIID\fR, or the currently playing track if no -\fIID\fR is specified. Requires one of the \fBscratch mine\fR, \fBscratch -random\fR or \fBscratch any\fR rights depending on how the track came to be +\fIID\fR is specified. +Requires one of the \fBscratch mine\fR, \fBscratch random\fR or +\fBscratch any\fR rights depending on how the track came to be added to the queue. .TP .B search \fITERMS\fR -Search for tracks matching the search terms. The results are put in a response -body, one to a line. +Search for tracks matching the search terms. +The results are put in a response body, one to a line. .IP The search string is split in the usual way, with quoting supported, into a -list of terms. Only tracks matching all terms are included in the results. +list of terms. +Only tracks matching all terms are included in the results. .IP Any terms of the form \fBtag:\fITAG\fR limits the search to tracks with that tag. @@ -274,10 +296,12 @@ Spaces in terms don't currently make sense, but may one day be interpreted to allow searching for phrases. .TP .B \fBset\fR \fITRACK\fR \fIPREF\fR \fIVALUE\fR -Set a preference. Requires the \fBprefs\fR right. +Set a preference. +Requires the \fBprefs\fR right. .TP .B set-global \fIKEY\fR \fIVALUE\fR -Set a global preference. Requires the \fBglobal prefs\fR right. +Set a global preference. +Requires the \fBglobal prefs\fR right. .TP .B stats Send server statistics in plain text in a response body. @@ -286,13 +310,16 @@ Send server statistics in plain text in a response body. Send the list of currently known tags in a response body. .TP .B \fBunset\fR \fITRACK\fR \fIPREF\fR -Unset a preference. Requires the \fBprefs\fR right. +Unset a preference. +Requires the \fBprefs\fR right. .TP .B \fBunset-global\fR \fIKEY\fR -Unset a global preference. Requires the \fBglobal prefs\fR right. +Unset a global preference. +Requires the \fBglobal prefs\fR right. .TP .B user \fIUSER\fR \fIRESPONSE\fR -Authenticate as \fIUSER\fR. See +Authenticate as \fIUSER\fR. +See .B AUTHENTICATION below. .TP @@ -308,11 +335,12 @@ Get or set the volume. With zero parameters just gets the volume and reports the left and right sides as the 2nd and 3rd fields of the response. .IP -With one parameter sets both sides to the same value. With two parameters sets -each side independently. Setting the volume requires the \fBvolume\fR right. +With one parameter sets both sides to the same value. +With two parameters sets each side independently. +Setting the volume requires the \fBvolume\fR right. .SH RESPONSES -Responses are three-digit codes. The first digit distinguishes errors from -succesful responses: +Responses are three-digit codes. +The first digit distinguishes errors from succesful responses: .TP .B 2 Operation succeeded. @@ -323,8 +351,8 @@ Operation failed. The second digit breaks down the origin of the response: .TP .B 0 -Generic responses not specific to the handling of the command. Mostly this is -parse errors. +Generic responses not specific to the handling of the command. +Mostly this is parse errors. .TP .B 1 51x errors indicate that the user had insufficient rights for the command. @@ -350,12 +378,12 @@ Text part is a potentially variable result. Text part is just commentary; a dot-stuffed body follows. .TP .B 4 -Text part is just commentary; an indefinite dot-stuffed body follows. (Used -for \fBlog\fR.) +Text part is just commentary; an indefinite dot-stuffed body follows. +(Used for \fBlog\fR.) .TP .B 5 -Used with "normal" errors, for instance a preference not being found. The text -part is commentary. +Used with "normal" errors, for instance a preference not being found. +The text part is commentary. .TP .B 9 The text part is just commentary (but would normally be a response for this @@ -365,20 +393,23 @@ Result strings (not bodies) intended for machine parsing (i.e. xx1 and xx2 responses) are quoted. .SH AUTHENTICATION When a connection is made the server sends a \fB231\fR response before any -command is received. This contains a protocol generation, an algorithm name -and a challenge encoded in hex, all separated by whitespace. +command is received. +This contains a protocol generation, an algorithm name and a +challenge encoded in hex, all separated by whitespace. .PP The current protocol generation is \fB2\fR. .PP The possible algorithms are (currently) \fBsha1\fR, \fBsha256\fR, \fBsha384\fR -and \fBsha512\fR. \fBSHA1\fR etc work as synonyms. +and \fBsha512\fR. +\fBSHA1\fR etc work as synonyms. .PP The \fBuser\fR response consists of the selected hash of the user's password concatenated with the challenge, encoded in hex. .SH "TRACK INFORMATION" Track information is encoded in a line (i.e. using the usual line syntax) as -pairs of fields. The first is a name, the second a value. The names have the -following meanings: +pairs of fields. +The first is a name, the second a value. +The names have the following meanings: .TP 12 .B expected The time the track is expected to be played at. @@ -393,7 +424,8 @@ The time the track was played at. The user that scratched the track. .TP .B state -The current track state. Valid states are: +The current track state. +Valid states are: .RS .TP 12 .B failed @@ -436,8 +468,8 @@ The wait status of the player in decimal. Times are decimal integers using the server's \fBtime_t\fR. .PP For file listings, the regexp applies to the basename of the returned file, not -the whole filename, and letter case is ignored. \fBpcrepattern\fR(3) describes -the regexp syntax. +the whole filename, and letter case is ignored. +\fBpcrepattern\fR(3) describes the regexp syntax. .PP Filenames are in UTF-8 even if the collection they come from uses some other encoding - if you want to access the real file (in such cases as the filenames @@ -445,8 +477,9 @@ actually correspond to a real file) you'll have to convert to whatever the right encoding is. .SH "EVENT LOG" The event log consists of lines starting with a hexadecimal timestamp and a -keyword followed by (optionally) parameters. The parameters are quoted in the -usual DisOrder way. Currently the following keywords are used: +keyword followed by (optionally) parameters. +The parameters are quoted in the usual DisOrder way. +Currently the following keywords are used: .TP .B completed \fITRACK\fR Completed playing \fITRACK\fR @@ -455,8 +488,8 @@ Completed playing \fITRACK\fR Completed playing \fITRACK\fR with an error status .TP .B moved \fIUSER\fR -User \fIUSER\fR moved some track(s). Further details aren't included any -more. +User \fIUSER\fR moved some track(s). +Further details aren't included any more. .TP .B playing \fITRACK\fR [\fIUSER\fR] Started playing \fITRACK\fR. @@ -471,8 +504,9 @@ Added \fIID\fR to the recently played list. Removed \fIID\fR from the recently played list. .TP .B removed \fIID\fR [\fIUSER\fR] -Queue entry \fIID\fR was removed. This is used both for explicit removal (when -\fIUSER\fR is present) and when playing a track (when it is absent). +Queue entry \fIID\fR was removed. +This is used both for explicit removal (when \fIUSER\fR is present) +and when playing a track (when it is absent). .TP .B rescanned A rescan completed. @@ -481,7 +515,8 @@ A rescan completed. \fITRACK\fR was scratched by \fIUSER\fR. .TP .B state \fIKEYWORD\fR -Some state change occurred. The current set of keywords is: +Some state change occurred. +The current set of keywords is: .RS .TP .B completed @@ -526,44 +561,50 @@ is as defined in .B "TRACK INFORMATION" above. .SH "CHARACTER ENCODING" -All data sent by both server and client is encoded using UTF-8. Moreover it -must be valid UTF-8, i.e. non-minimal sequences are not permitted, nor are -surrogates, nor are code points outside the Unicode code space. +All data sent by both server and client is encoded using UTF-8. +Moreover it must be valid UTF-8, i.e. non-minimal sequences are not +permitted, nor are surrogates, nor are code points outside the +Unicode code space. .PP There are no particular normalization requirements on either side of the -protocol. The server currently converts internally to NFC, the client must +protocol. +The server currently converts internally to NFC, the client must normalize the responses returned if it needs some normalized form for further processing. .PP The various characters which divide up lines may not be followed by combining -characters. For instance all of the following are prohibited: +characters. +For instance all of the following are prohibited: .TP .B o -LINE FEED followed by a combining character. For example the sequence -LINE FEED, COMBINING GRAVE ACCENT is never permitted. +LINE FEED followed by a combining character. +For example the sequence LINE FEED, COMBINING GRAVE ACCENT is never permitted. .TP .B o APOSTROPHE or QUOTATION MARK followed by a combining character when used to -delimit fields. For instance a line starting APOSTROPHE, COMBINING CEDILLA -is prohibited. +delimit fields. +For instance a line starting APOSTROPHE, COMBINING CEDILLA is prohibited. .IP Note that such sequences are not prohibited when the quote character cannot be -interpreted as a field delimiter. For instance APOSTROPHE, REVERSE SOLIDUS, -APOSTROPHE, COMBINING CEDILLA, APOSTROPHE would be permitted. +interpreted as a field delimiter. +For instance APOSTROPHE, REVERSE SOLIDUS, APOSTROPHE, COMBINING CEDILLA, +APOSTROPHE would be permitted. .TP .B o REVERSE SOLIDUS (BACKSLASH) followed by a combining character in a quoted -string when it is the first character of an escape sequence. For instance a -line starting APOSTROPHE, REVERSE SOLIDUS, COMBINING TILDE is prohibited. +string when it is the first character of an escape sequence. +For instance a line starting APOSTROPHE, REVERSE SOLIDUS, COMBINING TILDE +is prohibited. .IP As above such sequences are not prohibited when the character is not being used -to start an escape sequence. For instance APOSTROPHE, REVERSE SOLIDUS, -REVERSE SOLIDS, COMBINING TILDER, APOSTROPHE is permitted. +to start an escape sequence. +For instance APOSTROPHE, REVERSE SOLIDUS, REVERSE SOLIDS, COMBINING TILDE, +APOSTROPHE is permitted. .TP .B o Any of the field-splitting whitespace characters followed by a combining -character when not part of a quoted field. For instance a line starting COLON, -SPACE, COMBINING CANDRABINDU is prohibited. +character when not part of a quoted field. +For instance a line starting COLON, SPACE, COMBINING CANDRABINDU is prohibited. .IP As above non-delimiter uses are fine. .TP @@ -572,12 +613,14 @@ The FULL STOP characters used to quote or delimit a body. .PP Furthermore none of these characters are permitted to appear in the context of a canonical decomposition (i.e. they must still be present when converted to -NFC). In practice however this is not an issue in Unicode 5.0. +NFC). +In practice however this is not an issue in Unicode 5.0. .PP These rules are consistent with the observation that the split() function is -essentially a naive ASCII parser. The implication is not that these sequences -never actually appear in the protocol, merely that the server is not required -to honor them in any useful way nor be consistent between versions: in current +essentially a naive ASCII parser. +The implication is not that these sequences never actually appear in +the protocol, merely that the server is not required to honor them in +any useful way nor be consistent between versions: in current versions the result will be lines and fields that start with combining characters and are not necessarily split where you expect, but future versions may remove them, reject them or ignore some or all of the delimiters that have diff --git a/doc/disorderd.8.in b/doc/disorderd.8.in index 7c708c2..01802b3 100644 --- a/doc/disorderd.8.in +++ b/doc/disorderd.8.in @@ -29,7 +29,8 @@ concerning what is to be played. .SH OPTIONS .TP .B --config \fIPATH\fR, \fB-c \fIPATH -Set the configuration file. The default is +Set the configuration file. +The default is .IR pkgconfdir/config . See .BR disorder_config (5) @@ -39,12 +40,14 @@ for further information. Write a pidfile. .TP .B --foreground\fR, \fB-f -Run in the foreground. (By default, +Run in the foreground. +(By default, .B disorderd detaches from its terminal and runs in the background.) .TP .B --syslog\fR, \fB-s -Log to syslog. This is the default if DisOrder runs in the background. +Log to syslog. +This is the default if DisOrder runs in the background. .TP .B --debug\fR, \fB-d Enable debugging. @@ -60,27 +63,32 @@ For configuration file documentation, see .SS "Startup" The first time a new install of DisOrder is started it will run .B disorder-rescan -to pick up new tracks. On subsequent server restarts it will NOT do +to pick up new tracks. +On subsequent server restarts it will NOT do this automatically; if you want a rescan at every restart you must arrange that manually. .PP There is however an automatic rescan once every 24 hours. .PP A \fBroot\fR login is automatically created on startup if it does not -exist. If \fBdisorder\fR(1) is run as root on the same machine as the +exist. +If \fBdisorder\fR(1) is run as root on the same machine as the server it is capable of extracting the password from the database directly. .SS "Locales" .B disorderd -is locale-aware. If you do not set the locale correctly then it may -not handle non-ASCII data properly. +is locale-aware. +If you do not set the locale correctly then it may not handle +non-ASCII data properly. .PP Filenames and the configuration file are assumed to be encoded using the -current locale. Internally (within the server, in the database and in +current locale. +Internally (within the server, in the database and in communication between client and server) the UTF-8 encoding is used. .SS Backups DisOrder uses Berkeley DB but currently discards log files that are no longer -in use. This means that DB's catastrophic recovery cannot be used (normal +in use. +This means that DB's catastrophic recovery cannot be used (normal recovery can be used, and indeed the server does this automatically on startup). .PP @@ -104,7 +112,8 @@ It may be more convenient to perform these operations from the client .SH FILES .TP .I pkgconfdir/config -Global configuration file. See \fBdisorder_config\fR(5). +Global configuration file. +See \fBdisorder_config\fR(5). .TP .I pkgconfdir/config.private Private configuration (usernames and passwords). @@ -113,7 +122,8 @@ Private configuration (usernames and passwords). Per-user password file. .TP .I pkgstatedir/queue -Saved copy of queue. Do not edit while the daemon is running. +Saved copy of queue. +Do not edit while the daemon is running. .TP .I pkgstatedir/recent Saved copy of recently played track list. @@ -135,9 +145,10 @@ Tag lookup database. Tracks database. .TP .I pkgstatedir/DB_CONFIG -Berkeley DB configuration file. This may be used to override database -settings without recompiling DisOrder. See the Berkeley DB -documention for further details. +Berkeley DB configuration file. +This may be used to override database settings without recompiling +DisOrder. +See the Berkeley DB documention for further details. .TP .I pkgstatedir/log.* \fRand \fIpkgstatedir/__db.* Database internal files. @@ -146,12 +157,13 @@ Database internal files. Communication socket for \fBdisorder\fR(1). .TP .I pkgstatedir/lock -Lockfile. This prevents multiple instances of DisOrder running -simultaneously. +Lockfile. +This prevents multiple instances of DisOrder running simultaneously. .SH ENVIRONMENT .TP .B LC_ALL\fR, \fBLANG\fR, etc -Current locale. See \fBlocale\fR(7). +Current locale. +See \fBlocale\fR(7). .SH "SEE ALSO" \fBdisorder\fR(1), \fBdisorder_config\fR(5), \fBdisorder-dump\fR(8) .\" Local Variables: diff --git a/doc/disorderfm.1.in b/doc/disorderfm.1.in index 233d506..a647aa6 100644 --- a/doc/disorderfm.1.in +++ b/doc/disorderfm.1.in @@ -45,14 +45,15 @@ Specifies the filename encoding used below .IR DESTINATION . .PP If neither of \fB--from\fR or \fB--to\fR are specified then no encoding -translation is performed. If only one is specified then the other is set to -the current locale. +translation is performed. +If only one is specified then the other is set to the current locale. .TP .B --windows-friendly\fR, \fB-w Specifies that filenames below .I DESTINATION -must be Windows-friendly. This is achieved by replacing special characters -with '_', prefixing device names with '_' and stripping trailing dots and +must be Windows-friendly. +This is achieved by replacing special characters with '_', prefixing +device names with '_' and stripping trailing dots and spaces. .SS "File Selection" .TP @@ -62,18 +63,19 @@ Include filenames matching the glob pattern \fIPATTERN\fR. .B --exclude\fI PATTERN\fR, \fB-e\fI PATTERN Exclude filenames matching the glob pattern \fIPATTERN\fR. .PP -These options may be used more than once. They will be checked in order and -the first that matches any given filename will determine whether that file is -included or excluded. +These options may be used more than once. +They will be checked in order and the first that matches any given +filename will determine whether that file is included or excluded. .PP If none of the options match and \fB--include\fR was used at all then the file -is excluded. If none of the options match and \fB--include\fR was never used -then the file is included. +is excluded. +If none of the options match and \fB--include\fR was never used then the file +is included. .SS "File Copying" .TP .B --link\fR, \fB-l -Files are hard-linked to their destination location. This is the default -action. +Files are hard-linked to their destination location. +This is the default action. .TP .B --symlink\fR, \fB-s Symlinks are made in the destination location pointing back into the source @@ -83,8 +85,8 @@ directory. Files are copied into their destination location. .TP .B --no-action\fR, \fB-n -The destination location is not modified in any way. Instead a report is -written to standard output saying what would be done. +The destination location is not modified in any way. +Instead a report is written to standard output saying what would be done. .SS "Other" .TP .B --debug\fR, \fB-d diff --git a/doc/tkdisorder.1 b/doc/tkdisorder.1 index d32c6ec..390032b 100644 --- a/doc/tkdisorder.1 +++ b/doc/tkdisorder.1 @@ -24,12 +24,16 @@ tkdisorder \- DisOrder jukebox client .RI [ OPTIONS ] .SH DESCRIPTION .B tkdisorder -is a simple graphical client for DisOrder. It is not finished and no further -development is planned. Use \fBdisobedience\fR(1) instead. +is a simple graphical client for DisOrder. +It is not finished and no further +development is planned. +Use \fBdisobedience\fR(1) instead. .PP -The main window is divided into two. The top half contains the name +The main window is divided into two. +The top half contains the name of the current track and a progress bar indicating how far through -playing it is. It also contains three buttons: +playing it is. +It also contains three buttons: .TP .B Quit Terminates tkdisorder. -- [mdw]