task_register() conversion: writers

task_register() conversion: write task

task_register() conversion: i9e task

task_register() conversion: audioc task

task_register() conversion: filter tasks

task_register() conversion: stdin task

This renames stdin_set_defaults() to stdin_task_register() and changes
the function to register the stdin task. Before this patch, the task
was registered in the callers.

task_register() conversion: receivers

This adds a new public function, task_reap(), to sched.c. It is
called by para_audiod and para_play to free the memory occupied by
the receiver node after EOF. sched_shutdown() can not be used for
this purpose since the scheduler stays active during the life time of
these programs (i.e. schedule() never returns) while receiver nodes
come and go.

The new task_reap() has to face the problem that it is called
from another task's ->post_select() method, so removing the task
being reaped from the scheduler task list is not possible in
task_reap(). Hence this patch adds the new flag "dead" to struct
task. It is initially unset and is turned on in task_reap() to indicate
that (a) the task has exited (i.e. ->post_select() returned negative)
and (b) task_reap() has been called to fetch the exit status. Only
if this flag is set, the scheduler removes the task from the task list.

sched: Introduce alternative task API.

In the current implementation struct task is public so users of this
structure can mess with internal scheduler details as they please. This
has led to many bugs and questionable code in the past. This commit
is the first step to overcome this design mistake. At the end of this
patch series struct task can be made private to sched.c.

This commit introduces the following new public functions:

* task_register,
* task_context,
* sched_shutdown.

It also adds the new public task_info structure which carries the
information passed to the scheduler when a new task is registered. This
structure will stay public while struct task will become private once
all users have been converted.

task_register() is supposed to eventually replace register_task(). The
main difference of the two is that the new function returns a _pointer_
to a task structure which is allocated dynamically. Users are not
supposed to look at the fields of this pointer directly.

task_context() is a temporary helper which can be removed again at the
end of the series. Its sole purpose is to return the context pointer
which was passed at task register time as part of struct task_info.

The final new function, sched_shutdown(), deallocates the task
structures allocated during task_register() to cleanly shut down the
scheduler after all tasks have terminated.

All users need to be converted to the new API. This patch only converts
the stdout task though. The other tasks will be converted in subsequent
patches. The scheduler can tell if a task was registered using the
new API by means of the new ->owned_by_sched bit of struct task.
This boolean variable can also be removed after all tasks have been
converted.

Some users will need to query the exit status of a terminated
task. Hence we keep all tasks on the task list  after ->post_select()
returned negative but call neither ->pre_select() nor ->post_select()
any more for such tasks. This leads to the concept of zombie tasks.

sched: Mark argument of task_get_notification() as const.

We never write to the memory pointed to by the argument.

Simplify sched: Use only a single task list.

Currently the scheduler maintains two linked task lists, the pre_select
and the post_select list. This is completely unnecessary and bloats
the code for no good reason. This patch makes it use a single list
only and updates the documentation accordingly.

audiod: Simplify start_stop_decoders().

open_filters() DTRT if there are no filters configured.
No need to check twice.

Don't set t->error in ->pre_select().

->pre_select() methods should never fail, and tasks should not
set this variable at all. It is ignored anyway when set there.

afh_recv: Don't set t->error unnecessarily.

It is always wrong to set t->error directly as this can only confuse
the scheduler.

Merge branch 't/ao_fixes'

Cooking since 2014-03-22.

* t/ao_fixes:
  ao_write: Call ao_initialize() only once.
  ao_write: Join threads before returning an error from aow_post_select().
  ao_write: Simplify locking.
  Don't unlock and lock the thread mutex unnecessarily.
  ao_write: Check return value of pthread functions.
  ao_write: Avoid segfault on exit.
  ao_write: Avoid pthread_join().
  ao_write: Enforce a 20ms timeout.
  ao_write: Fix spurious segfault.

Merge branch 't/test_man'

Cooking since 2014-03-16.

* t/test_man:
  test-lib: Make colors work on FreeBSD.
  test suite: Add sanity check for generated man pages.

Merge branch 't/alsa_improvements'

Was cooking for almost two months.

* t/alsa_improvements:
  alsa: Remove pointless initialization.
  alsa_mix: Allow non-positive mixer values.
  alsa: New writer option: --buffer-time.
  alsa: Work around poll fd problems.
  alsa: Set period time.
  alsa: Also dump hardware params.
  alsa: Improve help text of --device.
  alsa: Improve documentation of struct private_alsa_write_data.
  alsa: Don't set t->error in ->pre_select().

