From b6579a61e2a45377f15954c0ec09ce991f4c0645 Mon Sep 17 00:00:00 2001 Message-Id: From: Mark Wooding Date: Wed, 5 Dec 2007 19:15:13 +0000 Subject: [PATCH] documentation update Organization: Straylight/Edgeware From: Richard Kettlewell --- doc/disobedience.1.in | 30 +++++++--------------------- doc/disorder-dbupgrade.8.in | 10 ++++++++-- doc/disorder-deadlock.8.in | 6 ++++++ doc/disorder-decode.8.in | 7 +++++++ doc/disorder-dump.8.in | 4 ---- doc/disorder-normalize.8 | 19 ++++++++++++++++++ doc/disorder-playrtp.1.in | 40 +++++++++++++++++++++++++++++++++++++ doc/disorder-rescan.8.in | 6 ++++++ doc/disorder-speaker.8 | 19 ++++++++++++++++++ doc/disorder-stats.8.in | 6 ++++++ doc/disorder.1.in | 11 ---------- doc/disorder.3 | 10 ++++++++-- doc/tkdisorder.1 | 5 +++-- 13 files changed, 129 insertions(+), 44 deletions(-) diff --git a/doc/disobedience.1.in b/doc/disobedience.1.in index 9410f2a..cc17756 100644 --- a/doc/disobedience.1.in +++ b/doc/disobedience.1.in @@ -301,29 +301,6 @@ The screen number to use. .\" .TP .\" .B --sync .\" Make all X requests synchronously. -.SH "GTK+ RESOURCES" -You can override these resources in order to customize the appearance of -Disobedience. -.\" TODO example that actually works. -.SS "Widget Names" -.TP -.B disobedience.*.choose -This is the panel containing the track choice tree. -.TP -.B disobedience.*.queue -This is the panel displaying the queue. -.TP -.B disobedience.*.choose -This is the panel listing recently played tracks. -.TP -.B disobedience.*.row-playing -This is the row listing the currently playing track. -.TP -.B disobedience.*.row-odd -This an odd-numbered row in the queue or recently played track list. -.TP -.B disobedience.*.row-even -This an even-numbered row in the queue or recently played track list. .SH CONFIGURATION If you are using .B disobedience @@ -339,6 +316,13 @@ 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. +.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. .SH FILES .TP .I ~/.disorder/HOSTNAME-rtp diff --git a/doc/disorder-dbupgrade.8.in b/doc/disorder-dbupgrade.8.in index 7da152b..3a6c2d7 100644 --- a/doc/disorder-dbupgrade.8.in +++ b/doc/disorder-dbupgrade.8.in @@ -26,7 +26,7 @@ disorder-dbupgrade \- DisOrder Database Upgrader .SH DESCRIPTION .B disorder-dbupgrade is DisOrder's database upgrader. It is invoked by DisOrder when -necessary and does not need to be invoked manually. +necessary and does not normally need to be invoked manually. .SH OPTIONS .TP .B --delete-bad-keys\fR, -x @@ -45,6 +45,12 @@ Set the configuration file. .B --debug\fR, \fB-d Enable debugging. .TP +.B --syslog +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. +.TP .B --help\fR, \fB-h Display a usage message. .TP @@ -56,7 +62,7 @@ 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 harmles. +option can be used to delete them if they are known to be harmless. .SH "SEE ALSO" \fBdisorderd\fR(8), \fBdisorder_config\fR(5) .\" Local Variables: diff --git a/doc/disorder-deadlock.8.in b/doc/disorder-deadlock.8.in index 8957186..df6db6f 100644 --- a/doc/disorder-deadlock.8.in +++ b/doc/disorder-deadlock.8.in @@ -34,6 +34,12 @@ Set the configuration file. .B --debug\fR, \fB-d Enable debugging. .TP +.B --syslog +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. +.TP .B --help\fR, \fB-h Display a usage message. .TP diff --git a/doc/disorder-decode.8.in b/doc/disorder-decode.8.in index 91c5996..f4ae673 100644 --- a/doc/disorder-decode.8.in +++ b/doc/disorder-decode.8.in @@ -31,6 +31,13 @@ therefore suitable for use as an player. .PP It is not intended to be used from the command line. +.SH OPTIONS +.TP +.B --help\fR, \fB-h +Display a usage message. +.TP +.B --version\fR, \fB-V +Display version number. .SH LIMITATIONS OGG files with multiple bitstreams are not supported. .PP diff --git a/doc/disorder-dump.8.in b/doc/disorder-dump.8.in index c876738..fe7e8b4 100644 --- a/doc/disorder-dump.8.in +++ b/doc/disorder-dump.8.in @@ -77,10 +77,6 @@ Taking a backup of the non-regeneratable parts of DisOrder's databases. .B . Indoctrinating one DisOrder server with the preference values of another. -.TP -.B . -Upgrading DisOrder across data format changes in the underlying -database library. .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 diff --git a/doc/disorder-normalize.8 b/doc/disorder-normalize.8 index b48b4af..7629439 100644 --- a/doc/disorder-normalize.8 +++ b/doc/disorder-normalize.8 @@ -27,5 +27,24 @@ is used by .BR disorderd (8) 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 +Set the configuration file. +.TP +.B --debug\fR, \fB-d +Enable debugging. +.TP +.B --syslog +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. +.TP +.B --help\fR, \fB-h +Display a usage message. +.TP +.B --version\fR, \fB-V +Display version number. .SH "SEE ALSO" .BR disorderd (8) diff --git a/doc/disorder-playrtp.1.in b/doc/disorder-playrtp.1.in index f4bcfd6..bdd05ec 100644 --- a/doc/disorder-playrtp.1.in +++ b/doc/disorder-playrtp.1.in @@ -39,11 +39,29 @@ broadcast to that port. If a group and a port are specified then the RTP stream is assumed to be multicast to that group and port. .SH OPTIONS +The default sound API is the first of the ones listed below that are available. +Usually this implies ALSA under Linux and Core Audio under OS X. +.TP +.B --alsa\fR, \fB-a +Use ALSA to play sound. +.TP +.B --oss\fR, \fB-o +Use OSS to play sound. +.TP +.B --core-audio\fR, \fB-c +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. .TP +.B --config \fIPATH\fR, \fB-C \fIPATH +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. +.TP .B --help\fR, \fB-h Display a usage message. .TP @@ -68,7 +86,29 @@ is four times the \fB--buffer\fR value. .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. +.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: +.TP +.B stop +Causes +.B disorder-playrtp +to terminate. +.TP +.B query +Causes the string "running" to be sent back. +.PP +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. .SH "SEE ALSO" +.BR disobedience (1), .BR disorder_config (5), .BR disorderd (8) .\" Local Variables: diff --git a/doc/disorder-rescan.8.in b/doc/disorder-rescan.8.in index 94dfc28..6a204de 100644 --- a/doc/disorder-rescan.8.in +++ b/doc/disorder-rescan.8.in @@ -35,6 +35,12 @@ Set the configuration file. .B --debug\fR, \fB-d Enable debugging. .TP +.B --syslog +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. +.TP .B --help\fR, \fB-h Display a usage message. .TP diff --git a/doc/disorder-speaker.8 b/doc/disorder-speaker.8 index a304da4..b3b2208 100644 --- a/doc/disorder-speaker.8 +++ b/doc/disorder-speaker.8 @@ -27,5 +27,24 @@ is used by .BR disorderd (8) to play digital audio with buffering and avoiding gaps between tracks. It is not intended for direct invocation. +.SH OPTIONS +.TP +.B --config \fIPATH\fR, \fB-c \fIPATH +Set the configuration file. +.TP +.B --debug\fR, \fB-d +Enable debugging. +.TP +.B --syslog +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. +.TP +.B --help\fR, \fB-h +Display a usage message. +.TP +.B --version\fR, \fB-V +Display version number. .SH "SEE ALSO" .BR disorderd (8) diff --git a/doc/disorder-stats.8.in b/doc/disorder-stats.8.in index 4ceda15..4719a3e 100644 --- a/doc/disorder-stats.8.in +++ b/doc/disorder-stats.8.in @@ -34,6 +34,12 @@ Set the configuration file. .B --debug\fR, \fB-d Enable debugging. .TP +.B --syslog +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. +.TP .B --help\fR, \fB-h Display a usage message. .TP diff --git a/doc/disorder.1.in b/doc/disorder.1.in index a05ca8c..89863de 100644 --- a/doc/disorder.1.in +++ b/doc/disorder.1.in @@ -24,14 +24,7 @@ disorder \- DisOrder jukebox client .RI [ OPTIONS ] .RB [ -- ] .RI [ COMMANDS ...] -.br -.B disorder -.B --length -.RI [ OPTIONS ] -.RB [ -- ] -.IR PATH ... .SH DESCRIPTION -Without the \fB--length\fR option, .B disorder is used to query the \fBdisorderd\fR(8) daemon from the command line. It may be used to request tracks, scratch tracks, query the current @@ -54,10 +47,6 @@ Enable debugging. .B --help\fR, \fB-h Display a usage message. .TP -.B --length\fR, \fB-L -Calculate the length in seconds of the files specified using the tracklength -plugin. -.TP .B --version\fR, \fB-V Display version number. .TP diff --git a/doc/disorder.3 b/doc/disorder.3 index f84bd16..b4d811d 100644 --- a/doc/disorder.3 +++ b/doc/disorder.3 @@ -77,6 +77,9 @@ you do not need to free the results. .IP Floating point conversions and wide character support are not currently implemented. +.IP +These functions will cope with UTF-8 even if the current locale uses +some other encoding. .PP "Never fail" in the above means that the process is terminated on error. .SH LOGGING @@ -167,8 +170,8 @@ Currently this means that they are not even defined outside the server. .PP All strings in this section are encoded using UTF-8. -.SS tracklength.so -This is a server plugin. +.SS "Tracklength Plugins" +These are server plugins defined by the \fBtracklength\fR directive. .PP .nf \fBlong disorder_tracklength(const char *track, @@ -181,6 +184,9 @@ 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 +To clarify this point, if the track must be opened to compute its +length, you would normally use \fBpath\fR and not \fBtrack\fR. +.IP If the return value is positive it should be the track length in seconds (round up if it is not an integral number of seconds long). .IP diff --git a/doc/tkdisorder.1 b/doc/tkdisorder.1 index 6d535be..d32c6ec 100644 --- a/doc/tkdisorder.1 +++ b/doc/tkdisorder.1 @@ -24,7 +24,8 @@ tkdisorder \- DisOrder jukebox client .RI [ OPTIONS ] .SH DESCRIPTION .B tkdisorder -is a simple graphical client for DisOrder. It is not really finished. +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 of the current track and a progress bar indicating how far through @@ -50,7 +51,7 @@ Display a usage message. .B --version\fR, \fB-V Display version number. .SH "SEE ALSO" -\fBdisorder\fR(1), \fBdisorder_config\fR(5) +\fBdisorder\fR(1), \fBdisobedience\fR(1), \fBdisorder_config\fR(5) .PP "\fBpydoc disorder\fR" for the Python API documentation. .\" Local Variables: -- [mdw]