Documentation update and re-ordering.
authorAndre Noll <maan@systemlinux.org>
Thu, 25 Oct 2007 17:25:32 +0000 (19:25 +0200)
committerAndre Noll <maan@systemlinux.org>
Thu, 25 Oct 2007 17:25:32 +0000 (19:25 +0200)
INSTALL
Makefile.in
NEWS
README
README.afs [new file with mode: 0644]
REQUIREMENTS [new file with mode: 0644]

diff --git a/INSTALL b/INSTALL
index 236e66d..f593f70 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -88,7 +88,7 @@ Finally, tell para_client to connect to server_host:
 Start para_server
 -----------------
 
-For this first try, we'll use a debug level of one to make the
+For this first try, we'll use a debug level of two to make the
 output of para_server more verbose.
 
        para_server -l 2
@@ -125,8 +125,8 @@ to the audio file table:
        para_client add /my/mp3/dir
 
 This might take a while, so it is a good idea to start with a directory
-containing not too many audio. Note that the table only contains data
-about the audio files found, not the files themselves.
+containing not too many audio files. Note that the table only contains
+data about the audio files found, not the files themselves.
 
 Print a list of all audio files found with
 
@@ -236,235 +236,5 @@ arbitrary commands. There are several flavours of key-bindings:
        - para: Like display, but start "para_client <specified
          command>" instead of "<specified command>".
 
----------
-AFS usage
----------
-
-Paraslash comes with a sophisticated audio file selector called afs.
-In the example above, we only used the "dummy" mode of afs which
-gets activated automatically if nothing else was specified. In this
-section the various features of afs are described.
-
-----------
-Attributes
-~~~~~~~~~~
-
-An attribute is simply a bit which can be set for each audio
-file individually.  Up to 64  different attributes may be
-defined. For example, "pop", "rock", "blues", "jazz", "instrumental",
-"german_lyrics", "speech", whatever. It's up to you how many attributes
-you define and how you call them.
-
-A new attribute "test" is created by
-
-       para_client addatt test
-
-and
-       para_client lsatt
-
-lists all available attributes. You can set the "test" attribute for
-an audio file by executing
-
-       para_client setatt test+ /path/to/the/audio/file
-
-Similarly, the "test" bit can be removed from a audio file with
-
-       para_client setatt test- /path/to/the/audio/file
-
-Instead of a path you can also use a pattern, and the attribute is
-applied to all audio files matching that pattern:
-
-       para_client setatt test+ '/test/directory/*'
-
-The command
-
-       para_client -- ls -lv
-
-gives you a verbose listing of your audio files which contains also
-which attributes are set.
-
-In case you wonder why the double-dash in the above command is needed:
-It tells para_client to not interpret the options after the dashes. If
-you find this annoying, just say
-
-       alias para='para_client --'
-
-and be happy. In the remainder part this alias is being used.
-
-Drop the test attribute entirely from the database with
-
-       para rmatt test
-
-Read the output of
-
-       para help ls
-       para help setatt
-
-for more information and a complete list of command line options to
-these commands.
-
-
-----------------------
-Abstract mood nonsense
-~~~~~~~~~~~~~~~~~~~~~~
-
-[skip this part if you don't like formal definitions]
-
-A mood consists of a unique name and its *mood definition*, which is a set of
-*mood lines* containing expressions in terms of attributes and other data
-contained in the database.
-
-A mood defines a subset of audio files called the *admissible audio files*
-for that mood. A mood can be *active* which means that para_server
-is going to select only files from that subset of admissible files.
-
-So in order to create a mood definition one has to write a set of
-mood lines. Mood lines come in three flavours: Accept lines, deny
-lines and score lines.
-
-The general syntax of the three types of mood lines is
-
-
-       accept [with score <score>] [if] [not] <mood_method> [options]
-       deny [with score <score>] [if] [not] <mood_method> [options]
-       score <score>  [if] [not] <mood_method> [options]
-
-
-Here <score> is either an integer or the string "random" which assigns
-a random score to all matching files. The score value changes the
-order in which admissible files are going to be selected, but is of
-minor importance for this introduction.
-
-So we concentrate on the first two forms, that is accept and deny
-lines. As usual, everything in square brackets is optional, i.e.
-accept/deny lines take the following form when ignoring scores:
-
-       accept [if] [not] <mood_method> [options]
-
-and analogously for the deny case. The "if" keyword is purely cosmetic
-and has no function. The "not" keyword just inverts the result, so
-the essence of a mood line is the mood method part and the options
-following thereafter.
-
-A *mood method* is realized as function which takes an audio file
-and computes a number from the data contained in the database.
-If this number is non-negative, we say the file *matches* the mood
-method. The file matches the full mood line if it either
-
-       - matches the mood method and the "not" keyword is not given,
-or
-       - does not match the mood method, but the "not" keyword is given.
-
-The set of admissible files for the whole mood is now defined as those
-files which match at least one accept mood line, but no deny mood line.
-More formally, a file is admissible if and only if
-
-       (F ~ AL1 or F ~ AL2...) and not (F ~ DL1 or F ~ DN2 ...)
-
-where F is the file, AL1, AL2... are the accept lines, DL1, DL2... are
-the deny lines and "~" means "matches".
-
-The cases where no mood lines of accept/deny type are defined need
-special treatment:
-
-       - Neither accept nor deny lines: This treats all files as admissible
-         (in fact, that is the definition of the dummy mood which is activated
-         automatically if no moods are available).
-
-       - Only accept lines: A file is admissible iff it matches at least one
-         accept line:
-
-               F ~ AL1 or F ~ AL2 or ...
-
-       - Only deny lines: A file is admissible iff it matches no deny line:
-
-               not (F ~ DL1 or F ~ DN2 ...)
-
-
-
---------------------
-List of mood_methods
-~~~~~~~~~~~~~~~~~~~~
-
-       no_attributes_set()
-
-Takes no arguments and matches an audio file if and only if no
-attributes are set.
-
-       played_rarely()
-
-Takes no arguments and matches all audio files where the number of
-times this audio file was selected is below the average.
-
-       is_set(attribute_name)
-
-Takes the name of an attribute and matches iff that attribute is set.
-
-       name_like(pattern)
-
-Takes a filename pattern and matches iff the path of the audio file
-matches the pattern.
-
-
-----------
-Mood usage
-~~~~~~~~~~
-
-To create a new mood called "my_mood", write its definition into
-some temporary file, say "tmpfile", and add it to the mood table
-by executing
-
-       para addmood my_mood < tmpfile
-
-If the mood definition is really short, you may just pipe it to the
-client instead of using temporary files. Like this:
-
-       echo "$MOOD_DEFINITION" | para addmood my_mood
-
-There is no need to keep the temporary file since you can always use
-the catmood command to get it back:
-
-       para catmood my_mood
-
-A mood can be activated by executing
-
-       para chmood my_mood
-
-Once active, the list of admissible files is shown by the ls command
-if the "-a" switch is given:
-
-       para ls -a
-
------------------------
-Example mood definition
-~~~~~~~~~~~~~~~~~~~~~~~
-
-Suppose you have defined attributes "punk" and "rock" and want to define
-a mood containing only Punk-Rock songs. That is, an audio file should be
-admissible if and only if both attributes are set. Since
-
-       punk and rock
-
-is obviously the same as
-
-       not (not punk or not rock)
-
-(de Morgan's rule), a mood definition that selects only Punk-Rock
-songs is
-
-       deny if not is_set punk
-       deny if not is_set rock
-
-
----------
-Troubles?
----------
-If something went wrong, look at the output. If that does not give
-you a clue, use loglevel one (option -l 1 for most commands) to show
-debugging info. Almost all paraslash executables have a brief online
-help which is displayed by using the -h switch.
-
-Still not working? Mail the author Andre Noll <maan@systemlinux.org>
-(english, german, or spanish language). Please provide enough info
-such as the version of paraslash you are using and relevant parts of
-the logs.
+This concludes the installation notes. Next thing you might to have a look
+at is how to use paraslash's audio file selector. See README.afs.
index 0bdd71f..bbef37d 100644 (file)
@@ -57,7 +57,7 @@ man_pages_html := $(patsubst %, man/html/%.html, $(man_binaries))
 gengetopts := $(wildcard *.ggo)
 gengetopts_c := $(gengetopts:.ggo=.cmdline.c)
 gengetopts_h := $(gengetopts:.ggo=.cmdline.h)
-grutatxt := NEWS CREDITS INSTALL README FEATURES
+grutatxt := NEWS CREDITS INSTALL README FEATURES REQUIREMENTS README.afs
 grutatxt_html := $(grutatxt:=.html)
 html_in := $(wildcard web/*.in.html)
 gen_html := $(subst web/,web/sync/,$(html_in))
@@ -75,7 +75,7 @@ web_misc := $(patsubst %,web/sync/%,$(web_misc))
 web_man := web/sync/man
 autocrap := config.h.in configure
 tarball_pfx := @PACKAGE_TARNAME@-@PACKAGE_VERSION@
-tarball_delete = web versions pics .changelog_before_cvs .changelog_cvs
+tarball_delete = web versions pics .changelog_before_cvs .changelog_cvs .gitignore
 tarball_delete := $(patsubst %,$(tarball_pfx)/%,$(tarball_delete))
 tarball_add := $(gengetopts_c) $(gengetopts_h) $(autocrap)
 
diff --git a/NEWS b/NEWS
index 93d82b2..2b5e3ff 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -1,6 +1,52 @@
 NEWS
 ====
 
+------------------------------------------
+0.3.0 (to be announced) "solar saturation"
+------------------------------------------
+
+paraslash.0.3.0 -- 'WWDBND --what would databases never do?'.
+
+
+Usually one might expect lots of new features AND a big increase in size
+for a major release like 0.2.x to 0.3.x.
+
+However, this release is smaller than the latest 0.2.x releases. The
+decrease in size is mostly due to the removal of some graphical tools
+(which were only afternoon hacks anyway). But also the fact that the
+mysql code is gone cuts down the size a bit.
+
+Being independent of mysql comes at a cost: The ((stripped)  binary
+size of para_server increases about 50K in i386.
+
+
+
+       - no more restrictions on unique basenames.
+
+       - independent of mysql: The new self-contained object
+         storage layer (osl) replaces the mysql database.
+
+       - Lyrics support.
+
+       - Reliable audio file move/rename detection.
+
+       - the new osl-based audio file selector (afs) replaces the random,
+         playlist and the mysql selector of paraslash-0.2.x.
+
+       - paraslash-0.2.x streams are now called "moods". Writing
+         0.3.x-mood definitions should be both easier and more
+         powerful than writing 0.2.x-stream definitions.
+
+       - para_krell, para_slider, para_para_sdl_gui, para_dbadm have
+         been removed. The world is a better place without them. However,
+         para_gui is still there.
+
+
+       - afs tracks audio file selection also in playlist mode.
+
+       - few easy-to-use afs commands replace the many not-so-easy-to-use
+         mysql commands ((and are available also in playlist mode).
+
 ----------------------------------------------
 0.2.17 (to be announced) "isotropic threshold"
 ----------------------------------------------
diff --git a/README b/README
index d4521bc..0173fb3 100644 (file)
--- a/README
+++ b/README
@@ -8,9 +8,9 @@ _Play, archive, rate and stream large audio sets happily_
 
 It contains the following programs:
 
------------------------
+------------------------
 para_server (obligatory)
------------------------
+------------------------
 
 para_server streams binary audio data (mp3/oggvorbis/m4a files)
 over local and/or remote networks. It listens on a tcp port and
@@ -33,7 +33,9 @@ It is possible to activate more than one sender simultaneously.
 The built-in audio file selector of paraslash is used to manage your
 audio files. It maintains statistics on the usage of all available audio
 files such as last played time, and the number of times each file was
-selected. Its features include
+selected.
+
+Its features include
 
        * attributes: Allow fine-grained audio file selection.
 
@@ -43,7 +45,7 @@ selected. Its features include
 
        * playlist table. Stores arbitrary many playlists.
 
-       * mood mode. Audio file selection works by spcifying mood
+       * mood mode. Audio file selection works by specifying mood
          methods involving attributes, pattern matching for file names
          and more.  This allows rather sophisticated configurations
          and is explained in more detail in INSTALL.
@@ -149,44 +151,12 @@ bash_completion (optional)
 
 A small bash script for inclusion in ~/.bashrc. It gives you command
 line completion for some paraslash commands.
-
-------------
-Requirements
-------------
-
-In any case you need
-
-       - gcc, the gnu compiler collection (shipped with distro): gcc-3.3
-         or newer is required.
-       - gnu make (shipped with disto, might be called gmake)
-       - bash
-       - openssl (needed by server, client): usually shipped with
-         distro, but you might have to install the "development package"
-         (called libssl-dev on debian systems) as well:
-         http://www.openssl.org/
-       - software mixing, e.g. ALSA and the direct mixing plugin (dmix)
-
-The mp3 decoder of para_filter is based on libmad: If you prefer to
-use the libmad package provided by your distributor, make sure to
-install the corresponding development package as well.  Otherwise,
-just download libmad from http://www.underbit.com/products/mad/
-
-For ogg vorbis streams you'll need libogg, libvorbis, libvorbisfile,
-The corresponding Debian packages are called libogg-dev libvorbis-dev,
-other distributors chose similar names.  All of these are also
-available at http://www.xiph.org/downloads/
-
-For aac files (m4a) you'll need libfaad. Get it at
-http://www.audiocoding.com/modules/wiki/?page=AAC
-
-If you intend to use the optional ortp streamer, you'll need libortp:
-http://www.linphone.org/ortp/
-
 -------
 LICENSE
 -------
 
-Distribution of paraslash is covered by the GNU GPL. See file COPYING.
+Distribution of paraslash is covered by the GNU GPL, version 2. See file
+COPYING.
 
 ----------
 THE AUTHOR
diff --git a/README.afs b/README.afs
new file mode 100644 (file)
index 0000000..e627ca7
--- /dev/null
@@ -0,0 +1,230 @@
+The audio file selector
+=======================
+
+Paraslash comes with a sophisticated audio file selector called afs.
+In the installation notes, only the "dummy" mode of afs was used which
+gets activated automatically if nothing else was specified. In this
+section the various features of afs are described.
+
+----------
+Attributes
+~~~~~~~~~~
+
+An attribute is simply a bit which can be set for each audio
+file individually.  Up to 64  different attributes may be
+defined. For example, "pop", "rock", "blues", "jazz", "instrumental",
+"german_lyrics", "speech", whatever. It's up to you how many attributes
+you define and how you call them.
+
+A new attribute "test" is created by
+
+       para_client addatt test
+and
+       para_client lsatt
+
+lists all available attributes. You can set the "test" attribute for
+an audio file by executing
+
+       para_client setatt test+ /path/to/the/audio/file
+
+Similarly, the "test" bit can be removed from a audio file with
+
+       para_client setatt test- /path/to/the/audio/file
+
+Instead of a path you can also use a pattern, and the attribute is
+applied to all audio files matching that pattern:
+
+       para_client setatt test+ '/test/directory/*'
+
+The command
+
+       para_client -- ls -lv
+
+gives you a verbose listing of your audio files which contains also
+which attributes are set.
+
+In case you wonder why the double-dash in the above command is needed:
+It tells para_client to not interpret the options after the dashes. If
+you find this annoying, just say
+
+       alias para='para_client --'
+
+and be happy. In the remainder part this alias is being used.
+
+Drop the test attribute entirely from the database with
+
+       para rmatt test
+
+Read the output of
+
+       para help ls
+       para help setatt
+
+for more information and a complete list of command line options to
+these commands.
+
+
+----------------------
+Abstract mood nonsense
+~~~~~~~~~~~~~~~~~~~~~~
+
+[skip this part if you don't like formal definitions]
+
+A mood consists of a unique name and its *mood definition*, which is a set of
+*mood lines* containing expressions in terms of attributes and other data
+contained in the database.
+
+A mood defines a subset of audio files called the *admissible audio files*
+for that mood. A mood can be *active* which means that para_server
+is going to select only files from that subset of admissible files.
+
+So in order to create a mood definition one has to write a set of
+mood lines. Mood lines come in three flavours: Accept lines, deny
+lines and score lines.
+
+The general syntax of the three types of mood lines is
+
+
+       accept [with score <score>] [if] [not] <mood_method> [options]
+       deny [with score <score>] [if] [not] <mood_method> [options]
+       score <score>  [if] [not] <mood_method> [options]
+
+
+Here <score> is either an integer or the string "random" which assigns
+a random score to all matching files. The score value changes the
+order in which admissible files are going to be selected, but is of
+minor importance for this introduction.
+
+So we concentrate on the first two forms, that is accept and deny
+lines. As usual, everything in square brackets is optional, i.e.
+accept/deny lines take the following form when ignoring scores:
+
+       accept [if] [not] <mood_method> [options]
+
+and analogously for the deny case. The "if" keyword is purely cosmetic
+and has no function. The "not" keyword just inverts the result, so
+the essence of a mood line is the mood method part and the options
+following thereafter.
+
+A *mood method* is realized as a function which takes an audio file
+and computes a number from the data contained in the database.
+If this number is non-negative, we say the file *matches* the mood
+method. The file matches the full mood line if it either
+
+       - matches the mood method and the "not" keyword is not given,
+or
+       - does not match the mood method, but the "not" keyword is given.
+
+The set of admissible files for the whole mood is now defined as those
+files which match at least one accept mood line, but no deny mood line.
+More formally, a file is admissible if and only if
+
+       (F ~ AL1 or F ~ AL2...) and not (F ~ DL1 or F ~ DN2 ...)
+
+where F is the file, AL1, AL2... are the accept lines, DL1, DL2... are
+the deny lines and "~" means "matches".
+
+The cases where no mood lines of accept/deny type are defined need
+special treatment:
+
+       - Neither accept nor deny lines: This treats all files as admissible
+         (in fact, that is the definition of the dummy mood which is activated
+         automatically if no moods are available).
+
+       - Only accept lines: A file is admissible iff it matches at least one
+         accept line:
+
+               F ~ AL1 or F ~ AL2 or ...
+
+       - Only deny lines: A file is admissible iff it matches no deny line:
+
+               not (F ~ DL1 or F ~ DN2 ...)
+
+
+
+--------------------
+List of mood_methods
+~~~~~~~~~~~~~~~~~~~~
+
+       no_attributes_set()
+
+Takes no arguments and matches an audio file if and only if no
+attributes are set.
+
+       played_rarely()
+
+Takes no arguments and matches all audio files where the number of
+times this audio file was selected is below the average.
+
+       is_set(attribute_name)
+
+Takes the name of an attribute and matches iff that attribute is set.
+
+       name_like(pattern)
+
+Takes a filename pattern and matches iff the path of the audio file
+matches the pattern.
+
+
+----------
+Mood usage
+~~~~~~~~~~
+
+To create a new mood called "my_mood", write its definition into
+some temporary file, say "tmpfile", and add it to the mood table
+by executing
+
+       para addmood my_mood < tmpfile
+
+If the mood definition is really short, you may just pipe it to the
+client instead of using temporary files. Like this:
+
+       echo "$MOOD_DEFINITION" | para addmood my_mood
+
+There is no need to keep the temporary file since you can always use
+the catmood command to get it back:
+
+       para catmood my_mood
+
+A mood can be activated by executing
+
+       para chmood my_mood
+
+Once active, the list of admissible files is shown by the ls command
+if the "-a" switch is given:
+
+       para ls -a
+
+-----------------------
+Example mood definition
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Suppose you have defined attributes "punk" and "rock" and want to define
+a mood containing only Punk-Rock songs. That is, an audio file should be
+admissible if and only if both attributes are set. Since
+
+       punk and rock
+
+is obviously the same as
+
+       not (not punk or not rock)
+
+(de Morgan's rule), a mood definition that selects only Punk-Rock
+songs is
+
+       deny if not is_set punk
+       deny if not is_set rock
+
+
+---------
+Troubles?
+---------
+If something went wrong, look at the output. If that does not give
+you a clue, use loglevel one (option -l 1 for most commands) to show
+debugging info. Almost all paraslash executables have a brief online
+help which is displayed by using the -h switch.
+
+Still not working? Mail the author Andre Noll <maan@systemlinux.org>
+(english, german, or spanish language). Please provide enough info
+such as the version of paraslash you are using and relevant parts of
+the logs.
diff --git a/REQUIREMENTS b/REQUIREMENTS
new file mode 100644 (file)
index 0000000..0a572b1
--- /dev/null
@@ -0,0 +1,44 @@
+Requirements
+============
+
+In any case you need
+
+       - gcc, the gnu compiler collection (shipped with distro): gcc-3.3
+         or newer is required.
+       - gnu make (shipped with disto, might be called gmake)
+       - bash
+       - openssl (needed by server, client): usually shipped with
+         distro, but you might have to install the "development package"
+         (called libssl-dev on debian systems) as well:
+         http://www.openssl.org/
+       - software mixing, e.g. ALSA and the direct mixing plugin (dmix)
+
+Optional features:
+
+       - *mp3*:
+       The mp3 decoder of para_filter is based on libmad:
+       If you prefer to use the libmad package provided by your
+       distributor, make sure to install the corresponding development
+       package as well.    Otherwise, just download libmad from
+       http://www.underbit.com/products/mad/
+
+       - *ogg vorbis*:
+       For ogg vorbis streams you'll need libogg, libvorbis,
+       libvorbisfile, The corresponding Debian packages are
+       called libogg-dev libvorbis-dev, other distributors chose
+       similar names.  The source of these is also available at
+       http://www.xiph.org/downloads/
+
+       - *aac*:
+       For aac files (m4a) you'll need libfaad. Get it at
+       http://www.audiocoding.com/modules/wiki/?page=AAC
+
+       - *ortp*:
+       If you intend to use the optional ortp streamer, you'll need libortp:
+       http://www.linphone.org/ortp/
+
+Hacking the source:
+
+       - gengetopt: ftp://ftp.gnu.org/pub/gnu/gengetopt/
+       - autoconf: ftp://ftp.gnu.org/pub/gnu/autoconf/
+       - grutatxt