chiark / gitweb /
docs updates for web ui changes
[disorder] / templates / help.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
2 <!--
3 This file is part of DisOrder.
4 Copyright (C) 2004, 2005, 2006, 2007 Richard Kettlewell
5
6 This program is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2 of the License, or
9 (at your option) any later version.
10
11 This program is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14 General Public License for more details.
15
16 You should have received a copy of the GNU General Public License
17 along with this program; if not, write to the Free Software
18 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
19 USA
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
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
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
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 <!--
363 Local variables:
364 mode:sgml
365 sgml-always-quote-attributes:nil
366 sgml-indent-step:1
367 sgml-indent-data:t
368 End:
369 -->