[disorder] / templates / help.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<!--
This file is part of DisOrder.
Copyright (C) 2004, 2005, 2006, 2007 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{topbar}@
   <h1 class=title>@label{help.title}@</h1>

   <h2 class=sidebarlink>Introduction</h2>

   <div class=helpsection>

     <p>All screens in the DisOrder web interface have a set of
     hyperlinks at the top.  You can use these to visit the various
     screens described below.  Note that if you are not logged in some
     of these will be greyed out.</p>

   </div>
  
   <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=new>New</a></h2>

   <div class=helpsection>

    <p>This screen displays tracks recently added to the database,
    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,
    and clicking on the track title will add it to the queue.</p>

    <p>The time tracks are remembered for is controlled by the server
    configuration.  See the "noticed_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.</p>
    
    <p>The form 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>

   </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>

  <h2 class=sidebarlink><a name=Login>Login</a></h2>

  <div class=helpsection>

   <p>This screen has two different versions.</p>

   <p><b>1</b>. When no user is logged in, it has a login form and a
   registration form.  If you do not have a username and password,
   fill in and submit the registration form.  You will be emailed an
   email with a confirmation URL that you must visit.  Only after
   visiting this URL will your login become active.</p>

   <p>Once you have a username and password, you can use the login
   form to authenticate yourself to the web interface.  Note that this
   is your primary DisOrder password, which (in old installations) may
   differ from your original web password.</p>

   <p><b>2</b>. When you are logged in, this screen instead has a form
   to change your email address or password, and a logout button.</p>

  </div>

  <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=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{topbarend}@
  </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.
d5b6ffd7	4	Copyright (C) 2004, 2005, 2006, 2007 Richard Kettlewell
460b9539	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>
e12da4d9	27	@include{topbar}@
460b9539	28	<h1 class=title>@label{help.title}@</h1>
460b9539	29
4a4c673c	30	<h2 class=sidebarlink>Introduction</h2>
	31
	32	<div class=helpsection>
	33
	34	<p>All screens in the DisOrder web interface have a set of
	35	hyperlinks at the top. You can use these to visit the various
	36	screens described below. Note that if you are not logged in some
	37	of these will be greyed out.</p>
	38
	39	</div>
	40
460b9539	41	<h2 class=sidebarlink><a name=playing>Playing</a></h2>
	42
	43	<div class=helpsection>
	44
	45	<p>This screen displays the currently playing track (if there is one) and
	46	lists all the tracks in the queue (the track that will be played soonest
	47	being listed first.) Where possible, estimated start times are
	48	given.</p>
	49
	50	<p>Each track has a <img class=button
	51	src="@label:images.scratch@"
	52	title="@label:playing.scratch@"
	53	alt="@label:playing.scratch@"> button next to it. For the
	54	currently playing track this can be used to stop playing the
	55	track before it has finished. For a track in the queue it
	56	removes the track from the queue.</p>
	57
	58	<p>Depending on the server configuration, you may be able to do
	59	this for any track, or only for tracks you submitted or that were
	60	randomly picked. See the "restrict" option in <a
	61	href="@url@?action=disorder_config.5">disorder_config(5)</a> for more
	62	details.</p>
	63
	64	<p>Artist and album names are hyperlinks to the relevant locations
	65	in the <a href="#choose">Choose</a> screen (see below).</p>
	66
	67	</div>
	68
	69	<h2 class=sidebarlink><a name=manage>Manage</a></h2>
	70
	71	<div class=helpsection>
	72
	73	<p>This screen is almost identical to <a
	74	href="#playing">Playing</a> except that it includes extra
	75	management features.</p>
	76
	77	<p>At the top of the screen are the following controls:</p>
	78
	79	<ul>
	80	<li>Pause. This button can be used to pause playing (provided the
	81	player supports it). <img width=16 height=16 class=imgbutton
	82	src="@label:images.enabled@"> indicates that playing is paused,
	83	<img width=16 height=16 class=imgbutton
	84	src="@label:images.disabled@"> that it is not.</li>
	85
	86	<li>Enable/disable random play. If disabled then queued tracks
	87	will still be played but if the queue is empty nothing will be
	88	picked at random. <img width=16 height=16 class=imgbutton
	89	src="@label:images.enabled@"> indicates that random play is
	90	enabled, <img width=16 height=16 class=imgbutton
	91	src="@label:images.disabled@"> that it is disabled.</li>
	92
	93	<li>Enable/disable play. If disabled then tracks in the queue
	94	will not be played, but will remain in the queue instead. <img
	95	width=16 height=16 class=imgbutton src="@label:images.enabled@">
	96	indicates that play is enabled, <img width=16 height=16
	97	class=imgbutton src="@label:images.disabled@"> that it is
	98	disabled.</li>
	99
	100	<li>Volume control. You can use the <img class=button
	101	src="@label:images.up@"
	102	title="@label:volume.increase@"
	103	alt="@label:volume.increase@"> and <img
	104	src="@label:images.down@"