Remove client_disconnect().

Everything this function does can be done as well when the task
terminates by returning negative in ->post_select().

This also avoids to leak the stream cipher structure of the previous
connection when running in interactive mode.

1,032 bytes in 1 blocks are definitely lost in loss record 61 of 85
   at 0x402994A: malloc (vg_replace_malloc.c:263)
   by 0x804C689: para_malloc (string.c:71)
   by 0x804FF87: sc_new (crypt.c:268)
   by 0x804E204: client_post_select (client_common.c:370)
   by 0x804D203: schedule (sched.c:59)
   by 0x804A2E7: main (client.c:500)

1,032 bytes in 1 blocks are definitely lost in loss record 62 of 85
   at 0x402994A: malloc (vg_replace_malloc.c:263)
   by 0x804C689: para_malloc (string.c:71)
   by 0x804FF87: sc_new (crypt.c:268)
   by 0x804E217: client_post_select (client_common.c:371)
   by 0x804D203: schedule (sched.c:59)
   by 0x804A2E7: main (client.c:500)

Fix memory leak in btr_splice_out_node().

Commit 072391fc (Improve btr_splice_out_node(), 2013-03) modified this
function to take a pointer to a buffer tree node pointer so that the
node pointer can be invalidated after it is spliced out. However, this
also means the caller can no longer free its resources. Hence we must
free the btrn in btr_splice_out_node() in order to avoid memory leaks.

Merge branch 't/rl_free_keymap'

Cooking since 2014-03-10.

* t/rl_free_keymap:
  build: Check whether rl_free_keymap is declared.

version.c: Fix year in version_text().

We want a single year here. The string got converted to a range by
mistake in commit 027f2c12.

flac afh: Fix off-by-one bug in meta_eof_cb().

After the full file has been read, the file position equals the number
of available bytes. The eof callback did not report EOF in this case.

wma afh: Read the description field as the comment tag.

The wma audio format handler parses the entries of the ASF content
description object and interprets its fifth field as the comment tag.

This is wrong, since this field actually corresponds to the rating
information, which is usually unused. The correct field to examine
is #4.

oggdec: Remove noisy debug message.

Also improve the comment for this code block.

reset version to 'git'

paraslash 0.5.2

Merge branch 't/oggdec_latency_improvements'

A single commit which was cooking since 2014-03-11.

* t/oggdec_latency_improvements:
  oggdec: Decode only OGGDEC_OUTPUT_CHUNK_SIZE many bytes per iteration.

Merge branch 't/opusdec_busy_loop_fix'

A single fix that was cooking since 2014-03-02.

* t/opusdec_busy_loop_fix:
  opusdec: Fix busy loop.

Revert "Add -Wdeclaration-after-statement."

This reverts commit cf517575ef0e501c963964ba4fd62aadaf795af8. It
broke our promise that paraslash still compiles with gcc-3.3.3.

ao_write: Call ao_initialize() only once.

It is possible that another instance of the ao writer is active
when aow_close() is called. Calling ao_shutdown() in ao_close()
might disturb the other instance and lead to a segmentation fault.

Fix this by calling ao_initialize() only once during aow_init()
and never call ao_shutdown() any more.

ao_write: Join threads before returning an error from aow_post_select().

This guarantees the play thread is not active any more in aow_close().

ao_write: Simplify locking.

Currently we lock the mutex at the beginnint of each iteration
of the main loop of aow_play() and drop the lock before calling
ao_play(). On errors we leave the loop either with the mutex locked
locked or unlocked, depending on the error condition that caused us
to break out of the loop.

This is unnecessarily complex. This patch simplifies the locking
by always leave the loop with the mutex locked.

Don't unlock and lock the thread mutex unnecessarily.

ao_write: Check return value of pthread functions.

Although pthread_cond_wait() and pthread_cond_signal() should never
fail on our setup, let's be conservative here and check the return
value anyway.

This patch also adds some comments and removes a few lines of code
which were commented out since day one of the ao writer.

ao_write: Avoid segfault on exit.

If para_audiod is terminated by a signal it calls the ->close() method
of each active writer. In this method the ao writer calls ao_close()
and frees all resources but leaves the play thread active. So the
thread continues to run, prints

ao_alsa ERROR: write error: File descriptor in bad state

