chiark / gitweb /
Merge from MDW's branch:
[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 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=choose>Choose</a></h2>
137
138    <div class=helpsection>
139
140     <p>This screen allows you to choose a track to be played, by navigating
141      through the directory structure of the tracks filesystem.  The following
142      buttons appear:</p>
143
144     <table class=helpbuttons>
145      <tbody>
146       <tr>
147        <td class=helpbuttons><img
148        class=button src="@label:images.edit@"
149        title="@label:choose.prefs@"
150        alt="@label:choose.prefs@"></td>
151        <td class=helpbuttons>This button can be used to edit the details for a
152        track; see <a href="#prefs">Editing Preferences</a> below.</td>
153       </tr>
154       <tr>
155        <td class=helpbuttons><span class=button>@label{choose.playall}@</span></td>
156        <td class=helpbuttons>This button plays all the tracks in a directory,
157        in order.  This is used to efficiently play a whole album.</td>
158       </tr>
159      </tbody>
160     </table>
161
162     <p>This screen has two forms: <a
163     href="@url@?action=choose&#38;nonce=@nonce@">choose</a>, which give
164     you all the top-level directories at once, and <a
165     href="@url@?action=choosealpha&#38;nonce=@nonce@">choosealpha</a>,
166     which breaks them down by initial letter.</p>
167
168    </div>
169
170    <h2 class=sidebarlink><a name=prefs>Editing Preferences</a></h2>
171
172    <div class=helpsection>
173
174     <p>This screen, reached from <a href="#choose">Choose</a> or <a
175     href="#recent">Recent</a>, is used to edit a track's preferences.
176      Preferences can be edited in two ways.</p>
177     
178     <p>At the top appear "cooked" preferences.  These can be used to
179     edit artist, album and title fields for the track as displayed, or
180     to set the tags for a track, or to enable or disable random play
181     for the track.</p>
182
183     <p>Tags are separated by commas and can contain any other printing
184     characters (including spaces).  Leading and trailing spaces are
185     not significant.</p>
186
187     <p>Random play for any given track is enabled by default, but you
188     can use this screen to disable it for undesirable tracks.</p>
189
190     <p>Below this are "raw" preferences, which allow individual
191     database fields to be modified.</p>
192
193     <p>To change an existing preference, edit its value and press its
194     <span class=button>@label{prefs.set}@</span> button.</p>
195
196     <p>To delete an existing preference, press its
197     <span class=button>@label{prefs.delete}@</span> button.</p>
198
199     <p>To add a new preference, enter its name and value in the box at the
200     bottom and press the <span class=button>@label{prefs.new}@</span> button.
201     If the preference exists already it will be overwritten.</p>
202
203
204     <p>Preferences can have any name or value but certain names have special
205     significance:</p>
206
207     <table class=helpprefs>
208      <tbody>
209       <tr>
210        <td class=helpprefs><span class=helppref>pick_at_random</span></td>
211        <td class=helpprefs>If this preference is present and set to "0" then
212        the track will not be picked for random play.  Otherwise it may be.</td>
213       </tr>
214       <tr>
215        <td class=helpprefs><span class=helppref>trackname_<span class=helpprefbit>context</span>_<span class=helpprefbit>part</span></span></td>
216        <td class=helpprefs>These preferences can be used to override the
217        filename parsing rules to find a track name part.  <span
218        class=helppref>trackname_<span class=helpprefbit>part</span></span> will
219        be used if the full version is not present.</td>
220      </tbody>
221     </table>
222
223     <p><span class=helpprefbit>context</span> can be anything but standard
224     values are:</p>
225
226     <table class=helpcontexts>
227      <tbody>
228       <tr>
229        <td class=helpcontexts><span class=helpcontext>display</span></td>
230        <td class=helpcontexts>Displayed in a web page</td>
231       </tr>
232       <tr>
233        <td class=helpcontexts><span class=helpcontext>sort</span></td>
234        <td class=helpcontexts>Used when sorting track names</td>
235       </tr>
236      </tbody>
237     </table>
238
239     <p><span class=helpprefbit>part</span> can be anything too but standard
240     values are "artist", "album" and "title", with the obvious meanings.</p>
241
242     <p>See also <a href="@url@?action=disorder.1">disorder(1)</a> and <a
243     href="@url@?action=disorder_config.5">disorder_config(5)</a> for further
244     details.</p>
245
246    </div>
247
248    <h2 class=sidebarlink>Search</h2>
249
250    <div class=helpsection>
251
252     <p>This screen allows you to search for keywords in track names.  If you
253     specify more than one keyword then only tracks containing all of them are
254     listed.  Results are grouped by artist, album and title.</p>
255
256     <p>It is possible to limit results to tracks with a particular
257     tag, by using <b>tag:</b><i>TAG</i> among the search terms.</p>
258
259     <p>Some keywords, known as "stopwords", are excluded from the search, and
260     will never match.  See the "stopword" option in <a
261     href="@url@?action=disorder_config.5">disorder_config(5)</a> for further
262     details about this.</p>
263
264    </div>
265
266   @if{@eq{@label:menu@}{sidebar}@}
267      {
268
269    <h2 class=sidebarlink>Volume</h2>
270
271    <div class=helpsection>
272
273     <p>This screen allows you to set the playback volume, if this is enabled in
274     the server configuration.  See the "channel" and "mixer" options in <a
275     href="@url@?action=disorder_config.5">disorder_config(5)</a> for further
276     details about this.</p>
277
278    </div>
279
280      }{<!-- volume currently only linked in sidebar menu -->}@ 
281
282   <h2 class=sidebarlink>Troubleshooting</h2>
283
284   <div class=helpsection>
285
286    <p>If you cannot play a track, or it does not appear in the
287    database even after a rescan, check the following things:</p>
288
289    <ul>
290
291     <li>Are there any error messages in the system log?  The server
292     logs to <tt>LOG_DAEMON</tt>, which typically ends up in
293     <i>/var/log/daemon.log</i> or <i>/var/log/messages</i>, though
294     this depends on local configuration.
295
296     <li>Is the track in a known format?  Have a look at the
297     configuration file for the formats recognized by the local
298     installation.  The filename matching is case-sensitive.
299
300     <li>Do permissions on the track allow the server to read it?
301      
302     <li>Do the permissions on the containing directories allow the
303     server to read and execute them?
304
305    </ul>
306
307    <p>The user the server runs as is determined by the <tt>user</tt>
308    directive in the configuration file.  The README recommends using
309    <b>jukebox</b> for this purpose but it could be different
310    locally.</p>
311
312   </div>
313
314    <h2 class=sidebarlink>Man Pages</h2>
315
316    <div class=helpsection>
317
318     <p><a href="@url@?action=disorder_config.5">disorder_config(5)</a> -
319      configuration</p>
320
321     <p><a href="@url@?action=disorder.1">disorder(1)</a> - command line
322      client</p>
323
324     <p><a href="@url@?action=disobedience.1">disobedience(1)</a> - GTK+
325      client</p>
326
327     <p><a href="@url@?action=tkdisorder.1">tkdisorder(1)</a> - GUI
328      client</p>
329
330     <p><a href="@url@?action=disorderd.8">disorderd(8)</a> - server</p>
331
332     <p><a href="@url@?action=disorder-dump.8">disorder-dump(8)</a> -
333      dump/restore preferences database</p>
334
335     <p><a href="@url@?action=disorder.3">disorder(3)</a> - C API</p>
336
337     <p><a href="@url@?action=disorder_protocol.5">disorder_protocol(5)</a> -
338      DisOrder control protocol</p>
339
340    </div>
341
342 @include{@label{menu}@end}@
343   </div>
344  </body>
345 </html>
346 @@
347 <!--
348 Local variables:
349 mode:sgml
350 sgml-always-quote-attributes:nil
351 sgml-indent-step:1
352 sgml-indent-data:t
353 End:
354 -->