105	title="@label:volume.reduce@"
106	alt="@label:volume.reduce@"> buttons to increase or
107	decrease the volume, or enter new volume settings for the left
108	and/or right speakers.</li>
109
110	</ul>
111
112	<p>Below this is the same table of current and queued tracks as for
113	the main playing screen, but with extra buttons for managing the
114	queue.
115	The <img class=button src="@label:images.up@"
116	title="@label:playing.up@" alt="@label:playing.up@"> and <img
117	src="@label:images.down@" title="@label:playing.down@"
118	alt="@label:playing.down@"> buttons on each track move that
119	track around in the queue. Similarly the <img class=button
120	src="@label:images.upall@" title="@label:playing.upall@"
121	alt="@label:playing.upall@"> and <img
122	src="@label:images.downall@" title="@label:playing.downall@"
123	alt="@label:playing.downall@"> buttons move each track to the head or
124	tail of the queue.
125	Depending on server configuration, it may be that only trusted
126	users can move tracks around the queue.</p>
127
128	</div>
129
130	<h2 class=sidebarlink><a name=recent>Recent</a></h2>
131
132	<div class=helpsection>
133
134	<p>This screen displays recently played tracks, most recent first.
135	The <img class=button src="@label:images.edit@"
136	title="@label:choose.prefs@" alt="@label:choose.prefs@">
137	button can be used to edit the details for a track; see <a
138	href="#prefs">Editing Preferences</a> below.</p>
139
140	<p>The number of tracks remembered is controlled by the server
141	configuration. See the "history" option in <a
142	href="@url@?action=disorder_config.5">disorder_config(5)</a> for more
143	details.</p>
144
145	</div>
146
78efa64e RK	147	<h2 class=sidebarlink><a name=new>New</a></h2>
	148
	149	<div class=helpsection>
	150
	151	<p>This screen displays tracks recently added to the database,
	152	most recent first. The <img class=button
	153	src="@label:images.edit@" title="@label:choose.prefs@"
	154	alt="@label:choose.prefs@"> button can be used to edit the details
	155	for a track; see <a href="#prefs">Editing Preferences</a> below,
	156	and clicking on the track title will add it to the queue.</p>
	157
	158	<p>The time tracks are remembered for is controlled by the server
	159	configuration. See the "noticed_history" option in <a
	160	href="@url@?action=disorder_config.5">disorder_config(5)</a> for
	161	more details.</p>
	162
	163	</div>
	164
460b9539	165	<h2 class=sidebarlink><a name=choose>Choose</a></h2>
	166
	167	<div class=helpsection>
	168
	169	<p>This screen allows you to choose a track to be played, by navigating
	170	through the directory structure of the tracks filesystem. The following
	171	buttons appear:</p>
	172
	173	<table class=helpbuttons>
	174	<tbody>
	175	<tr>
	176	<td class=helpbuttons><img
	177	class=button src="@label:images.edit@"
	178	title="@label:choose.prefs@"
	179	alt="@label:choose.prefs@"></td>
	180	<td class=helpbuttons>This button can be used to edit the details for a
	181	track; see <a href="#prefs">Editing Preferences</a> below.</td>
	182	</tr>
	183	<tr>
	184	<td class=helpbuttons><span class=button>@label{choose.playall}@</span></td>
	185	<td class=helpbuttons>This button plays all the tracks in a directory,
	186	in order. This is used to efficiently play a whole album.</td>
	187	</tr>
	188	</tbody>
	189	</table>
	190
	191	<p>This screen has two forms: <a
	192	href="@url@?action=choose&nonce=@nonce@">choose</a>, which give
	193	you all the top-level directories at once, and <a
	194	href="@url@?action=choosealpha&nonce=@nonce@">choosealpha</a>,
	195	which breaks them down by initial letter.</p>
	196
	197	</div>
	198
	199	<h2 class=sidebarlink><a name=prefs>Editing Preferences</a></h2>
	200
	201	<div class=helpsection>
	202
	203	<p>This screen, reached from <a href="#choose">Choose</a> or <a
