Convert para_recv to lopsub.

[paraslash.git] / web / manual.md

diff --git a/web/manual.md b/web/manual.md
index 3b9c270973b7419b82c7587be912817608c5ddd5..f8d35e548791f2ab3325fc71336f075edd13095f 100644 (file)
--- a/web/manual.md
+++ b/web/manual.md
@@ -187,7 +187,7 @@ Requirements
 
        git clone git://git.tuebingen.mpg.de/osl
        cd osl && make && sudo make install && sudo ldconfig
 
        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 realpath \
               libasound2-dev libao-dev libreadline-dev libncurses-dev \
               libmad0-dev libid3tag0-dev libasound2-dev libvorbis-dev \
               libfaad-dev libspeex-dev libFLAC-dev libsamplerate-dev realpath \
               libasound2-dev libao-dev libreadline-dev libncurses-dev \


@@ -203,6 +203,13 @@ code repository, execute
 
                git clone git://git.tuebingen.mpg.de/osl
 
 
                git clone git://git.tuebingen.mpg.de/osl
 

+- [lopsub](http://people.tuebingen.mpg.de/maan/lopsub/). The long
+option parser for subcommands generates the command line and config
+file parsers for all paraslash executables. Clone the source code
+repository with
+
+               git clone git://git.tuebingen.mpg.de/lopsub
+

 - [gcc](ftp://ftp.gnu.org/pub/gnu/gcc) or
 [clang](http://clang.llvm.org). All gcc versions >= 4.2 are currently
 supported. Clang version 1.1 or newer should work as well.
 - [gcc](ftp://ftp.gnu.org/pub/gnu/gcc) or
 [clang](http://clang.llvm.org). All gcc versions >= 4.2 are currently
 supported. Clang version 1.1 or newer should work as well.


@@ -221,6 +228,9 @@ executables.
 - [help2man](ftp://ftp.gnu.org/pub/gnu/help2man) is used to create
 the man pages.
 
 - [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
 Optional:
 
 - [openssl](http://www.openssl.org/) or


@@ -751,8 +761,8 @@ these commands.
 
 The image, lyrics, moods and playlists tables are all blob tables.
 Blob tables consist of three columns each: The identifier which is
 
 The image, lyrics, moods and playlists tables are all blob tables.
 Blob tables consist of three columns each: The identifier which is

-a positive non-negative number that is auto-incremented, the name
-(an arbitrary string) and the content (the blob).
+a positive number that is auto-incremented, the name (an arbitrary
+string) and the content (the blob).

 
 All blob tables support the same set of actions: cat, ls, mv, rm
 and add. Of course, _add_ is used for adding new blobs to the table
 
 All blob tables support the same set of actions: cat, ls, mv, rm
 and add. Of course, _add_ is used for adding new blobs to the table


@@ -776,21 +786,19 @@ or playlist is activated with the select command.
 
 ### The score table ###
 
 
 ### 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
 -------------------
 
 Playlists and moods
 -------------------


@@ -1812,6 +1820,33 @@ Examples
 Development
 ===========
 
 Development
 ===========
 

+Contributing
+------------
+
+Paraslash is an open source project and contributions are
+welcome. Here's a list of things you can do to help the project:
+
+- Report problems with building, installing or running the software.
+  In particular, test the experimental git branches ("next" and "pu").
+  This helps to identify and fix problems before the code gets merged
+  and thus keeps the master branch as stable as possible.
+- Proofread the documentation (manual, web pages, man pages, source
+  code documentation) and point out unclear or poorly written parts. If
+  you are a native English speaker you will easily find a lot of text
+  that could be improved.
+- Run analysis tools (coverity, afl, sparse, etc.) and report issues
+  found by those tools.
+- Suggest new features you would like to see implemented.
+- Compile and test on your favorite architecture or operating
+  system. The code is tested only on a limited set of systems, so you
+  will probably encounter problems when building on different systems.
+- Post about about paraslash on your blog or on social networks.
+- Build and maintain Debian/RPM packages for your favorite distribution.
+
+Note that there is no mailing list, no bug tracker and no discussion
+forum for paraslash. If you'd like to contribute, or have questions
+about contributing, send email to Andre Noll <maan@tuebingen.mpg.de>.
+

 Tools
 -----
 
 Tools
 -----
 


@@ -1825,9 +1860,6 @@ developer machine.
 paraslash development. It is necessary for cloning the git repository
 and for getting updates.
 
 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.
 - [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.


@@ -1936,7 +1968,7 @@ Coding Style
 
 The preferred coding style for paraslash coincides more or less
 with the style of the Linux kernel. So rather than repeating what is
 
 The preferred coding style for paraslash coincides more or less
 with the style of the Linux kernel. So rather than repeating what is

-written [there](http://www.kernel.org/doc/Documentation/CodingStyle),
+written [there](http://www.kernel.org/doc/Documentation/process/coding-style.rst),

 here are the most important points.
 
 - Burn the GNU coding standards.
 here are the most important points.
 
 - Burn the GNU coding standards.