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