Change all multi-word options to dashes instead of underscores.
[paraslash.git] / web / manual.m4
index 041457e..55bb49a 100644 (file)
@@ -77,11 +77,11 @@ The paraslash executables
 
 *para_server*
 
 
 *para_server*
 
-para_server streams binary audio data (MP3, OGG/Vorbis, OGG/Speex,
-M4A, WMA files) over local and/or remote networks. It listens on a
-TCP port and accepts commands such as play, stop, pause, next from
-authenticated clients. There are many more commands though, see the
-man page of para_server for a description of all commands.
+para_server streams binary audio data (MP3, ...) over local and/or
+remote networks. It listens on a TCP port and accepts commands such
+as play, stop, pause, next from authenticated clients. There are
+many more commands though, see the man page of para_server for a
+description of all commands.
 
 It supports three built-in network streaming protocols
 (senders/receivers): HTTP, DCCP, or UDP. This is explained in more
 
 It supports three built-in network streaming protocols
 (senders/receivers): HTTP, DCCP, or UDP. This is explained in more
@@ -145,6 +145,12 @@ interactive sessions on systems with libreadline.
 
 A command line HTTP/DCCP/UDP stream grabber. The http mode is
 compatible with arbitrary HTTP streaming sources (e.g. icecast).
 
 A command line HTTP/DCCP/UDP stream grabber. The http mode is
 compatible with arbitrary HTTP streaming sources (e.g. icecast).
+In addition to the three network streaming modes, para_recv can also
+operate in local (afh) mode. In this mode it writes the content of
+an audio file on the local file system in complete chunks to stdout,
+optionally 'just in time'. This allows to cut an audio file without
+first decoding it, and it enables third-party software which is unaware
+of the particular audio format to send complete frames in real time.
 
 *para_filter*
 
 
 *para_filter*
 
@@ -159,11 +165,7 @@ for audio volume.
 
 A small stand-alone program that prints tech info about the given
 audio file to STDOUT. It can be instructed to print a "chunk table",
 
 A small stand-alone program that prints tech info about the given
 audio file to STDOUT. It can be instructed to print a "chunk table",
-an array of offsets within the audio file or to write the content of
-the audio file in complete chunks 'just in time'.
-
-This allows third-party streaming software that is unaware of the
-particular audio format to send complete frames in real time.
+an array of offsets within the audio file.
 
 *para_write*
 
 
 *para_write*
 
@@ -172,6 +174,9 @@ output plug-in and optional WAV/raw players for ALSA (Linux) and for
 coreaudio (Mac OS). para_write can also be used as a stand-alone WAV
 or raw audio player.
 
 coreaudio (Mac OS). para_write can also be used as a stand-alone WAV
 or raw audio player.
 
+*para_play*
+
+A command line audio player.
 
 *para_gui*
 
 
 *para_gui*
 
@@ -183,7 +188,7 @@ can be added easily.
 
 *para_fade*
 
 
 *para_fade*
 
-An (OSS-only) alarm clock and volume-fader.
+An alarm clock and volume-fader for OSS and ALSA.
 
 -----------
 Quick start
 
 -----------
 Quick start
@@ -197,8 +202,16 @@ REFERENCE(Quick start, set up) a typical server and client.
 
 Requirements
 ~~~~~~~~~~~~
 
 Requirements
 ~~~~~~~~~~~~
