Fix a typo in the manual.
[paraslash.git] / web / manual.m4
index f9b5344..e665ea7 100644 (file)
@@ -115,6 +115,9 @@ All connections between para_server and para_client are encrypted
 with a symmetric RC4 session key. For each user of paraslash you must
 create a public/secret RSA key pair for authentication.
 
 with a symmetric RC4 session key. For each user of paraslash you must
 create a public/secret RSA key pair for authentication.
 
+If para_client is started without non-option arguments, an interactive
+session (shell) is started. Command history and command completion are
+supported through libreadline.
 
 *para_audiod*
 
 
 *para_audiod*
 
@@ -135,7 +138,8 @@ socket credentials, if available.
 
 The client program which talks to para_audiod. Used to control
 para_audiod, to receive status info, or to grab the stream at any
 
 The client program which talks to para_audiod. Used to control
 para_audiod, to receive status info, or to grab the stream at any
-point of the decoding process.
+point of the decoding process. Like para_client, para_audioc supports
+interactive sessions on systems with libreadline.
 
 *para_recv*
 
 
 *para_recv*
 
@@ -202,9 +206,10 @@ In any case you'll need
 
        git clone git://git.tuebingen.mpg.de/osl
 
 
        git clone git://git.tuebingen.mpg.de/osl
 
-       - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/gcc, gcc). The
-       EMPH(gnu compiler collection) is usually shipped with the
-       distro. gcc-3.3 or newer is required.
+       - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/gcc, gcc) or
+       XREFERENCE(http://clang.llvm.org, clang). All gcc versions
+       >= 3.3 are currently supported. Clang version 1.1 or newer
+       should work as well.
 
        - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/make, gnu make) is
        also shipped with the disto. On BSD systems the gnu make
 
        - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/make, gnu make) is
        also shipped with the disto. On BSD systems the gnu make
@@ -214,11 +219,17 @@ In any case you'll need
        scripts which run during compilation require the EMPH(Bourne
        again shell).  It is most likely already installed.
 
        scripts which run during compilation require the EMPH(Bourne
        again shell).  It is most likely already installed.
 
-       - XREFERENCE(http://www.openssl.org/, openssl). The EMPH(Secure
-       Sockets Layer) library is needed for cryptographic routines
-       on both the server and the client side. It is usually shipped
-       with the distro, but you might have to install the "development
-       package" (called libssl-dev on debian systems) as well.
+       - XREFERENCE(http://www.openssl.org/, openssl) or
+       XREFERENCE(ftp://ftp.gnupg.org/gcrypt/libgcrypt/, libgcrypt).
+       At least one of these two libraries is needed as the backend
+       for cryptographic routines on both the server and the client
+       side. Both openssl and libgcrypt are usually shipped with the
+       distro, but you might have to install the development package
+       (libssl-dev or libgcrypt-dev on debian systems) as well.
+
+       - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/gengetopt/, gengetopt)
+       is needed to generate the C code for the command line parsers
+       of all paraslash executables.
 
        - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/help2man, help2man)
        is used to create the man pages.
 
        - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/help2man, help2man)
        is used to create the man pages.
