chiark / gitweb /
docs updates for web ui changes
[disorder] / templates / help.html
CommitLineData
460b9539 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
2<!--
3This file is part of DisOrder.
d5b6ffd7 4Copyright (C) 2004, 2005, 2006, 2007 Richard Kettlewell
460b9539 5
6This program is free software; you can redistribute it and/or modify
7it under the terms of the GNU General Public License as published by
8the Free Software Foundation; either version 2 of the License, or
9(at your option) any later version.
10
11This program is distributed in the hope that it will be useful, but
12WITHOUT ANY WARRANTY; without even the implied warranty of
13MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14General Public License for more details.
15
16You should have received a copy of the GNU General Public License
17along with this program; if not, write to the Free Software
18Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
19USA
20-->
21<html>
22 <head>
23@include{stdhead}@
24 <title>@label{help.title}@</title>
25 </head>
26 <body>
27@include{@label{menu}@}@
28 <h1 class=title>@label{help.title}@</h1>
29
30 <h2 class=sidebarlink><a name=playing>Playing</a></h2>
31
32 <div class=helpsection>
33
34 <p>This screen displays the currently playing track (if there is one) and
35 lists all the tracks in the queue (the track that will be played soonest
36 being listed first.) Where possible, estimated start times are
37 given.</p>
38
39 <p>Each track has a <img class=button
40 src="@label:images.scratch@"
41 title="@label:playing.scratch@"
42 alt="@label:playing.scratch@"> button next to it. For the
43 currently playing track this can be used to stop playing the
44 track before it has finished. For a track in the queue it
45 removes the track from the queue.</p>
46
47 <p>Depending on the server configuration, you may be able to do
48 this for any track, or only for tracks you submitted or that were
49 randomly picked. See the "restrict" option in <a
50 href="@url@?action=disorder_config.5">disorder_config(5)</a> for more
51 details.</p>
52
53 <p>Artist and album names are hyperlinks to the relevant locations
54 in the <a href="#choose">Choose</a> screen (see below).</p>
55
56 </div>
57
58 <h2 class=sidebarlink><a name=manage>Manage</a></h2>
59
60 <div class=helpsection>
61
62 <p>This screen is almost identical to <a
63 href="#playing">Playing</a> except that it includes extra
64 management features.</p>
65
66 <p>At the top of the screen are the following controls:</p>
67
68 <ul>
69 <li>Pause. This button can be used to pause playing (provided the
70 player supports it). <img width=16 height=16 class=imgbutton
71 src="@label:images.enabled@"> indicates that playing is paused,
72 <img width=16 height=16 class=imgbutton
73 src="@label:images.disabled@"> that it is not.</li>
74
75 <li>Enable/disable random play. If disabled then queued tracks
76 will still be played but if the queue is empty nothing will be
77 picked at random. <img width=16 height=16 class=imgbutton
78 src="@label:images.enabled@"> indicates that random play is
79 enabled, <img width=16 height=16 class=imgbutton
80 src="@label:images.disabled@"> that it is disabled.</li>
81
82 <li>Enable/disable play. If disabled then tracks in the queue
83 will not be played, but will remain in the queue instead. <img
84 width=16 height=16 class=imgbutton src="@label:images.enabled@">
85 indicates that play is enabled, <img width=16 height=16
86 class=imgbutton src="@label:images.disabled@"> that it is
87 disabled.</li>
88
89 <li>Volume control. You can use the <img class=button
90 src="@label:images.up@"
91 title="@label:volume.increase@"
92 alt="@label:volume.increase@"> and <img
93 src="@label:images.down@"
94 title="@label:volume.reduce@"
95 alt="@label:volume.reduce@"> buttons to increase or
96 decrease the volume, or enter new volume settings for the left
97 and/or right speakers.</li>
98
99 </ul>
100
101 <p>Below this is the same table of current and queued tracks as for
102 the main playing screen, but with extra buttons for managing the
103 queue.
104 The <img class=button src="@label:images.up@"
105 title="@label:playing.up@" alt="@label:playing.up@"> and <img
106 src="@label:images.down@" title="@label:playing.down@"
107 alt="@label:playing.down@"> buttons on each track move that
108 track around in the queue. Similarly the <img class=button
109 src="@label:images.upall@" title="@label:playing.upall@"
110 alt="@label:playing.upall@"> and <img
111 src="@label:images.downall@" title="@label:playing.downall@"
112 alt="@label:playing.downall@"> buttons move each track to the head or
113 tail of the queue.
114 Depending on server configuration, it may be that only trusted
115 users can move tracks around the queue.</p>
116
117 </div>
118
119 <h2 class=sidebarlink><a name=recent>Recent</a></h2>
120
121 <div class=helpsection>
122
123 <p>This screen displays recently played tracks, most recent first.
124 The <img class=button src="@label:images.edit@"
125 title="@label:choose.prefs@" alt="@label:choose.prefs@">
126 button can be used to edit the details for a track; see <a
127 href="#prefs">Editing Preferences</a> below.</p>
128
129 <p>The number of tracks remembered is controlled by the server
130 configuration. See the "history" option in <a
131 href="@url@?action=disorder_config.5">disorder_config(5)</a> for more
132 details.</p>
133
134 </div>
135
78efa64e
RK
136 <h2 class=sidebarlink><a name=new>New</a></h2>
137
138 <div class=helpsection>
139
140 <p>This screen displays tracks recently added to the database,
141 most recent first. The <img class=button
142 src="@label:images.edit@" title="@label:choose.prefs@"
143 alt="@label:choose.prefs@"> button can be used to edit the details
144 for a track; see <a href="#prefs">Editing Preferences</a> below,
145 and clicking on the track title will add it to the queue.</p>
146
147 <p>The time tracks are remembered for is controlled by the server
148 configuration. See the "noticed_history" option in <a
149 href="@url@?action=disorder_config.5">disorder_config(5)</a> for
150 more details.</p>
151
152 </div>
153
460b9539 154 <h2 class=sidebarlink><a name=choose>Choose</a></h2>
155
156 <div class=helpsection>
157
158 <p>This screen allows you to choose a track to be played, by navigating
159 through the directory structure of the tracks filesystem. The following
160 buttons appear:</p>
161
162 <table class=helpbuttons>
163 <tbody>
164 <tr>
165 <td class=helpbuttons><img
166 class=button src="@label:images.edit@"
167 title="@label:choose.prefs@"
168 alt="@label:choose.prefs@"></td>
169 <td class=helpbuttons>This button can be used to edit the details for a
170 track; see <a href="#prefs">Editing Preferences</a> below.</td>
171 </tr>
172 <tr>
173 <td class=helpbuttons><span class=button>@label{choose.playall}@</span></td>
174 <td class=helpbuttons>This button plays all the tracks in a directory,
175 in order. This is used to efficiently play a whole album.</td>
176 </tr>
177 </tbody>
178 </table>
179
180 <p>This screen has two forms: <a
181 href="@url@?action=choose&#38;nonce=@nonce@">choose</a>, which give
182 you all the top-level directories at once, and <a
183 href="@url@?action=choosealpha&#38;nonce=@nonce@">choosealpha</a>,
184 which breaks them down by initial letter.</p>
185
186 </div>
187
188 <h2 class=sidebarlink><a name=prefs>Editing Preferences</a></h2>
189
190 <div class=helpsection>
191
192 <p>This screen, reached from <a href="#choose">Choose</a> or <a
193 href="#recent">Recent</a>, is used to edit a track's preferences.
194 Preferences can be edited in two ways.</p>
195
196 <p>At the top appear "cooked" preferences. These can be used to
197 edit artist, album and title fields for the track as displayed, or
198 to set the tags for a track, or to enable or disable random play
199 for the track.</p>
200
201 <p>Tags are separated by commas and can contain any other printing
202 characters (including spaces). Leading and trailing spaces are
203 not significant.</p>
204
205 <p>Random play for any given track is enabled by default, but you
206 can use this screen to disable it for undesirable tracks.</p>
207
208 <p>Below this are "raw" preferences, which allow individual
209 database fields to be modified.</p>
210
211 <p>To change an existing preference, edit its value and press its
212 <span class=button>@label{prefs.set}@</span> button.</p>
213
214 <p>To delete an existing preference, press its
215 <span class=button>@label{prefs.delete}@</span> button.</p>
216
217 <p>To add a new preference, enter its name and value in the box at the
218 bottom and press the <span class=button>@label{prefs.new}@</span> button.
219 If the preference exists already it will be overwritten.</p>
220
221
222 <p>Preferences can have any name or value but certain names have special
223 significance:</p>
224
225 <table class=helpprefs>
226 <tbody>
227 <tr>
228 <td class=helpprefs><span class=helppref>pick_at_random</span></td>
229 <td class=helpprefs>If this preference is present and set to "0" then
230 the track will not be picked for random play. Otherwise it may be.</td>
231 </tr>
232 <tr>
233 <td class=helpprefs><span class=helppref>trackname_<span class=helpprefbit>context</span>_<span class=helpprefbit>part</span></span></td>
234 <td class=helpprefs>These preferences can be used to override the
235 filename parsing rules to find a track name part. <span
236 class=helppref>trackname_<span class=helpprefbit>part</span></span> will
237 be used if the full version is not present.</td>
238 </tbody>
239 </table>
240
241 <p><span class=helpprefbit>context</span> can be anything but standard
242 values are:</p>
243
244 <table class=helpcontexts>
245 <tbody>
246 <tr>
247 <td class=helpcontexts><span class=helpcontext>display</span></td>
248 <td class=helpcontexts>Displayed in a web page</td>
249 </tr>
250 <tr>
251 <td class=helpcontexts><span class=helpcontext>sort</span></td>
252 <td class=helpcontexts>Used when sorting track names</td>
253 </tr>
254 </tbody>
255 </table>
256
257 <p><span class=helpprefbit>part</span> can be anything too but standard
258 values are "artist", "album" and "title", with the obvious meanings.</p>
259
260 <p>See also <a href="@url@?action=disorder.1">disorder(1)</a> and <a
261 href="@url@?action=disorder_config.5">disorder_config(5)</a> for further
262 details.</p>
263
264 </div>
265
266 <h2 class=sidebarlink>Search</h2>
267
268 <div class=helpsection>
269
270 <p>This screen allows you to search for keywords in track names. If you
271 specify more than one keyword then only tracks containing all of them are
272 listed. Results are grouped by artist, album and title.</p>
273
274 <p>It is possible to limit results to tracks with a particular
275 tag, by using <b>tag:</b><i>TAG</i> among the search terms.</p>
276
277 <p>Some keywords, known as "stopwords", are excluded from the search, and
278 will never match. See the "stopword" option in <a
279 href="@url@?action=disorder_config.5">disorder_config(5)</a> for further
280 details about this.</p>
281
282 </div>
283
284 @if{@eq{@label:menu@}{sidebar}@}
285 {
286
287 <h2 class=sidebarlink>Volume</h2>
288
289 <div class=helpsection>
290
291 <p>This screen allows you to set the playback volume, if this is enabled in
292 the server configuration. See the "channel" and "mixer" options in <a
293 href="@url@?action=disorder_config.5">disorder_config(5)</a> for further
294 details about this.</p>
295
296 </div>
297
298 }{<!-- volume currently only linked in sidebar menu -->}@
299
300 <h2 class=sidebarlink>Troubleshooting</h2>
301
302 <div class=helpsection>
303
304 <p>If you cannot play a track, or it does not appear in the
305 database even after a rescan, check the following things:</p>
306
307 <ul>
308
309 <li>Are there any error messages in the system log? The server
310 logs to <tt>LOG_DAEMON</tt>, which typically ends up in
311 <i>/var/log/daemon.log</i> or <i>/var/log/messages</i>, though
312 this depends on local configuration.
313
314 <li>Is the track in a known format? Have a look at the
315 configuration file for the formats recognized by the local
316 installation. The filename matching is case-sensitive.
317
318 <li>Do permissions on the track allow the server to read it?
319
320 <li>Do the permissions on the containing directories allow the
321 server to read and execute them?
322
323 </ul>
324
325 <p>The user the server runs as is determined by the <tt>user</tt>
326 directive in the configuration file. The README recommends using
327 <b>jukebox</b> for this purpose but it could be different
328 locally.</p>
329
330 </div>
331
332 <h2 class=sidebarlink>Man Pages</h2>
333
334 <div class=helpsection>
335
336 <p><a href="@url@?action=disorder_config.5">disorder_config(5)</a> -
337 configuration</p>
338
339 <p><a href="@url@?action=disorder.1">disorder(1)</a> - command line
340 client</p>
341
342 <p><a href="@url@?action=disobedience.1">disobedience(1)</a> - GTK+
343 client</p>
344
460b9539 345 <p><a href="@url@?action=disorderd.8">disorderd(8)</a> - server</p>
346
347 <p><a href="@url@?action=disorder-dump.8">disorder-dump(8)</a> -
348 dump/restore preferences database</p>
349
350 <p><a href="@url@?action=disorder.3">disorder(3)</a> - C API</p>
351
352 <p><a href="@url@?action=disorder_protocol.5">disorder_protocol(5)</a> -
353 DisOrder control protocol</p>
354
355 </div>
356
357@include{@label{menu}@end}@
358 </div>
359 </body>
360</html>
361@@
362<!--
363Local variables:
364mode:sgml
365sgml-always-quote-attributes:nil
366sgml-indent-step:1
367sgml-indent-data:t
368End:
369-->