+For the impatient:
 
 
-In any case you'll need
+       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 \
+              libmad0-dev libid3tag0-dev libasound2-dev libvorbis-dev \
+              libfaad-dev libspeex-dev libFLAC-dev libsamplerate-dev \
+              libasound2-dev libao-dev libreadline-dev libncurses-dev
+
+Detailed description: In any case you'll need
 
        - XREFERENCE(http://systemlinux.org/~maan/osl/, libosl).
        The _object storage layer_ library is used by para_server. To
 
        - XREFERENCE(http://systemlinux.org/~maan/osl/, libosl).
        The _object storage layer_ library is used by para_server. To
@@ -262,6 +275,10 @@ Optional:
        or decode files encoded with the _Free Lossless Audio Codec_,
        libFLAC (libFLAC-dev) must be installed.
 
        or decode files encoded with the _Free Lossless Audio Codec_,
        libFLAC (libFLAC-dev) must be installed.
 
+       - XREFERENCE(http://www.mega-nerd.com/SRC/index.html,
+       libsamplerate). The resample filter will only be compiled if
+       this library is installed. Debian package: libsamplerate-dev.
+
        - XREFERENCE(ftp://ftp.alsa-project.org/pub/lib/, alsa-lib). On
        Linux, you'll need to have ALSA's development package
        libasound2-dev installed.
        - XREFERENCE(ftp://ftp.alsa-project.org/pub/lib/, alsa-lib). On
        Linux, you'll need to have ALSA's development package
        libasound2-dev installed.
@@ -270,9 +287,13 @@ Optional:
        libao). Needed to build the ao writer (ESD, PulseAudio,...).
        Debian package: libao-dev.
 
        libao). Needed to build the ao writer (ESD, PulseAudio,...).
        Debian package: libao-dev.
 
+       - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/ncurses, curses). Needed
+       for para_gui. Debian package: libncurses-dev.
+
        - XREFERENCE(http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html,
        GNU Readline). If this library (libreadline-dev) is installed,
        - XREFERENCE(http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html,
        GNU Readline). If this library (libreadline-dev) is installed,
-       para_client and para_audioc support interactive sessions.
+       para_client, para_audioc and para_play support interactive
+       sessions.
 
 Installation
 ~~~~~~~~~~~~
 
 Installation
 ~~~~~~~~~~~~
@@ -291,10 +312,20 @@ libmad) is needed for para_server if you only want to stream MP3 or WMA
 files. Also, it's fine to use para_server on a box without sound card.
 
 Next, install the paraslash package on all machines, you'd like this
 files. Also, it's fine to use para_server on a box without sound card.
 
 Next, install the paraslash package on all machines, you'd like this
-software to run on:
+software to run on. If you compile from a released tarball, execute
 
        (./configure && make) > /dev/null
 
 
        (./configure && make) > /dev/null
 
+When compiling from git or from snapshots downloaded via gitweb,
+the above command will not work because the configure script is not
+included in the git repository. In this case the following command
+should be used instead:
+
+       ./autogen.sh
+
+This runs autoconf to generate the configure script, then runs it as
+above. Therefore you'll need autoconf for this to work.
+
 There should be no errors but probably some warnings about missing
 packages which usually implies that not all audio formats will be
 supported. If headers or libs are installed at unusual locations you
 There should be no errors but probably some warnings about missing
 packages which usually implies that not all audio formats will be
 supported. If headers or libs are installed at unusual locations you
@@ -375,7 +406,7 @@ the directory /var/paraslash that has been created during installation:
 
        sudo chown $LOGNAME /var/paraslash
 
 
        sudo chown $LOGNAME /var/paraslash
 
-Alternatively, use the --afs_socket Option to specify a different
+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
 location for the AFS command socket.
 
 For this first try, we'll use the info loglevel to make the output
@@ -494,7 +525,7 @@ including ssh and gpg. An RSA key consists in fact of two keys,
 called the public key and the private key. A message can be encrypted
 with either key and only the counterpart of that key can decrypt
 the message. While RSA can be used for both signing and encrypting
 called the public key and the private key. A message can be encrypted
 with either key and only the counterpart of that key can decrypt
 the message. While RSA can be used for both signing and encrypting
-a message, paraslash only uses RSA only for the latter purpose. The
+a message, paraslash uses RSA only for the latter purpose. The
 RSA public key encryption and signatures algorithms are defined in
 detail in RFC 2437.
 
 RSA public key encryption and signatures algorithms are defined in
 detail in RFC 2437.
 
@@ -561,7 +592,7 @@ The user_list file
 
 At startup para_server reads the user list file which contains one
 line per user. The default location of the user list file may be
 
 At startup para_server reads the user list file which contains one
 line per user. The default location of the user list file may be
-changed with the --user_list option.
+changed with the --user-list option.
 
 There should be at least one user in this file. Each user must have
 an RSA key pair. The public part of the key is needed by para_server
 
 There should be at least one user in this file. Each user must have
 an RSA key pair. The public part of the key is needed by para_server
@@ -608,7 +639,7 @@ restricted on platforms that support UNIX socket credentials which
 allow para_audiod to obtain the Unix credentials of the connecting
 process.
 
 allow para_audiod to obtain the Unix credentials of the connecting
 process.
 
-Use para_audiod's --user_allow option to allow connections only for
+Use para_audiod's --user-allow option to allow connections only for
 a limited set of users.
 
 -----------------------
 a limited set of users.
 
 -----------------------
@@ -1739,7 +1770,7 @@ a curses window. By default the command
 
        para_audioc -- stat -p
 
 
        para_audioc -- stat -p
 
-is executed, but this can be customized via the --stat_cmd option. In
+is executed, but this can be customized via the --stat-cmd option. In
 particular it possible to use
 
        para_client -- stat -p
 particular it possible to use
 
        para_client -- stat -p