@@ -244,10 +255,25 @@ Optional:
        - XREFERENCE(http://www.audiocoding.com/, libfaad).  For aac
        files (m4a) you'll need libfaad (libfaad-dev).
 
        - XREFERENCE(http://www.audiocoding.com/, libfaad).  For aac
        files (m4a) you'll need libfaad (libfaad-dev).
 
+       - XREFERENCE(http://www.speex.org/, speex). In order to stream
+       or decode speex files, libspeex (libspeex-dev) is required.
+
+       - XREFERENCE(http://flac.sourceforge.net/, flac). To stream
+       or decode files encoded with the _Free Lossless Audio Codec_,
+       libFLAC (libFLAC-dev) must be 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.
 
        - 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(http://downloads.xiph.org/releases/ao/,
+       libao). Needed to build the ao writer (ESD, PulseAudio,...).
+       Debian package: libao-dev.
+
+       - 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.
+
 Installation
 ~~~~~~~~~~~~
 
 Installation
 ~~~~~~~~~~~~
 
@@ -277,7 +303,11 @@ might need to tell the configure script where to find them. Try
        ./configure --help
 
 to see a list of options. If the paraslash package was compiled
        ./configure --help
 
 to see a list of options. If the paraslash package was compiled
-successfully, execute as root,
+successfully, execute (optionally)
+
+       make test
+
+to run the paraslash test suite. If all tests pass, execute as root
 
        make install
 
 
        make install
 
@@ -304,7 +334,7 @@ following commands:
 
        user=bar
        target=~/.paraslash/server.users
 
        user=bar
        target=~/.paraslash/server.users
-       key=~/.paraslash/key.pub.$user
+       key=~/.paraslash/id_rsa.pub.$user
        perms=AFS_READ,AFS_WRITE,VSS_READ,VSS_WRITE
        mkdir -p ~/.paraslash
        echo "user $user $key $perms" >> $target
        perms=AFS_READ,AFS_WRITE,VSS_READ,VSS_WRITE
        mkdir -p ~/.paraslash
        echo "user $user $key $perms" >> $target
@@ -312,20 +342,25 @@ following commands:
 Next, change to the "bar" account on client_host and generate the
 key pair with the commands
 
 Next, change to the "bar" account on client_host and generate the
 key pair with the commands
 
-       key=~/.paraslash/key.$LOGNAME
-       mkdir -p ~/.paraslash
-       (umask 077 && openssl genrsa -out $key 2048)
+       ssh-keygen -t rsa -b 2048
+       # hit enter twice to create a key with no passphrase
 
 
-para_server only needs to know the public key of the key pair just
-created. It can be extracted with
+This generates the two files id_rsa and id_rsa.pub in ~/.ssh. Note
+that paraslash can also read keys generated by the "openssl genrsa"
+command. However, since keys created with ssh-keygen can also be used
+for ssh, this method is recommended.
 
 
-       pubkey=~/.paraslash/key.pub.$LOGNAME
-       openssl rsa -in $key -pubout -out $pubkey
+Note that para_server refuses to use a key if it is shorter than 2048
+bits. In particular, the RSA keys of paraslash 0.3.x will not work
+with version 0.4.x. Moreover, para_client refuses to use a (private)
+key which is world-readable.
 
 
-Copy the public key just created to server_host (you may skip this step
-for a single-user setup, i.e. if foo=bar and server_host=client_host):
+para_server only needs to know the public key of the key pair just
+created. Copy this public key to server_host:
 
 
-       scp $pubkey foo@server_host:.paraslash/
+       src=~/.ssh/id_rsa.pub
+       dest=.paraslash/id_rsa.pub.$LOGNAME
+       scp $src foo@server_host:$dest
 
 Finally, tell para_client to connect to server_host:
 
 
 Finally, tell para_client to connect to server_host:
 
@@ -399,9 +434,9 @@ as bar@client_host
 
 
 We will also have to tell para_audiod that it should receive the
 
 
 We will also have to tell para_audiod that it should receive the
-audio stream from server_host:
+audio stream from server_host via http:
 
 
-       para_audiod -l info -r 'mp3:http -i server_host'
+       para_audiod -l info -r '.:http -i server_host'
 
 You should now be able to listen to the audio stream once para_server
 starts streaming. To activate streaming, execute
 
 You should now be able to listen to the audio stream once para_server
 starts streaming. To activate streaming, execute
@@ -459,7 +494,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.
 
@@ -479,12 +514,13 @@ as follows:
 
        - para_client connects to para_server and sends an
        authentication request for a user. It does so by connecting
 
        - para_client connects to para_server and sends an
        authentication request for a user. It does so by connecting
-       to para_server, TCP 2990, the control port of para_server.
+       to TCP port 2990 of the server host. This port is called the
+       para_server _control port_.
 
        - para_server accepts the connection and forks a child process
 
        - para_server accepts the connection and forks a child process
-       which is supposed to handle the connection. The parent process
-       keeps listening on the control port while the child process
-       (also called para_server below) continues as follows.
+       which handles the incoming request. The parent process keeps
+       listening on the control port while the child process (also
+       called para_server below) continues as follows.
 
        - para_server loads the RSA public key of that user, fills a
        fixed-length buffer with random bytes, encrypts that buffer
 
        - para_server loads the RSA public key of that user, fills a
        fixed-length buffer with random bytes, encrypts that buffer
@@ -494,7 +530,7 @@ as follows:
        session key.
 
        - para_client receives the encrypted buffer and decrypts it
        session key.
 
        - para_client receives the encrypted buffer and decrypts it
-       using the user's private key, thereby obtaining the challenge
+       with the user's private key, thereby obtaining the challenge
        buffer and the session key. It sends the SHA1 hash value of
        the challenge back to para_server and stores the session key
        for further use.
        buffer and the session key. It sends the SHA1 hash value of
        the challenge back to para_server and stores the session key
        for further use.
@@ -510,10 +546,10 @@ as follows:
        this point on the communication is encrypted using the RC4
        stream cipher with the session key known to both peers.
 
        this point on the communication is encrypted using the RC4
        stream cipher with the session key known to both peers.
 
-paraslash relies on the quality of openssl's cryptographically strong
-pseudo-random bytes, on the security of the implementation of the
-openssl RSA and RC4 crypto routines and on the infeasibility to invert
-the SHA1 function.
+paraslash relies on the quality of the pseudo-random bytes provided
+by the crypto library (openssl or libgcrypt), on the security of
+the implementation of the RSA and RC4 crypto routines and on the
+infeasibility to invert the SHA1 function.
 
 Neither para_server or para_client create RSA keys on their own. This
 has to be done once for each user as sketched in REFERENCE(Quick start,
 
 Neither para_server or para_client create RSA keys on their own. This
 has to be done once for each user as sketched in REFERENCE(Quick start,
@@ -523,8 +559,8 @@ file, below).
 The user_list file
 ~~~~~~~~~~~~~~~~~~
 
 The user_list file
 ~~~~~~~~~~~~~~~~~~
 
-At startup para_server reads the user list file which must contain
-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.
 
 There should be at least one user in this file. Each user must have
 changed with the --user_list option.
 
 There should be at least one user in this file. Each user must have
@@ -557,19 +593,6 @@ execute. The output of
 contains in the third column the permissions needed to execute the
 command.
 
 contains in the third column the permissions needed to execute the
 command.
 
-A new RSA key can be created with
-
-       openssl genrsa -out <private_key> 2048
-
-and the public part may be extracted with
-
-       openssl rsa -in <private_key> -pubout -out <public_key>
-
-Note that para_server refuses to use a key if it is shorter than 2048
-bits. In particular, the RSA keys of paraslash 0.3.x will not work
-with version 0.4.x. Moreover, para_client refuses to use a (private)
-key which is world-readable.
-
 It is possible to make para_server reread the user_list file by
 executing the paraslash "hup" command or by sending SIGHUP to the
 PID of para_server.
 It is possible to make para_server reread the user_list file by
 executing the paraslash "hup" command or by sending SIGHUP to the
 PID of para_server.
@@ -604,10 +627,11 @@ known audio files to those which satisfy certain criteria.  It also
 maintains tables containing images (e.g. album cover art) and lyrics
 that can be associated with one or more audio files.
 
 maintains tables containing images (e.g. album cover art) and lyrics
 that can be associated with one or more audio files.
 
-AFS uses libosl, the object storage layer, as the backend library
-for storing information on audio files, playlists, etc. This library
-offers functionality similar to a relational database, but is much
-more lightweight than a full database backend.
+AFS uses XREFERENCE(http://systemlinux.org/~maan/osl/, libosl), the
+object storage layer library, as the backend library for storing
+information on audio files, playlists, etc. This library offers
+functionality similar to a relational database, but is much more
+lightweight than a full database backend.
 
 In this chapter we sketch the setup of the REFERENCE(The AFS process,
 AFS process) during server startup and proceed with the description
 
 In this chapter we sketch the setup of the REFERENCE(The AFS process,
 AFS process) during server startup and proceed with the description
@@ -617,7 +641,7 @@ and moods) explains these two audio file selection mechanisms
 in detail and contains pratical examples. The way REFERENCE(File
 renames and content changes, file renames and content changes) are
 detected is discussed briefly before the REFERENCE(Troubleshooting,
 in detail and contains pratical examples. The way REFERENCE(File
 renames and content changes, file renames and content changes) are
 detected is discussed briefly before the REFERENCE(Troubleshooting,
-Troubleshooting) section which concludes the chapter.
+Troubleshooting) section concludes the chapter.
 
 The AFS process
 ~~~~~~~~~~~~~~~
 
 The AFS process
 ~~~~~~~~~~~~~~~
@@ -720,7 +744,7 @@ Similarly, the "test" bit can be removed from an audio file with
        para_client setatt test- /path/to/the/audio/file
 
 Instead of a path you may use a shell wildcard pattern. The attribute
        para_client setatt test- /path/to/the/audio/file
 
 Instead of a path you may use a shell wildcard pattern. The attribute
-is applied to all audio files matching that pattern:
+is applied to all audio files matching this pattern:
 
        para_client setatt test+ '/test/directory/*'
 
 
        para_client setatt test+ '/test/directory/*'
 
@@ -776,7 +800,7 @@ can be used.
 
 Note that the images and lyrics are not interpreted at all, and also
 the playlist and the mood blobs are only investigated when the mood
 
 Note that the images and lyrics are not interpreted at all, and also
 the playlist and the mood blobs are only investigated when the mood
-or playlist is activated by using the select command.
+or playlist is activated with the select command.
 
 *The score table*
 
 
 *The score table*
 
@@ -792,7 +816,9 @@ 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 is recomputed by the select command which loads a
 last_played and the num_played fields in the audio file table.
 
 The score table is recomputed by the select command which loads a
-new mood or playlist.
+mood or playlist. Audio files are chosen for streaming from the rows
+of the score table on a highest-score-first basis.
+
 
 Playlists and moods
 ~~~~~~~~~~~~~~~~~~~
 
 Playlists and moods
 ~~~~~~~~~~~~~~~~~~~
@@ -804,17 +830,12 @@ terms of attributes and other type of information available in the
 audio file table. As an example, a mood can define a filename pattern,
 which is then matched against the names of audio files in the table.
 
 audio file table. As an example, a mood can define a filename pattern,
 which is then matched against the names of audio files in the table.
 
-Selecting a mood or playlist means the generation of a ranking
-(a score table) for the set of admissible files. Audio files are
-then selected on a highest-score-first basis. The score table is
-recomputed at the moment the mood or playlist is selected.
-
 *Playlists*
 
 Playlists are accommodated in the playlist table of the afs database,
 *Playlists*
 
 Playlists are accommodated in the playlist table of the afs database,
-using the aforementioned blob format for tables. A new filelist is
-created using the addpl command, by specifying the full (absolute)
-paths of all desired audio files, separated by newlines. For example
+using the aforementioned blob format for tables. A new playlist is
+created with the addpl command by specifying the full (absolute)
+paths of all desired audio files, separated by newlines. Example:
 
        find /my/mp3/dir -name "*.mp3" | para addpl my_playlist
 
 
        find /my/mp3/dir -name "*.mp3" | para addpl my_playlist
 
@@ -834,7 +855,7 @@ 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 set of *mood lines* containing expressions in terms of attributes
 and other data contained in the database.
 
-At any time, at most one mood can be *active* which means that
+At any time at most one mood can be *active* which means that
 para_server is going to select only files from that subset of
 admissible files.
 
 para_server is going to select only files from that subset of
 admissible files.
 
@@ -944,7 +965,7 @@ 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
 audio files never match. Another difference is the special treatment
 if the year tag is a two-digit number. In this case either 1900 or
 has no year tag or the content of the year tag is not a number. Such
 audio files never match. Another difference is the special treatment
 if the year tag is a two-digit number. In this case either 1900 or
-2000 are added to the tag value depending on whether the number is
+2000 is added to the tag value, depending on whether the number is
 greater than 2000 plus the current year.
 
 
 greater than 2000 plus the current year.
 
 
@@ -1102,6 +1123,15 @@ how meta data about the file is to be encoded. The bit stream of WMA
 is composed of superframes, each containing one or more frames of
 2048 samples. For 16 bit stereo a WMA superframe is about 8K large.
 
 is composed of superframes, each containing one or more frames of
 2048 samples. For 16 bit stereo a WMA superframe is about 8K large.
 
+*FLAC*
+
+The Free Lossless Audio Codec (FLAC) compresses audio without quality
+loss. It gives better compression ratios than a general purpose
+compressor like zip or bzip2 because FLAC is designed specifically
+for audio. A FLAC-encoded file consits of frames of varying size, up
+to 16K. Each frame starts with a header that contains all information
+necessary to decode the frame.
+
 Meta data
 ~~~~~~~~~
 
 Meta data
 ~~~~~~~~~
 
@@ -1114,10 +1144,10 @@ title, album, year and comment tags. Each of these can only be at most
 32 characters long. ID3, version 2 is much more flexible but requires
 a separate library being installed for paraslash to support it.
 
 32 characters long. ID3, version 2 is much more flexible but requires
 a separate library being installed for paraslash to support it.
 
-Ogg vorbis files contain meta data as Vorbis comments, which are
-typically implemented as strings of the form "[TAG]=[VALUE]". Unlike
-ID3 version 1 tags, one may use whichever tags are appropriate for
-the content.
+Ogg vorbis, ogg speex and flac files contain meta data as Vorbis
+comments, which are typically implemented as strings of the form
+"[TAG]=[VALUE]". Unlike ID3 version 1 tags, one may use whichever
+tags are appropriate for the content.
 
 AAC files usually use the MPEG-4 container format for storing meta
 data while WMA files wrap meta data as special objects within the
 
 AAC files usually use the MPEG-4 container format for storing meta
 data while WMA files wrap meta data as special objects within the
@@ -1135,7 +1165,7 @@ paraslash uses the word "chunk" as common term for the building blocks
 of an audio file. For MP3 files, a chunk is the same as an MP3 frame,
 while for OGG files a chunk is an OGG page, etc.  Therefore the chunk
 size varies considerably between audio formats, from a few hundred
 of an audio file. For MP3 files, a chunk is the same as an MP3 frame,
 while for OGG files a chunk is an OGG page, etc.  Therefore the chunk
 size varies considerably between audio formats, from a few hundred
-bytes (MP3) up to 8K (WMA).
+bytes (MP3) up to 16K (FLAC).
 
 The chunk table contains the offsets within the audio file that
 correspond to the chunk boundaries of the file. Like the meta data,
 
 The chunk table contains the offsets within the audio file that
 correspond to the chunk boundaries of the file. Like the meta data,
@@ -1344,12 +1374,12 @@ REFERENCE(Forward error correction, FEC) below.
 Streams with headers and headerless streams
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Streams with headers and headerless streams
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-For ogg vorbis and wma streams, not all information needed to decode
-the stream is contained in each data chunk but only in the audio
-file header of the container format. Therefore clients must be able
-to obtain this information in case streaming starts in the middle of
-the file or if para_audiod is started while para_server is already
-sending a stream.
+For OGG/Vorbis, OGG/Speex and wma streams, some of the information
+needed to decode the stream is only contained in the audio file
+header of the container format but not in each data chunk. Clients
+must be able to obtain this information in case streaming starts in
+the middle of the file or if para_audiod is started while para_server
+is already sending a stream.
 
 This is accomplished in different ways, depending on the streaming
 protocol. For connection-oriented streams (HTTP, DCCP) the audio file
 
 This is accomplished in different ways, depending on the streaming
 protocol. For connection-oriented streams (HTTP, DCCP) the audio file
@@ -1428,8 +1458,7 @@ from being interpreted by para_recv.
 -> Create a minimal config for para_audiod for HTTP streams:
 
        c=$HOME/.paraslash/audiod.conf.min; s=server.foo.com
 -> Create a minimal config for para_audiod for HTTP streams:
 
        c=$HOME/.paraslash/audiod.conf.min; s=server.foo.com
-       formats="mp3 ogg aac wma" # remove what you do not have
-       for f in $formats; do echo receiver \"$f:http -i $s\"; done > $c
+       echo receiver \".:http -i $s\" > $c
        para_audiod --config $c
 
 -------
        para_audiod --config $c
 
 -------
@@ -1467,11 +1496,23 @@ the driving application (para_audiod or para_filter). Example:
        para_filter -f 'mp3dec --ignore-crc' -f 'compress --damp 1'
 
 For para_audiod, each audio format has its own set of filters. The
        para_filter -f 'mp3dec --ignore-crc' -f 'compress --damp 1'
 
 For para_audiod, each audio format has its own set of filters. The
-name of the audio format for which the filter should be applied is
-used as the prefix for the filter option. Example:
+name of the audio format for which the filter should be applied can
+be used as the prefix for the filter option. Example:
 
        para_audiod -f 'mp3:prebuffer --duration 300'
 
 
        para_audiod -f 'mp3:prebuffer --duration 300'
 
+The "mp3" prefix above is actually interpreted as a POSIX extended
+regular expression. Therefore
+
+       para_audiod -f '.:prebuffer --duration 300'
+
+activates the prebuffer filter for all supported audio formats (because
+"." matches all audio formats) while
+
+       para_audiod -f 'wma|ogg:prebuffer --duration 300'
+
+activates it only for wma and ogg streams.
+
 Decoders
 ~~~~~~~~
 
 Decoders
 ~~~~~~~~
 
@@ -1497,9 +1538,9 @@ Forward error correction
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 As already mentioned REFERENCE(Streaming protocols, earlier),
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 As already mentioned REFERENCE(Streaming protocols, earlier),
-paraslash uses forward error correction (FEC) for the unreliable
-UDP transport. FEC is a technique which was invented already in
-1960 by Reed and Solomon and which is widely used for the parity
+paraslash uses forward error correction (FEC) for the unreliable UDP
+and DCCP transports. FEC is a technique which was invented already
+in 1960 by Reed and Solomon and which is widely used for the parity
 calculations of storage devices (RAID arrays). It is based on the
 algebraic concept of finite fields, today called Galois fields, in
 honour of the mathematician Galois (1811-1832). The FEC implementation
 calculations of storage devices (RAID arrays). It is based on the
 algebraic concept of finite fields, today called Galois fields, in
 honour of the mathematician Galois (1811-1832). The FEC implementation
@@ -1526,7 +1567,7 @@ From these observations it is clear that there are three different
 FEC parameters: The slice size, the number of data slices k, and the
 total number of slices n. It is crucial to choose the slice size
 such that no fragmentation of network packets takes place because
 FEC parameters: The slice size, the number of data slices k, and the
 total number of slices n. It is crucial to choose the slice size
 such that no fragmentation of network packets takes place because
-FEC only guards against losses and reodering but fails if slices are
+FEC only guards against losses and reordering but fails if slices are
 received partially.
 
 FEC decoding in paralash is performed through the fecdec filter which
 received partially.
 
 FEC decoding in paralash is performed through the fecdec filter which
@@ -1628,12 +1669,12 @@ A paraslash writer acts as a data sink that consumes but does not
 produce audio data. Paraslash writers operate on the client side and
 are contained in para_audiod and in the stand-alone tool para_write.
 
 produce audio data. Paraslash writers operate on the client side and
 are contained in para_audiod and in the stand-alone tool para_write.
 
-The para_write program reads uncompressed 16 bit audio data from
-STDIN. If this data starts with a wav header, sample rate and channel
-count are read from the header. Otherwise CD audio (44.1KHz stereo)
-is assumed but this can be overridden by command line options.
-para_audiod, on the other hand, obtains the sample rate and the number
-of channels from the decoder.
+The para_write program reads uncompressed audio data from STDIN. If
+this data starts with a wav header, sample rate, sample format and
+channel count are read from the header. Otherwise CD audio (44.1KHz
+16 bit little endian, stereo) is assumed but this can be overridden
+by command line options. para_audiod, on the other hand, obtains
+the sample rate and the number of channels from the decoder.
 
 Like receivers and filters, each writer has an individual set of
 command line options, and for para_audiod writers can be configured
 
 Like receivers and filters, each writer has an individual set of
 command line options, and for para_audiod writers can be configured
@@ -1671,6 +1712,11 @@ write the PCM data to a file on the file system rather than playing
 it through a sound device. It is supported on all platforms and is
 always compiled in.
 
 it through a sound device. It is supported on all platforms and is
 always compiled in.
 
+*AO*. _Libao_ is a cross-platform audio library which supports a wide
+variety of platforms including PulseAudio (gnome), ESD (Enlightened
+Sound Daemon), AIX, Solaris and IRIX.  The ao writer plays audio
+through an output plugin of libao.
+
 Examples
 ~~~~~~~~
 
 Examples
 ~~~~~~~~
 
@@ -1783,11 +1829,6 @@ branches, below), the git source code management tool is used for
 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.
 
-ftp://ftp.gnu.org/pub/gnu/gengetopt/ (gengetopt). The C code for
-the command line parsers of all paraslash executables is generated
-by gengetopt. The generated C files are shipped in the tarballs but
-are not contained in the git repository.
-
 ftp://ftp.gnu.org/pub/gnu/m4/ (m4). Some input files for gengetopt
 are generated from templates by the m4 macro processor.
 
 ftp://ftp.gnu.org/pub/gnu/m4/ (m4). Some input files for gengetopt
 are generated from templates by the m4 macro processor.
 
@@ -1841,7 +1882,7 @@ New development does not usually happen on "master", however.
 Instead, a separate topic branch is forked from the tip of "master",
 and it first is tested in isolation; Usually there are a handful such
 topic branches that are running ahead of "master". The tip of these
 Instead, a separate topic branch is forked from the tip of "master",
 and it first is tested in isolation; Usually there are a handful such
 topic branches that are running ahead of "master". The tip of these
-branches is not published in the public repository, to keep the number
+branches is not published in the public repository to keep the number
 of branches that downstream developers need to worry about low.
 
 The quality of topic branches varies widely. Some of them start out as
 of branches that downstream developers need to worry about low.
 
 The quality of topic branches varies widely. Some of them start out as
@@ -1863,6 +1904,11 @@ have been merged into "next" are usually not rebased, and you can find
 the tip of topic branches you are interested in from the output of
 "git log next"). You should be able to safely build on top of them.
 
 the tip of topic branches you are interested in from the output of
 "git log next"). You should be able to safely build on top of them.
 
+However, at times "next" will be rebuilt from the tip of "master" to
+get rid of merge commits that will never be in "master". The commit
+that replaces "next" will usually have the identical tree, but it
+will have different ancestry from the tip of "master".
+
 The "pu" (proposed updates) branch bundles the remainder of the
 topic branches.  The "pu" branch, and topic branches that are only in
 "pu", are subject to rebasing in general.  By the above definition
 The "pu" (proposed updates) branch bundles the remainder of the
 topic branches.  The "pu" branch, and topic branches that are only in
 "pu", are subject to rebasing in general.  By the above definition
@@ -2020,7 +2066,7 @@ detection of duplicate or reordered packets. Being a connectionless
 protocol, only minimal internal state about the connection is
 maintained, which means that there is no protection against packet
 loss or network congestion. Error checking and correction (if at all)
 protocol, only minimal internal state about the connection is
 maintained, which means that there is no protection against packet
 loss or network congestion. Error checking and correction (if at all)
-are performed in the application.'
+are performed in the application.
 
 *DCCP*. The _Datagram Congestion Control Protocol_ combines the
 connection-oriented state maintenance known from TCP with the
 
 *DCCP*. The _Datagram Congestion Control Protocol_ combines the
 connection-oriented state maintenance known from TCP with the