and probably crashes afterwards due to accessing freed memory. Fix this
by cancelling the thread in ->close() if it exists. Ironically enough,
this re-introduces a call to pthread_join(), but it's OK here since
we the cancelled thread should exit immediately (so we don't block),
and we are about to exit anyway.

ao_write: Avoid pthread_join().

The call to pthread_join() may block for hundreds of milliseconds,
depending of the amount of buffered data. This is not acceptable in
a post_select hook. Among other problems this leads to an incorrect time
display and fake "time jump" warnings.

This patch drops the call to pthread_join() and makes ->post_select()
return non-negative until the play thread has terminated. In order to
have a way to tell if the thread is still running we let the thread
(i.e. aow_play()) remove its own buffer tree node on exit instead
of doing this in ->post_select() after pthread_join(). Hence if
->thread_btrn is NULL, we know the thread has terminated. It would
be easier to use pthread_tryjoin_np() but this would not be portable,
as this function is a non-standard GNU extension.

ao_write: Enforce a 20ms timeout.

Without this, the ao writer frequently complained about buffer
underruns.

ao_write: Fix spurious segfault.

Both btr_node_status() and btr_consume() access the buffer tree of
the ao writer, so these functions must be called with the pthread
mutex locked.

Merge branch 'maint'

audiod: Avoid segfault on exit.

When para_audiod terminates, it calls clean_exit() which closes
all slots unconditionally, regardless of whether they are in use.
This may lead to a segfault due to an invalid read:

==25253== Invalid read of size 4
==25253==    at 0x40EBEA: close_slot (audiod.c:443)
==25253==    by 0x40FCE8: clean_exit (audiod.c:1163)
==25253==    by 0x40FD7D: signal_post_select (audiod.c:1014)
==25253==    by 0x41490A: schedule (sched.c:65)
==25253==    by 0x406BC3: main (audiod.c:1436)
==25253==  Address 0x5c19d8 is not stack'd, malloc'd or (recently) free'd

This bug was introduced 9 month ago in commit eec23a69 (audiod:
Fix memory leak on exit: close slots). Fix it by calling
close_unused_slots(). This also simplifies clean_exit() a bit.

Merge branch 't/misc'

Various fixes, improvements, cleanups. Cooking since 2014-02-22.

* t/misc: (29 commits)
  build: Don't link with -lreadline if readline was not found.
  audiod: Skip NULL pointer check in compute_time_diff().
  audiod: Make compute_time_diff() return void.
  com_stat(): Remove pointless uptime variable.
  gcrypt: Fix gcc warning on Ubuntu Lucid.
  flac: Try to link also without -logg.
  version.c: Fix comment of version_single_line().
  doxygen: Expand all macros, in particular config.h.
  recv_common.c: Improve documentation of check_receiver_arg().
  audiod: get_time_string() comment fix.
  configure: Really print opus audio file handler if opus lib was found.
  Overhaul doxygen main page.
  afs.h: Don't try to list all supported audio formats.
  Change copyright year to 2014.
  Add link to sideband.h in doxygen main page.
  Doxify error2.c and add GPL header.
  Add -Wdeclaration-after-statement.
  Add some missing includes.
  Makefile.real: Add clean2 to the list of phony targets.
  mood.c: Fix a trivial whitespace issue.
  ...

Merge branch 't/fade_improvements'

Cooking since 2014-02-08.

* t/fade_improvements:
  fade: Improve error diagnostics.
  fade: Switch to the fade-in mood *before* sleeping.
  fade: Allow to set more than one channel in sleep mode.
  fade: Implement new mode "set".
  fade: Log to stderr.

Conflicts:
error.h

Merge branch 't/aes'

Cooking since 2014-02-02.

* t/aes:
  Implement aes_ctr128 and prefer it over RC4.
  server: Lookup user only once.

Merge branch 't/manual_improvements'

Cooking since 2014-01-25.

* t/manual_improvements:
  manual: Remove outdated sentence about para_afh.
  manual: Add description of ogg/opus.
  manual: Improve troubleshooting section.
  manual: Minor filter text improvement.

oggdec: Decode only OGGDEC_OUTPUT_CHUNK_SIZE many bytes per iteration.

This avoids buffer underruns on slow hardware and simplifies
ogg_post_select() a bit.

alsa: Remove pointless initialization.

The value stored in msg is never read. Found by the clang analyzer.

alsa_mix: Allow non-positive mixer values.

For the rpi the PCM range is from -10239 to 400. The math in
->set_mixer works fine for negative values.

alsa: New writer option: --buffer-time.

This removes the old way of setting of private_alsa_write_data->buffer_time

Currently we set the buffer time to the minimum of the maximum
buffer time and 500ms. This results in different values for different
hardware. In view of the introduction of the sync filter it seems to
be desirable to have more control over this value.

This patch adds the --buffer-time config option to the alsa
writer which allows to specify a suitable value, the default being
170ms. The unit of private_alsa_write_data->buffer_time is changed
from microseconds to milliseconds as this avoids to divide by 1000
in ->pre_select().

alsa: Work around poll fd problems.

In its ->pre_select method the alsa writer adds the alsa poll file
descriptor to the set of fds to be monitored during the next select
call. When this fd is ready for I/O, select() returns and ->post_select
is called. Currently ->post_select checks if the alsa poll fd is set
and returns early if it is not.

The problem is that on some hardware/kernel/alsa-lib combinations,
the poll fd is never marked as ready for I/O. This happens at least
on the raspberry pi with linux-3.10.10 and alsa-lib-1.0.27. The result
is no audio at all.

We address this problem in two ways:

* In alsa_init() we remember the buffer duration for later use in
->pre_select where we ask the scheduler to impose half of the duration
as an upper bound on the select timeout.

* In ->post_select, if there is input data available, we don't
check any more whether the poll fd is ready but try to write
unconditionally. On EAGAIN, we read from the poll fd to discard any
pending events.

alsa: Set period time.

This is probably not necessary, but since aplay from the alsa-utils
package sets it in the same way, it can't hurt to do this.

alsa: Also dump hardware params.

Since this makes the alsa output even more verbose, let's downgrade
the loglevel of config dump messages to DEBUG.

alsa: Improve help text of --device.

The new text gives the user a hint how to find out about the devices
ALSA knows about.

alsa: Improve documentation of struct private_alsa_write_data.

Remove the stale reference to writer node groups and explain how
sample_rate and channel count are determined.

alsa: Don't set t->error in ->pre_select().

->pre_select() methods should never fail, and tasks should not
set this variable at all. It is ignored anyway when set there.

Merge branch 't/cmd_improvements'

Cooking since 2014-01-16.

* t/cmd_improvements:
  afs.cmd: Strip redundant "sort" from ls help output.
  audiod.cmd: Improve grab client help text.
  afs.cmd: Improve second level indenting.
  afd.cmd: Fix a trivial whitespace issue.

build: Check whether rl_free_keymap is declared.

Readline versions up to and including 6.2 miss to declare the public
symbol rl_free_keymap(). We currently work around this issue by
manually declaring the function in interactive.c.

The recently released readline-6.3, however, does declare that symbol.
Since we compile with -Wredundant-decls this leads to the following
warning:

interactive.c:239:6: warning: redundant redeclaration of 'rl_free_keymap' [-Wredundant-decls]
 void rl_free_keymap(Keymap keymap);

This patch gets rid of the warning by adding a check to configure.ac
which detects whether the symbol is declared in the readline header
file. Only if it is uncdelared we declare it manually as before.

opusdec: Fix busy loop.

This braino caused the opus decoder to request a minimal timeout
most of the time.

The bug was introduced 2013-09 in commit 14c16b65.

Merge branch 't/sync'

Cooking since 2014-01-14.

* t/sync:
  The sync filter.
  net: Let maksock() callers perform flowopt cleanup.
  net: makesock_addrinfo(): Make socketfd local to the loop.
  net: Let makesock() continue on setsockopt() failure.
  net: Reduce indentation level in makesock_addrinfo().
  net: Further simplify makesock_addrinfo().
  net: Replace the double loop of lookup_address() by a single loop.
  net: makesock(): Combine code for passive sockets.
  net: Change makesock_addrinfo() to set given flowopts before SO_REUSEADDR.
  net: Clarify code flow of makesock_addrinfo().
  net: Remove unnecessary condition in makesock_addrinfo().
  net: Remove pointless initialization in makesock_addrinfo().
  net: Kill dead code in makesock_addrinfo().
  net: Remove networking headers from para.h.
  net: Improve error handling of makesock_addrinfo().
  net: Split makesock(), part 2: Introduce makesock_addrinfo().
  net: Split makesock(), part 1: Introduce lookup_address().
  net: Simplify makesock().
  net: Fix parse_url().
  net: Correct \return text of parse_url().

build: Don't link with -lreadline if readline was not found.

Currently, if libreadline is not installed, linking fails with

ld: cannot find -lreadline

This patch makes the build succeed by linking para_client, para_audioc
and para_play without readline support in this case.

audiod: Skip NULL pointer check in compute_time_diff().

We never pass a NULL pointer to this function.

audiod: Make compute_time_diff() return void.

Its single caller does not care about the return value.

com_stat(): Remove pointless uptime variable.

This variable is set but the content is never used. Drop it.

gcrypt: Fix gcc warning on Ubuntu Lucid.

For some reason the gcc-4.4.3 that ships with Ubuntu Lucid started
to complain recently:

gcrypt.c: In function ‘mgf1’:
gcrypt.c:101: warning: ISO C90 forbids mixed declarations and code

It turned out that a double semicolon is responsible for the
warning. This patch removes the duplicate.

flac: Try to link also without -logg.

If libflac was compiled without ogg support, the build system should
include flac even if libogg is not installed. Currently this does
not work because the autoconf test tries to link with -logg, so it
always fails if libogg is not available.

Fix this by trying both with and without libogg.

version.c: Fix comment of version_single_line().

Codenames are no longer used.

doxygen: Expand all macros, in particular config.h.

This improves the generated documentation web pages since now all
HAVE_XXX macros of config.h are taken into account.

recv_common.c: Improve documentation of check_receiver_arg().

Drop meaningless "and further are present", and note that the "real"
type of the returned pointer depends on the receiver.

audiod: get_time_string() comment fix.

configure: Really print opus audio file handler if opus lib was found.

This is the second time this bug shows up. It was fixed ad0da073 but
re-introduced in the merge commit b5c6af5c. See also 40439a77.

Overhaul doxygen main page.

It got way too large, and contained quite a few links to .c files
whose doxygen page is not very interesting. For example, the doxygen
page of the .c files of filters, receivers and writers contain only
the init function since all other functions are static.

This commit limits the number of links on the main page considerably.
The new page tries to focus on important data structures and APIs
and does not strive for completeness.

afs.h: Don't try to list all supported audio formats.

Change copyright year to 2014.

This year, we're really on time. The changes in this patch were
created by the following silly script:

    files=$(git grep -l 'Copyright (C) [0-9]\{4\}\(-2013\)* Andre Noll')
    sed --in-place= -e 's/Copyright (C) \([0-9]\{4\}\)-2013 Andre Noll/Copyright (C) \1-2014 Andre Noll/1' $files
    sed --in-place= -e 's/Copyright (C) 2013 Andre Noll/Copyright (C) 2013-2014 Andre Noll/1' $files

Add link to sideband.h in doxygen main page.

It is an essential part of the client/server communication, and is
well documented to boot.

Doxify error2.c and add GPL header.

Also add a link to the file in the doxygen main page.

Add -Wdeclaration-after-statement.

We don't have (and don't want to have) declarations after
statements. This change helps to keep it this way.

Add some missing includes.

Letting .c files include their "own" header file guarantees that the
declaration in the header file stays in sync with the definition.

Eventually we may even enable gcc's -Wmissing-declarations, but
we're not there yet, mainly due to command handlers, init functions
and completers.

Note that including signal.h in signal.c required two other includes
since the header file defines a task structure.

Makefile.real: Add clean2 to the list of phony targets.

We don't want to create a file named clean2.

mood.c: Fix a trivial whitespace issue.

Provide new screenshots.

The old ones were more than 4 years old. There is no huge difference though.

Remove old changelog files.

This simplifies Makefile.real a bit, and of course it's still in the
git history in case somebody is really that interested in the ancient
history of this project.

Remove convert_0.3-0.4.sh.

The database layout hasn't changed since 0.4.0, and nobody should
run paraslash-3.x.x anymore.

Rename command_util.sh -> command_util.bash.

It's a bash script which wouldn't run properly under general POSIX
shells.

Remove __malloc attribute from para_realloc().

This attribute tells the compiler that the returned pointer cannot
alias any other pointer. This is not the case for para_realloc().

web: Remove "/" character in <br> elements.

'br' is an empty element, i.e., it can take no content and it may not
have an end tag.  Indeed, the W3C Markup Validation Service complains
about this:

Line 33, Column 42: NET-enabling start-tag requires SHORTTAG YES

This bug was introduced in commit 607d79aa (web: Unify <br>
elements. 2013-08).

NEWS: Add download links for 0.5.1.

This should have been done in the release commit of course.

Remove trailing dot at the end of purpose texts.

This looks ugly in the man pages where the purpose is listed in
parentheses. Most of these texts are not even full sentences.

Include options for receivers/filters/writer in man pages

This broke in v0.5.0 when we started to create the man pages in a
way that works also in a cross-compile setup.

This fix introduces a new script man_util.bash which does the real
work and hides all the ugliness from the Makefiles.

gui: Don't ignore SIGHUP.

It results in para_gui eating 100% CPU if the terminal window is
closed. Not ignoring the signal makes para_gui die instead.

This bug was present since "day 1".

Merge branch 'refs/heads/t/clang_warning_fixes'

Was cooking since 2014-01-14.

1b9e28 command.c: Silence clang warning.
994e72 udp_recv: Fix clang warning.
c853e7 aac_afh: Fix clang warning.

test-lib: Make colors work on FreeBSD.

Some implementations of tput don't accept capnames (bold, setaf,
sgr0) but only the older termcap capability names (md, AF, me). This
patch teaches test-lib.sh to try both variants and succeed if either
variant works.

fade: Improve error diagnostics.

This adds a new generic error code "invalid mixer channel", which is
returned from both ALSA and OSS in case the specified mixer channel
could not be set.

Prior to this patch, ALSA would return a bad channel error also when
the given value was out of range. This is fixed by replacing the now
unused ALSA_MIX_BAD_ELEM error code by the new ALSA_MIX_RANGE code.

Finally, para_fade is changed to no longer print the list of available
channels after it failed to set the initial mode.

fade: Switch to the fade-in mood *before* sleeping.

This way the fade-in mood is active when para_fade is interrupted
during the sleep.

Currently sweet_dreams() calls change_afs_mode_and_play(),
which switches to a different mood and changes the mood directly
thereafter. For the new sematics we need to separate the two
actions though. Hence change_afs_mode_and_play() is renamed to
change_afs_mode(), and it now performs the mood switching part
only. Its two callers are modified to call client_cmd("play")
themselves.

This allows to call change_afs_mode() before we go to sleep and
client_cmd("play") on wake up.

fade: Allow to set more than one channel in sleep mode.

This makes --ivol a string option which may be specified multiple
times, each with its own channel:value pair. The channel part is
optional, invalid channels are ignored.

This change retains backwards-compatibility, i.e. providing a single
value without "channel:" prefix still works as before.

Unfortunately the patch is a bit large since set_channel() had to be
moved to the top of fade.c. This function grew another argument to
specify the channel to set.

test suite: Add sanity check for generated man pages.

The build system of v0.5.0 and v0.5.1 missed to include options for
receivers, filters and writers.  The new test makes sure this never
happens again.

Implement aes_ctr128 and prefer it over RC4.

This adds the aes_ctr128 stream cipher to para_server, para_client
and para_audiod. para_server now announces this cipher as a supported
feature and para_client requests an aes_ctr128-encrypted session
if the server supports it. If one or both sides don't understand
the new feature, the RC4 fallback applies. So this change is
backwards-compatible.

Both gcrypt and openssl support aes_ctr128, and the two implementations
are compatible to each other: a para_client linked against openssl can
talk to a para_server which was linked against libgcrypt and vice versa.

This patch also updates the documentation to talk about stream
ciphers and session keys rather than to mention RC4 explicitly. A
short section on AES is added which also explains how counter mode
turns a block cipher into a stream cipher.

manual: Remove outdated sentence about para_afh.

Commit 06f33ca1 (2011-08) removed the streaming mode of para_afh,
but the documentation was not updated to reflect this change.

manual: Add description of ogg/opus.

Also mention in the speex section that speex was obsoleted by opus.

manual: Improve troubleshooting section.

These days all para_* commands support --help and --detailed-help.
Also add a note how to restart para_audiod after a crash.

afs.cmd: Strip redundant "sort" from ls help output.

The sentences before this table make it clear that these options
change the sort order.

audiod.cmd: Improve grab client help text.

The shortened text does not mention file descriptors any more, it
should be easier to understand.

Also reformat the text slightly.

afs.cmd: Improve second level indenting.

Currently we have an empty line between each item, mainly to make sure
that man pages including the html version look nice. However, indenting
by spaces and dropping the empty lines looks better in the plaintext
version (help output) while still keeping help2man and man2html happy.