manual: Rewrite section on score table.

[paraslash.git] / web / manual.md

diff --git a/web/manual.md b/web/manual.md
index 7d2c4cf3105ed47ccac28effbb3295c7240eb6bc..b154b3919091ff6a897a45f0f333fba1be4875bc 100644 (file)
--- a/web/manual.md
+++ b/web/manual.md
@@ -187,9 +187,9 @@ Requirements
 
        git clone git://git.tuebingen.mpg.de/osl
        cd osl && make && sudo make install && sudo ldconfig
-       sudo apt-get install autoconf libssl-dev help2man gengetopt \
+       sudo apt-get install autoconf libssl-dev help2man gengetopt m4 \
               libmad0-dev libid3tag0-dev libasound2-dev libvorbis-dev \
-              libfaad-dev libspeex-dev libFLAC-dev libsamplerate-dev \
+              libfaad-dev libspeex-dev libFLAC-dev libsamplerate-dev realpath \
               libasound2-dev libao-dev libreadline-dev libncurses-dev \
               libopus-dev
 
@@ -204,7 +204,7 @@ code repository, execute
                git clone git://git.tuebingen.mpg.de/osl
 
 - [gcc](ftp://ftp.gnu.org/pub/gnu/gcc) or
-[clang](http://clang.llvm.org). All gcc versions >= 3.3 are currently
+[clang](http://clang.llvm.org). All gcc versions >= 4.2 are currently
 supported. Clang version 1.1 or newer should work as well.
 
 - [gnu make](ftp://ftp.gnu.org/pub/gnu/make) is also shipped with the
@@ -221,6 +221,9 @@ executables.
 - [help2man](ftp://ftp.gnu.org/pub/gnu/help2man) is used to create
 the man pages.
 
+- [m4](ftp://ftp.gnu.org/pub/gnu/m4/). Some source files are generated
+from templates by the m4 macro processor.
+
 Optional:
 
 - [openssl](http://www.openssl.org/) or
@@ -776,21 +779,19 @@ or playlist is activated with the select command.
 
 ### The score table ###
 
-Unlike all other tables the contents of the score table remain in
-memory and are never stored on disk. The score table contains two
-columns: The SHA1 hash value (of an audio file) and its current
-score.
-
-However, only those files which are admissible for the current mood
-or playlist are contained in the score table. The audio file selector
-always chooses the row with the highest score as the file to stream
-next. While doing so, it computes the new score and updates the
-last_played and the num_played fields in the audio file table.
+The score table describes those audio files which are admissible for
+the current mood or playlist (see below). The table has two columns:
+a pointer to a row of the audio file table and a score value.
 
-The score table is recomputed by the select command which loads a
-mood or playlist. Audio files are chosen for streaming from the rows
-of the score table on a highest-score-first basis.
+Unlike all other tables of the database, the score table remains in
+memory and is never stored on disk. It is initialized at startup and
+recomputed when the select command loads a new mood or playlist.
 
+When the audio file selector is asked to open the next audio file,
+it picks the row with the highest score, opens the corresponding
+file and passes the file descriptor to the virtual streaming system.
+At this point the last_played and the num_played fields of the selected
+file are updated and the score is recomputed.
 
 Playlists and moods
 -------------------
@@ -926,12 +927,13 @@ is not set, the empty string is matched against the pattern.
        frequency ~ <num>
        channels ~ <num>
        num_played ~ <num>
+       image_id ~ <num>
+       lyrics_id ~ <num>
 
 Takes a comparator ~ of the set {<, =, <=, >, >=, !=} and a number
 <num>. Matches an audio file iff the condition <val> ~ <num> is
 satisfied where val is the corresponding value of the audio file
-(value of the year tag, bitrate in kbit/s, frequency in Hz, channel
-count, play count).
+(value of the year tag, bitrate in kbit/s, etc.).
 
 The year tag is special as its value is undefined if the audio file
 has no year tag or the content of the year tag is not a number. Such
@@ -1824,9 +1826,6 @@ developer machine.
 paraslash development. It is necessary for cloning the git repository
 and for getting updates.
 
-- [m4](ftp://ftp.gnu.org/pub/gnu/m4/). Some input files for gengetopt
-are generated from templates by the m4 macro processor.
-
 - [autoconf](ftp://ftp.gnu.org/pub/gnu/autoconf/) GNU autoconf creates
 the configure file which is shipped in the tarballs but has to be
 generated when compiling from git.
@@ -2198,7 +2197,6 @@ Application web pages
 ---------------------
 
 - [paraslash](http://people.tuebingen.mpg.de/maan/paraslash/)
-- [alternative page](http://paraslash.systemlinux.org/)
 - [xmms](http://xmms2.org/wiki/Main_Page)
 - [mpg123](http://www.mpg123.de/)
 - [gstreamer](http://gstreamer.freedesktop.org/)