chiark - git - mdw - disorder/blob - templates/help.tmpl

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
   2 <!--
   3 This file is part of DisOrder.
   4 Copyright (C) 2004-2008 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 @stdhead{help}
  24  </head>
  25  <body>
  26 @stdmenu{help}
  27    <h1>@label{help.title}</h1>
  28
  29    <h2 class=sectiontitle>Introduction</h2>
  30
  31    <div class=section>
  32
  33      <p>All screens in the DisOrder web interface have a set of
  34      hyperlinks at the top.  You can use these to visit the various
  35      screens described below.  Note that if you are not logged in some
  36      of these will be greyed out.  The link for the currently active
  37      screen is highlighted.</p>
  38
  39    </div>
  40
  41    <h2 class=sectiontitle><a name=playing>Playing</a></h2>
  42
  43    <div class=section>
  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 src="@image{remove}"
  51     title="@label{playing.remove}" alt="@label{playing.remove}">
  52     button next to it.  For the currently playing track this can be
  53     used to stop playing the track before it has finished; this is
  54     called &ldquo;scratching&rdquo;.  For a track in the queue it
  55     removes the track from the queue.</p>
  56
  57     <p>If you are not logged in, or if your user has limited rights,
  58     you may only be able to scratch or remove certain tracks (for
  59     instance, those you picked yourself).</p>
  60
  61     <p>Artist and album names are hyperlinks to the relevant locations
  62     in the <a href="#choose">Choose</a> screen (see below).</p>
  63
  64    </div>
  65
  66    <h2 class=sectiontitle><a name=manage>Manage</a></h2>
  67
  68    <div class=section>
  69
  70     <p>This screen is almost identical to <a
  71     href="#playing">Playing</a> except that it includes extra
  72     management features.</p>
  73
  74    <p>At the top of the screen are the following controls:</p>
  75
  76    <ul>
  77     <li>Pause.  This button can be used to pause playing (provided the
  78     player supports it).  <img width=@width height=@height class=imgbutton
  79     src="@image{enabled}"> indicates that playing is paused,
  80     <img width=@width height=@height class=imgbutton
  81     src="@image{disabled}"> that it is not.</li>
  82
  83     <li>Enable/disable random play.  If disabled then queued tracks
  84     will still be played but if the queue is empty nothing will be
  85     picked at random.  <img width=@width height=@height class=imgbutton
  86     src="@image{enabled}"> indicates that random play is
  87     enabled, <img width=@width height=@height class=imgbutton
  88     src="@image{disabled}"> that it is disabled.</li>
  89
  90     <li>Enable/disable play.  If disabled then tracks in the queue
  91     will not be played, but will remain in the queue instead.  <img
  92     width=@width height=@height class=imgbutton src="@image{enabled}">
  93     indicates that play is enabled, <img width=@width height=@height
  94     class=imgbutton src="@image{disabled}"> that it is
  95     disabled.</li>
  96
  97     <li>Volume control.  You can use the <img class=button
  98        src="@image{up}"
  99        title="@label{volume.up}"
 100        alt="@label{volume.up}"> and <img
 101        src="@image{down}"
 102        title="@label{volume.down}"
 103        alt="@label{volume.down}"> buttons to increase or
 104     decrease the volume, or enter new volume settings for the left
 105     and/or right speakers.</li>
 106
 107    </ul>
 108
 109    <p>Below this is the same table of current and queued tracks as for
 110     the main playing screen, but with extra buttons for managing the
 111     queue.
 112     The <img class=button src="@image{up}"
 113      title="@label{playing.up}" alt="@label{playing.up}"> and <img
 114      src="@image{down}" title="@label{playing.down}"
 115      alt="@label{playing.down}"> buttons on each track move that
 116     track around in the queue.  Similarly the <img class=button
 117      src="@image{upall}" title="@label{playing.upall}"
 118      alt="@label{playing.upall}"> and <img
 119      src="@image{downall}" title="@label{playing.downall}"
 120      alt="@label{playing.downall}"> buttons move each track to the head or
 121     tail of the queue.</p>
 122
 123     <p>If you are not logged in, or if your user has limited rights,
 124     you may only be able to move certain tracks (for instance, those
 125     you picked yourself), and may not be able to adjust the volume,
 126     random play setting, etc.</p>
 127
 128    </div>
 129
 130    <h2 class=sectiontitle><a name=recent>Recent</a></h2>
 131
 132    <div class=section>
 133
 134     <p>This screen displays recently played tracks, most recent first.
 135     The <img class=button src="@image{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 <span class=configuration>history</span>
 142     option in <a
 143     href="@url?action=disorder_config.5">disorder_config(5)</a> for
 144     more details.</p>
 145
 146    </div>
 147
 148    <h2 class=sectiontitle><a name=new>New</a></h2>
 149
 150    <div class=section>
 151
 152     <p>This screen displays tracks recently added to the database,
 153     most recent first.  The <img class=button
 154     src="@image{edit}" title="@label{choose.prefs}"
 155     alt="@label{choose.prefs}"> button can be used to edit the details
 156     for a track; see <a href="#prefs">Editing Preferences</a> below,
 157     and clicking on the track title will add it to the queue.</p>
 158
 159     <p>The time tracks are remembered for is controlled by the server
 160     configuration.  See the <span
 161     class=configuration>noticed_history</span> option in <a
 162     href="@url?action=disorder_config.5">disorder_config(5)</a> for
 163     more details.</p>
 164
 165    </div>
 166
 167    <h2 class=sectiontitle><a name=choose>Choose</a></h2>
 168
 169    <div class=section>
 170
 171     <p>This screen allows you to choose a track to be played, by navigating
 172      through the directory structure of the tracks filesystem.
 173
 174   @if{@eq{@label{menu.choosewhich}}{choosealpha}}
 175      {
 176
 177      <p>At the top of the page is a list of first letters.  Click on
 178      any of these takes you to a list of directories starting with
 179      that letter.</p>
 180
 181      <p>Below this is a search form.  You can enter one or more
 182      keywords here and select @label{search.search} and get a list of
 183      tracks containing all those keywords.  It is possible to limit
 184      search results to tracks with a particular tag, by using
 185      <b>tag:</b><i>TAG</i> among the search terms.  Select
 186      @label{search.clear} to clear the search results.</p>
 187
 188      <p>Initially the rest of the page is empty.  However when you
 189      have selected an initial letter, you will see a list of the
 190      matching directories and files.  Select a directory to enter it,
 191      or a file to play it.
 192
 193      }
 194      {
 195
 196      <p>At the top of the page is a search form.  You can enter one or
 197      more keywords here and select @label{search.search} and get a
 198      list of tracks containing all those keywords.  It is possible to
 199      limit search results to tracks with a particular tag, by using
 200      <b>tag:</b><i>TAG</i> among the search terms.</p>
 201
 202      <p>Below this appears a list of top-level files and directories.
 203      Select a directory to enter it, or a file to play it.</p>
 204
 205      }
 206
 207      <p>The following icons will also appear:</p>
 208
 209     <table class=helpbuttons>
 210      <tbody>
 211       <tr>
 212        <td><img
 213        class=button src="@image{edit}"
 214        title="@label{choose.prefs}"
 215        alt="@label{choose.prefs}"></td>
 216        <td>This button can be used to edit the details for a
 217        track; see <a href="#prefs">Editing Preferences</a> below.</td>
 218       </tr>
 219       <tr>
 220        <td><span class=button>@label{choose.playall}</span></td>
 221        <td>This button plays all the tracks in a directory,
 222        in order.  This is used to efficiently play a whole album.</td>
 223       </tr>
 224      </tbody>
 225     </table>
 226
 227     <p>NB.  Some keywords, known as &ldquo;stopwords&rdquo;, are
 228     excluded from the search, and will never match.  See the <span
 229     class=configuration>stopword</span> option in <a
 230     href="@url?action=disorder_config.5">disorder_config(5)</a> for
 231     further details about this.</p>
 232
 233     <p>This screen will may not be available if you are not logged in
 234     or if your user has limited rights.</p>
 235
 236    </div>
 237
 238    <h2 class=sectiontitle><a name=prefs>Editing Preferences</a></h2>
 239
 240    <div class=section>
 241
 242     <p>This screen, reached from <a href="#choose">Choose</a> or <a
 243     href="#recent">Recent</a>, is used to edit a track's preferences.
 244     Note that if you are not logged in, or your user has limited
 245     rights, you may not be able to edit track preferences.</p>
 246
 247     <p>The form can be used to
 248     edit artist, album and title fields for the track as displayed; or
 249     to set the tags or weight for a track; or to enable or disable random play
 250     for the track.</p>
 251
 252     <p>Tags are separated by commas and can contain any other printing
 253     characters (including spaces).  Leading and trailing spaces are
 254     not significant.</p>
 255
 256     <p>Weights determine how likely a track is to be picked at
 257     random.  Tracks with higher weights are more likely to be picked.
 258     The default weight is 90000 and the maximum is 2147483647.</p>
 259
 260     <p>By default, any track can be picked for random play.  The check
 261     box at the bottom can be used to selectivel enable or disable it
 262     for individual tracks.</p>
 263
 264    </div>
 265
 266   <h2 class=sectiontitle><a name=Login>Login</a></h2>
 267
 268   <div class=section>
 269
 270    <p>This screen has two different versions.</p>
 271
 272    <p><b>1</b>. When no user is logged in, it has a login form and a
 273    registration form.  If you do not have a username and password,
 274    fill in and submit the registration form.  You will be emailed an
 275    email with a confirmation URL that you must visit.  Only after
 276    visiting this URL will your login become active.</p>
 277
 278    <p>Once you have a username and password, you can use the login
 279    form to authenticate yourself to the web interface.  Note that this
 280    is your primary DisOrder password, which (in old installations) may
 281    differ from your original web password.</p>
 282
 283    <p><b>2</b>. When you are logged in, this screen instead has a form
 284    to change your email address or password, and a logout button.</p>
 285
 286   </div>
 287
 288   <h2 class=sectiontitle>Troubleshooting</h2>
 289
 290   <div class=section>
 291
 292    <p>If you cannot play a track, or it does not appear in the
 293    database even after a rescan, check the following things:</p>
 294
 295    <ul>
 296
 297     <li>Are there any error messages in the system log?  The server
 298     logs to <span class=configuration>LOG_DAEMON</span>, which
 299     typically ends up in <i>/var/log/daemon.log</i> or
 300     <i>/var/log/messages</i>, though this depends on local
 301     configuration.
 302
 303     <li>Is the track in a known format?  Out of the box, OGG, MP3,
 304      FLAC and WAV are supported.  You can look at the configuration
 305      file for additional formats recognized by the local installation.
 306
 307     <li>Do permissions on the track allow the server to read it?  If
 308     the server cannot read it then it will not be able to play it.
 309
 310     <li>Do the permissions on the containing directories allow the
 311     server to read and execute them?
 312
 313    </ul>
 314
 315    <p>The user the server runs as is determined by the <span
 316    class=configuration>user</span> directive in the configuration
 317    file.  The README recommends using <b>jukebox</b> for this purpose
 318    but it could be different locally.</p>
 319
 320   </div>
 321
 322    <h2 class=sectiontitle>Man Pages</h2>
 323
 324    <div class=section>
 325
 326     <p><a href="@url?action=disorder_config.5">disorder_config(5)</a> -
 327      configuration</p>
 328
 329     <p><a href="@url?action=disorder_templates.5">disorder_templates(5)</a> -
 330      template language</p>
 331
 332     <p><a href="@url?action=disorder.1">disorder(1)</a> - command line
 333      client</p>
 334
 335     <p><a href="@url?action=disobedience.1">disobedience(1)</a> - GTK+
 336      client</p>
 337
 338     <p><a href="@url?action=disorderd.8">disorderd(8)</a> - server</p>
 339
 340     <p><a href="@url?action=disorder-dump.8">disorder-dump(8)</a> -
 341      dump/restore preferences database</p>
 342
 343     <p><a href="@url?action=disorder.3">disorder(3)</a> - C API</p>
 344
 345     <p><a href="@url?action=disorder_protocol.5">disorder_protocol(5)</a> -
 346      DisOrder control protocol</p>
 347
 348    </div>
 349
 350 @credits
 351   </div>
 352  </body>
 353 </html>
 354 @discard{
 355 Local variables:
 356 mode:sgml
 357 sgml-always-quote-attributes:nil
 358 sgml-indent-step:1
 359 sgml-indent-data:t
 360 indent-tabs-mode:nil
 361 fill-column:79
 362 End:
 363 }@#