X-Git-Url: https://git.distorted.org.uk/~mdw/disorder/blobdiff_plain/6f3acea989cf8191569cc59d492722662fb25464..2d0cdf2b2501a0d19726f1d5ba06e4596c77c6b7:/doc/disobedience.1.in diff --git a/doc/disobedience.1.in b/doc/disobedience.1.in index 82916fb..2c7ee78 100644 --- a/doc/disobedience.1.in +++ b/doc/disobedience.1.in @@ -1,5 +1,5 @@ .\" -.\" Copyright (C) 2004, 2005, 2006, 2007 Richard Kettlewell +.\" Copyright (C) 2004-2008 Richard Kettlewell .\" .\" This program is free software; you can redistribute it and/or modify .\" it under the terms of the GNU General Public License as published by @@ -24,52 +24,16 @@ disobedience \- GUI client for DisOrder jukebox .RI [ OPTIONS ] .SH DESCRIPTION .B disobedience -is a graphical client for DisOrder. It is a work in progress and many features -are not implemented yet. However everything in this man page is either -implemented or marked as missing. -.SH "SETTING UP" -You might use commands such as the following to set up a standalone instance of -Disobedience: -.PP -.RS -.nf -cd -mkdir .disorder -echo password > .disorder/passwd -echo connect >> .disorder/passwd -chmod 600 .disorder/passwd -.fi -.RE -.SH OPTIONS -.TP -.B --config \fIPATH\fR, \fB-c \fIPATH -Set the configuration file. The default is -.IR pkgconfdir/config . -.TP -.B --debug\fR, \fB-d -Enable debugging. -.TP -.B --help\fR, \fB-h -Display a usage message. -.TP -.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: -.TP -.B --display \fIDISPLAY\fR -The X display to use. -.TP -.B --screen \fISCREEN\fR -The screen number to use. -.\" If know enough to use it you know enough to find it -.\" .TP -.\" .B --sync -.\" Make all X requests synchronously. +is a graphical client for DisOrder. .SH "WINDOWS AND ICONS" .SS "File Menu" -This only has one option, "Quit", which terminates the program. +This has the following options: +.TP +.B Login +Brings up the \fBLogin Details Window\fR; see below. +.TP +.B Quit +Terminates the program. .SS "Edit Menu" This has the following options: .TP @@ -78,6 +42,27 @@ Select all tracks in whichever of the Queue or Recent tabs are showing. .TP .B Properties Edit the details of the selected tracks. +See +.B "Properties Window" +below. +.SS "Control Menu" +This has the following options: +.TP +.B Scratch +Interrupts the currently playing track. +.TP +.B Playing +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. +.TP +.B "Network player" +Enables or disables network play. +See +.B "NETWORK PLAY" +below. .SS "Help Menu" This has only one option, "About DisOrder", which pops up a box giving the name, author and version number of the software. @@ -91,37 +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 +.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 @@ -129,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 @@ -150,33 +148,105 @@ 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 -the display will be limited to tracks containing all those words. 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. +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 will pop up a menu with the following options: +Right clicking over a track will pop up a menu with the following options: .TP .B Play Play selected tracks. .TP .B Properties Edit properties of selected tracks. +See +.B "Properties Window" +below. +.PP +A middle click on a track will add it to the queue. +.PP +Right clicking over a directory will pop up a menu with the following options: +.TP +.B "Play all tracks" +Play all the tracks in the directory, in the order they appear on screen. +.TP +.B "Track properties" +Edit properties of all tracks in the directory. +.TP +.B "Select all tracks" +Select all the tracks in the directory (and deselect everything else). +.PP +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. +.PP +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 +.B "Properties Window" +below. +.TP +.B "Play track" +Play selected tracks. +.TP +.B "Select All 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: +.TP +.B Hostname +The host to connect to. +.TP +.B Service +The service name or port number to connect to. +.TP +.B "User name" +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. .PP -A middle click on a file will add it to the queue. +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. +.TP +.B Save +This button saves the current settings in +.IR $HOME/.disorder/passwd . +.TP +.B Close +This button closes the window, discarding any unsaved changes. .SS "Properties Window" This window contains details of one or more tracks and allows them to be edited. @@ -184,13 +254,19 @@ 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. +.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 all changes. @@ -199,48 +275,93 @@ all changes. .B CTRL+A Select all tracks (queue/recent) .TP +.B CTRL+L +Brings up the \fBLogin Details Window\fR. +.TP .B CTRL+Q Quit. -.SH "GTK+ RESOURCES" -You can override these resources in order to customize the appearance of -Disobedience. TODO example that actually works. -.SS "Widget Names" +.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 +disabled from a later run of Disobedience. +.PP +The player will log to +.I ~/.disorder/HOSTNAME\-rtp.log +so look there if it does not seem to be working. +.PP +You can stop it without running Disobedience by the command +.BR "killall disorder\-playrtp" . +.SH OPTIONS .TP -.B disobedience.*.choose -This is the panel containing the track choice tree. +.B \-\-config \fIPATH\fR, \fB\-c \fIPATH +Set the configuration file. +The default is +.IR pkgconfdir/config . .TP -.B disobedience.*.queue -This is the panel displaying the queue. +.B \-\-debug\fR, \fB\-d +Enable debugging. .TP -.B disobedience.*.choose -This is the panel listing recently played tracks. +.B \-\-help\fR, \fB\-h +Display a usage message. .TP -.B disobedience.*.row-playing -This is the row listing the currently playing track. +.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: .TP -.B disobedience.*.row-odd -This an odd-numbered row in the queue or recently played track list. +.B \-\-display \fIDISPLAY\fR +The X display to use. .TP -.B disobedience.*.row-even -This an even-numbered row in the queue or recently played track list. +.B \-\-screen \fISCREEN\fR +The screen number to use. +.\" If know enough to use it you know enough to find it +.\" .TP +.\" .B \-\-sync +.\" Make all X requests synchronously. .SH CONFIGURATION If you are using .B disobedience 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 server will need a -.B listen -directive in its configuration and the clien a matching -.B connect -directive. Also the client will need user passwords, either in -.IR pkgconfdir/config. USER -or -.IR ~ USER /.disorder.passwd . +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. +.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. +.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 +Socket for communication with RTP player. +.TP +.I ~/.disorder/HOSTNAME\-rtp.log +Log file for RTP player. .SH "SEE ALSO" +.BR disorder\-playrtp (1), .BR disorder_config (5) .PP -.B http://www.gtk.org/api/2.6/gtk/gtk-x11.html +.B http://www.greenend.org.uk/rjk/disorder/ +.br +- DisOrder home page +.PP +.B http://www.gtk.org/api/2.6/gtk/gtk\-x11.html .br - Using GTK+ on the X Window System .\" Local Variables: