Don't let make write the filename into the output
[paraslash.git] / INSTALL
diff --git a/INSTALL b/INSTALL
index 236e66d..b0bbbad 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -7,14 +7,16 @@ Any knowledge of how to work with mouse and icons is not required.
 ---------------------------
 Install all needed packages
 ---------------------------
-
-See README for a list of required software. You don't need everything
-listed there. In particular, mp3, ogg vorbis and aac support is
-optional. Autoconf will detect what is installed on your system
-and will only try to build those executables that can be built with
-your setup.
-
-Note that no special library (not even the mp3 decodong library libmad)
+See
+<<
+<a href="REQUIREMENTS.html"> REQUIREMENTS </a>
+>>
+for a list of required software. You don't need everything listed there. In
+particular, mp3, ogg vorbis and aac support are all optional. Autoconf will
+detect what is installed on your system and will only try to build those
+executables that can be built with your setup.
+
+Note that no special library (not even the mp3 decoding library libmad)
 is needed for para_server if you only want to stream mp3 files.
 Also, it's fine to use para_server on a box without sound card as
 para_server only sends the audio stream to connected clients.
@@ -53,24 +55,25 @@ as user foo, and that you want to connect from client_host as user bar.
 As foo@server_host, create ~/.paraslash/server.users by typing the
 following commands:
 
+       user=bar
        target=~/.paraslash/server.users
-       key=~/.paraslash/key.pub.bar
+       key=~/.paraslash/key.pub.$user
        perms=AFS_READ,AFS_WRITE,VSS_READ,VSS_WRITE
        mkdir -p ~/.paraslash
-       echo "user bar $key $perms" >> $target
+       echo "user $user $key $perms" >> $target
 
 This gives "bar" the full privileges.
 
 Change to the bar account on client_host and generate the key-pair
 with the commands
 
-       key=~/.paraslash/key.bar
+       key=~/.paraslash/key.$LOGNAME
        mkdir -p ~/.paraslash
        (umask 077 && openssl genrsa -out $key)
 
 Next, extract its public part:
 
-       pubkey=~/.paraslash/key.pub.bar
+       pubkey=~/.paraslash/key.pub.$LOGNAME
        openssl rsa -in $key -pubout -out $pubkey
 
 and copy the public key just created to server_host (you may
@@ -88,10 +91,18 @@ 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
-output of para_server more verbose.
+Before starting the server make sure you have write permissions to
+the directory /var/paraslash.
+
+       sudo chown $user /var/paraslash
 
-       para_server -l 2
+Alternatively, use the --afs_socket Option to specify a different
+location for the afs command socket.
+
+For this first try, we'll use the info loglevel to make the output
+of para_server more verbose.
+
+       para_server -l info
 
 Now you can use para_client to connect to the server and issue
 commands. Open a new shell (as "bar" on "client_host" in the above
@@ -125,8 +136,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
 
@@ -136,8 +147,8 @@ Print a list of all audio files found with
 Start streaming manually
 ------------------------
 
-       para play
-       para stat 2
+       para_client play
+       para_client stat 2
 
 This starts streaming and dumps some information about the current
 audio file to stdout.
@@ -153,7 +164,7 @@ Paraslash comes with its own receiving and playing software, which
 will be described next. Try the following on client_host (assuming
 Linux/ALSA and an mp3 stream):
 
-       para_recv -l 2 -r 'http -i server_host' > file.mp3
+       para_recv -l info -r 'http -i server_host' > file.mp3
        # (interrupt with CTRL+C after a few seconds)
        ls -l file.mp3 # should not be empty
        para_filter -f mp3dec -f wav < file.mp3 > file.wav
@@ -185,7 +196,7 @@ supposed to play the audio stream. Try
 for help. Usually you have to specify only server_host as the receiver
 specifier for each supported audio format, like this:
 
-       para_audiod -l 2 -r 'mp3:http -i server_host'
+       para_audiod -l info -r 'mp3:http -i server_host'
 
 The preferred way to use para_audiod is to run it once at system start
 as an unprivileged user. para_audiod needs to create a "well-known"
@@ -194,7 +205,7 @@ socket is
 
        /var/paraslash/audiod_socket.$HOSTNAME
 
-so the /var/paraslash directory should be owned by the user who
+so the /var/paraslash directory should be writable for the user who
 runs para_audiod.
 
 If you want to change the location of the socket, use the -s option
@@ -236,235 +247,8 @@ 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
+<<
+<a href="README.afs.html"> README.afs</a>
+>>