4a4c673c	204	href="#recent">Recent</a>, is used to edit a track's preferences.</p>
460b9539	205
4a4c673c	206	<p>The form can be used to
460b9539	207	edit artist, album and title fields for the track as displayed, or
	208	to set the tags for a track, or to enable or disable random play
	209	for the track.</p>
	210
	211	<p>Tags are separated by commas and can contain any other printing
	212	characters (including spaces). Leading and trailing spaces are
	213	not significant.</p>
	214
	215	<p>Random play for any given track is enabled by default, but you
	216	can use this screen to disable it for undesirable tracks.</p>
	217
460b9539	218	</div>
	219
	220	<h2 class=sidebarlink>Search</h2>
	221
	222	<div class=helpsection>
	223
	224	<p>This screen allows you to search for keywords in track names. If you
	225	specify more than one keyword then only tracks containing all of them are
	226	listed. Results are grouped by artist, album and title.</p>
	227
	228	<p>It is possible to limit results to tracks with a particular
	229	tag, by using <b>tag:</b><i>TAG</i> among the search terms.</p>
	230
	231	<p>Some keywords, known as "stopwords", are excluded from the search, and
	232	will never match. See the "stopword" option in <a
	233	href="@url@?action=disorder_config.5">disorder_config(5)</a> for further
	234	details about this.</p>
	235
	236	</div>
	237
4a4c673c	238	<h2 class=sidebarlink><a name=Login>Login</a></h2>
460b9539	239
4a4c673c	240	<div class=helpsection>
460b9539	241
4a4c673c	242	<p>This screen has two different versions.</p>
460b9539	243
4a4c673c	244	<p><b>1</b>. When no user is logged in, it has a login form and a
	245	registration form. If you do not have a username and password,
	246	fill in and submit the registration form. You will be emailed an
	247	email with a confirmation URL that you must visit. Only after
	248	visiting this URL will your login become active.</p>
460b9539	249
4a4c673c	250	<p>Once you have a username and password, you can use the login
	251	form to authenticate yourself to the web interface. Note that this
	252	is your primary DisOrder password, which (in old installations) may
	253	differ from your original web password.</p>
	254
	255	<p><b>2</b>. When you are logged in, this screen instead has a form
	256	to change your email address or password, and a logout button.</p>
460b9539	257
4a4c673c	258	</div>
460b9539	259
	260	<h2 class=sidebarlink>Troubleshooting</h2>
	261
	262	<div class=helpsection>
	263
	264	<p>If you cannot play a track, or it does not appear in the
	265	database even after a rescan, check the following things:</p>
	266
	267	<ul>
	268
	269	<li>Are there any error messages in the system log? The server
	270	logs to <tt>LOG_DAEMON</tt>, which typically ends up in
	271	<i>/var/log/daemon.log</i> or <i>/var/log/messages</i>, though
	272	this depends on local configuration.
	273
	274	<li>Is the track in a known format? Have a look at the
	275	configuration file for the formats recognized by the local
	276	installation. The filename matching is case-sensitive.
	277
	278	<li>Do permissions on the track allow the server to read it?
	279
	280	<li>Do the permissions on the containing directories allow the
	281	server to read and execute them?
	282
	283	</ul>
	284
	285	<p>The user the server runs as is determined by the <tt>user</tt>
	286	directive in the configuration file. The README recommends using
	287	<b>jukebox</b> for this purpose but it could be different
	288	locally.</p>
	289
	290	</div>
	291
	292	<h2 class=sidebarlink>Man Pages</h2>
	293
	294	<div class=helpsection>
	295
	296	<p><a href="@url@?action=disorder_config.5">disorder_config(5)</a> -
	297	configuration</p>
	298
	299	<p><a href="@url@?action=disorder.1">disorder(1)</a> - command line
	300	client</p>
	301
	302	<p><a href="@url@?action=disobedience.1">disobedience(1)</a> - GTK+
	303	client</p>
	304
460b9539	305	<p><a href="@url@?action=disorderd.8">disorderd(8)</a> - server</p>
	306
	307	<p><a href="@url@?action=disorder-dump.8">disorder-dump(8)</a> -
	308	dump/restore preferences database</p>
	309
	310	<p><a href="@url@?action=disorder.3">disorder(3)</a> - C API</p>
	311
	312	<p><a href="@url@?action=disorder_protocol.5">disorder_protocol(5)</a> -
	313	DisOrder control protocol</p>
	314
	315	</div>
	316
e12da4d9	317	@include{topbarend}@
460b9539	318	</div>
	319	</body>
	320	</html>
	321	@@
	322	<!--
	323	Local variables:
	324	mode:sgml
	325	sgml-always-quote-attributes:nil
	326	sgml-indent-step:1
	327	sgml-indent-data:t
	328	End:
	329	-->