[disorder] / templates / help.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<!--
This file is part of DisOrder.
Copyright (C) 2004, 2005, 2006 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
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
USA
-->
<html>
 <head>
@include{stdhead}@
  <title>@label{help.title}@</title>
 </head>
 <body>
@include{@label{menu}@}@
   <h1 class=title>@label{help.title}@</h1>

   <h2 class=sidebarlink><a name=playing>Playing</a></h2>

   <div class=helpsection>

    <p>This screen displays the currently playing track (if there is one) and
    lists all the tracks in the queue (the track that will be played soonest
    being listed first.)  Where possible, estimated start times are
    given.</p>

    <p>Each track has a <img class=button
       src="@label:images.scratch@"
       title="@label:playing.scratch@"
       alt="@label:playing.scratch@"> button next to it.  For the
       currently playing track this can be used to stop playing the
       track before it has finished.  For a track in the queue it
       removes the track from the queue.</p>

    <p>Depending on the server configuration, you may be able to do
    this for any track, or only for tracks you submitted or that were
    randomly picked.  See the "restrict" option in <a
    href="@url@?action=disorder_config.5">disorder_config(5)</a> for more
    details.</p>

   <p>Artist and album names are hyperlinks to the relevant locations
   in the <a href="#choose">Choose</a> screen (see below).</p>

   </div>

   <h2 class=sidebarlink><a name=manage>Manage</a></h2>

   <div class=helpsection>

    <p>This screen is almost identical to <a
    href="#playing">Playing</a> except that it includes extra
    management features.</p>

   <p>At the top of the screen are the following controls:</p>

   <ul>
    <li>Pause.  This button can be used to pause playing (provided the
    player supports it).  <img width=16 height=16 class=imgbutton
    src="@label:images.enabled@"> indicates that playing is paused,
    <img width=16 height=16 class=imgbutton
    src="@label:images.disabled@"> that it is not.</li>

    <li>Enable/disable random play.  If disabled then queued tracks
    will still be played but if the queue is empty nothing will be
    picked at random.  <img width=16 height=16 class=imgbutton
    src="@label:images.enabled@"> indicates that random play is
    enabled, <img width=16 height=16 class=imgbutton
    src="@label:images.disabled@"> that it is disabled.</li>

    <li>Enable/disable play.  If disabled then tracks in the queue
    will not be played, but will remain in the queue instead.  <img
    width=16 height=16 class=imgbutton src="@label:images.enabled@">
    indicates that play is enabled, <img width=16 height=16
    class=imgbutton src="@label:images.disabled@"> that it is
    disabled.</li>

    <li>Volume control.  You can use the <img class=button
       src="@label:images.up@"
       title="@label:volume.increase@"
       alt="@label:volume.increase@"> and <img
       src="@label:images.down@"
       title="@label:volume.reduce@"
       alt="@label:volume.reduce@"> buttons to increase or
    decrease the volume, or enter new volume settings for the left
    and/or right speakers.</li>

   </ul>

   <p>Below this is the same table of current and queued tracks as for
    the main playing screen, but with extra buttons for managing the
    queue.
    The <img class=button src="@label:images.up@"
     title="@label:playing.up@" alt="@label:playing.up@"> and <img
     src="@label:images.down@" title="@label:playing.down@"
     alt="@label:playing.down@"> buttons on each track move that
    track around in the queue.  Similarly the <img class=button
     src="@label:images.upall@" title="@label:playing.upall@"
     alt="@label:playing.upall@"> and <img
     src="@label:images.downall@" title="@label:playing.downall@"
     alt="@label:playing.downall@"> buttons move each track to the head or
    tail of the queue.
    Depending on server configuration, it may be that only trusted
    users can move tracks around the queue.</p>

   </div>

   <h2 class=sidebarlink><a name=recent>Recent</a></h2>

   <div class=helpsection>

    <p>This screen displays recently played tracks, most recent first.
    The <img class=button src="@label:images.edit@"
    title="@label:choose.prefs@" alt="@label:choose.prefs@">
    button can be used to edit the details for a track; see <a
    href="#prefs">Editing Preferences</a> below.</p>

    <p>The number of tracks remembered is controlled by the server
    configuration.  See the "history" option in <a
    href="@url@?action=disorder_config.5">disorder_config(5)</a> for more
    details.</p>

   </div>

   <h2 class=sidebarlink><a name=choose>Choose</a></h2>

   <div class=helpsection>

    <p>This screen allows you to choose a track to be played, by navigating
     through the directory structure of the tracks filesystem.  The following
     buttons appear:</p>

    <table class=helpbuttons>
     <tbody>
      <tr>
       <td class=helpbuttons><img
       class=button src="@label:images.edit@"
       title="@label:choose.prefs@"
       alt="@label:choose.prefs@"></td>
       <td class=helpbuttons>This button can be used to edit the details for a
       track; see <a href="#prefs">Editing Preferences</a> below.</td>
      </tr>
      <tr>
       <td class=helpbuttons><span class=button>@label{choose.playall}@</span></td>
       <td class=helpbuttons>This button plays all the tracks in a directory,
       in order.  This is used to efficiently play a whole album.</td>
      </tr>
     </tbody>
    </table>

    <p>This screen has two forms: <a
    href="@url@?action=choose&#38;nonce=@nonce@">choose</a>, which give
    you all the top-level directories at once, and <a
    href="@url@?action=choosealpha&#38;nonce=@nonce@">choosealpha</a>,
    which breaks them down by initial letter.</p>

   </div>

   <h2 class=sidebarlink><a name=prefs>Editing Preferences</a></h2>

   <div class=helpsection>

    <p>This screen, reached from <a href="#choose">Choose</a> or <a
    href="#recent">Recent</a>, is used to edit a track's preferences.
     Preferences can be edited in two ways.</p>
    
    <p>At the top appear "cooked" preferences.  These can be used to
    edit artist, album and title fields for the track as displayed, or
    to set the tags for a track, or to enable or disable random play
    for the track.</p>

    <p>Tags are separated by commas and can contain any other printing
    characters (including spaces).  Leading and trailing spaces are
    not significant.</p>

    <p>Random play for any given track is enabled by default, but you
    can use this screen to disable it for undesirable tracks.</p>

    <p>Below this are "raw" preferences, which allow individual
    database fields to be modified.</p>

    <p>To change an existing preference, edit its value and press its
    <span class=button>@label{prefs.set}@</span> button.</p>

    <p>To delete an existing preference, press its
    <span class=button>@label{prefs.delete}@</span> button.</p>

    <p>To add a new preference, enter its name and value in the box at the
    bottom and press the <span class=button>@label{prefs.new}@</span> button.
    If the preference exists already it will be overwritten.</p>


    <p>Preferences can have any name or value but certain names have special
    significance:</p>

    <table class=helpprefs>
     <tbody>
      <tr>
       <td class=helpprefs><span class=helppref>pick_at_random</span></td>
       <td class=helpprefs>If this preference is present and set to "0" then
       the track will not be picked for random play.  Otherwise it may be.</td>
      </tr>
      <tr>
       <td class=helpprefs><span class=helppref>trackname_<span class=helpprefbit>context</span>_<span class=helpprefbit>part</span></span></td>
       <td class=helpprefs>These preferences can be used to override the
       filename parsing rules to find a track name part.  <span
       class=helppref>trackname_<span class=helpprefbit>part</span></span> will
       be used if the full version is not present.</td>
     </tbody>
    </table>

    <p><span class=helpprefbit>context</span> can be anything but standard
    values are:</p>

    <table class=helpcontexts>
     <tbody>
      <tr>
       <td class=helpcontexts><span class=helpcontext>display</span></td>
       <td class=helpcontexts>Displayed in a web page</td>
      </tr>
      <tr>
       <td class=helpcontexts><span class=helpcontext>sort</span></td>
       <td class=helpcontexts>Used when sorting track names</td>
      </tr>
     </tbody>
    </table>

    <p><span class=helpprefbit>part</span> can be anything too but standard
    values are "artist", "album" and "title", with the obvious meanings.</p>

    <p>See also <a href="@url@?action=disorder.1">disorder(1)</a> and <a
    href="@url@?action=disorder_config.5">disorder_config(5)</a> for further
    details.</p>

   </div>

   <h2 class=sidebarlink>Search</h2>

   <div class=helpsection>

    <p>This screen allows you to search for keywords in track names.  If you
    specify more than one keyword then only tracks containing all of them are
    listed.  Results are grouped by artist, album and title.</p>

    <p>It is possible to limit results to tracks with a particular
    tag, by using <b>tag:</b><i>TAG</i> among the search terms.</p>

    <p>Some keywords, known as "stopwords", are excluded from the search, and
    will never match.  See the "stopword" option in <a
    href="@url@?action=disorder_config.5">disorder_config(5)</a> for further
    details about this.</p>

   </div>

  @if{@eq{@label:menu@}{sidebar}@}
     {

   <h2 class=sidebarlink>Volume</h2>

   <div class=helpsection>

    <p>This screen allows you to set the playback volume, if this is enabled in
    the server configuration.  See the "channel" and "mixer" options in <a
    href="@url@?action=disorder_config.5">disorder_config(5)</a> for further
    details about this.</p>

   </div>

     }{<!-- volume currently only linked in sidebar menu -->}@ 

  <h2 class=sidebarlink>Troubleshooting</h2>

  <div class=helpsection>

   <p>If you cannot play a track, or it does not appear in the
   database even after a rescan, check the following things:</p>

   <ul>

    <li>Are there any error messages in the system log?  The server
    logs to <tt>LOG_DAEMON</tt>, which typically ends up in
    <i>/var/log/daemon.log</i> or <i>/var/log/messages</i>, though
    this depends on local configuration.

    <li>Is the track in a known format?  Have a look at the
    configuration file for the formats recognized by the local
    installation.  The filename matching is case-sensitive.

    <li>Do permissions on the track allow the server to read it?
     
    <li>Do the permissions on the containing directories allow the
    server to read and execute them?

   </ul>

   <p>The user the server runs as is determined by the <tt>user</tt>
   directive in the configuration file.  The README recommends using
   <b>jukebox</b> for this purpose but it could be different
   locally.</p>

  </div>

   <h2 class=sidebarlink>Man Pages</h2>

   <div class=helpsection>

    <p><a href="@url@?action=disorder_config.5">disorder_config(5)</a> -
     configuration</p>

    <p><a href="@url@?action=disorder.1">disorder(1)</a> - command line
     client</p>

    <p><a href="@url@?action=disobedience.1">disobedience(1)</a> - GTK+
     client</p>

    <p><a href="@url@?action=tkdisorder.1">tkdisorder(1)</a> - GUI
     client</p>

    <p><a href="@url@?action=disorderd.8">disorderd(8)</a> - server</p>

    <p><a href="@url@?action=disorder-dump.8">disorder-dump(8)</a> -
     dump/restore preferences database</p>

    <p><a href="@url@?action=disorder.3">disorder(3)</a> - C API</p>

    <p><a href="@url@?action=disorder_protocol.5">disorder_protocol(5)</a> -
     DisOrder control protocol</p>

   </div>

@include{@label{menu}@end}@
  </div>
 </body>
</html>
@@
<!--
Local variables:
mode:sgml
sgml-always-quote-attributes:nil
sgml-indent-step:1
sgml-indent-data:t
End:
-->
Commit	Line	Data
460b9539	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&nonce=@nonce@">choose</a>, which give
164	you all the top-level directories at once, and <a
165	href="@url@?action=choosealpha&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	-->