--- Begin Message ---
Package: esound-clients
Version: 0.2.29-1
Severity: normal
Tags: upstream, patch
On a Sarge system (not the one where I'm writing this), I noticed a
number of problems with the documentation;
- The synopsis line on most of the pages is just "Enlightened Sound
Daemon" and doesn't tell you at all what the particular utility is
for;
- There are various POD formatting problems in the source;
- A couple of the pages seem to be nothing but boilerplate, and at
that, possibly incorrect boilerplate for the application at hand;
- Various minor wording fibs etc
I have attempted to correct these. Please consider the attached patch
for inclusion into the next stable release of Debian, but please note
that a few of the pages now will not even try to appear authoritative.
I figured it would be better to tell the truth than to be misleading.
I removed references to esd-config from all pages except esd(1);
perhaps this would suffice to close bug #204262
I notice that upstream 0.2.34 no longer (?) ships PODs but only the
.1.in versions of the manual pages. This is unfortunate as it would
appear that the POD versions were used to produce these. Anyhow, it
looked -- based on a brief examination of a few of the files -- that
upstream is still shipping exactly the same documentation as you have
apart from some very minor updates to the OPTIONS section of esd.1.in
Thank you for your time and attention,
/* era */
diff -urN esound-0.2.29.orig/docs/esd-config.pod
esound-0.2.29/docs/esd-config.pod
--- esound-0.2.29.orig/docs/esd-config.pod 2004-06-18 08:08:35.000000000
+0300
+++ esound-0.2.29/docs/esd-config.pod 2004-06-18 08:27:00.000000000 +0300
@@ -1,34 +1,55 @@
=head1 NAME
-esd-config - The Enlightened Sound Daemon
+esd-config - configuration tool for linking against esd
=head1 DESCRIPTION
-esd-config is a tool that is used to configure to deter
-mine the compiler and linker flags that should be used to
-compile and link programs that use EsounD. It is also used
-internally to the .m4 macros for GNU autoconf that are
+B<esd-config> is a tool which is used by B<configure> to
+determine the compiler and linker flags that should be used to
+compile and link programs that use EsounD. It is also used
+internally by the B<m4> macros for GNU B<autoconf> that are
included with EsounD.
=head1 USAGE
-esd-config [--prefix[=DIR]] [--exec-prefix[=DIR]] [--version] [--libs]
[--cflags]
+esd-config
+[--prefix[=DIR]]
+[--exec-prefix[=DIR]]
+[--version]
+[--libs]
+[--cflags]
-B<--version> Print the currently installed version of EsounD on the standard
output.
+=over 2
-B<--libs> Print the linker flags that are necessary to link an EsounD
program.
+=item B<--version>
-B<--cflags> Print the compiler flags that are necessary to compile an EsounD
program.
+Print the currently installed version of EsounD on the standard output.
-B<--prefix=PREFIX> If specified, use PREFIX instead of the installation
prefix that EsounD was
-built with when computing the output for the --cflags and --libs options.
-This option is also used for the exec prefix if --exec-prefix was not
-specified. This option must be specified before any --libs or --cflags options.
+=item B<--libs>
-B<--exec-prefix=PREFIX> If specified, use PREFIX instead of the installation
+Print the linker flags that are necessary to link an EsounD program.
+
+=item B<--cflags>
+
+Print the compiler flags that are necessary to compile an EsounD program.
+
+=item B<--prefix=PREFIX>
+
+If specified, use PREFIX instead of the installation prefix that EsounD was
+built with when computing the output for the B<--cflags> and B<--libs> options.
+This option is also used for the exec prefix if B<--exec-prefix> was not
+specified. This option must be specified before any B<--libs> or
+B<--cflags> options.
+
+=item B<--exec-prefix=PREFIX>
+
+If specified, use PREFIX instead of the installation
exec prefix that EsounD was built with when computing the output for the
---cflags and --libs options. This option must be specified before any --libs
-or --cflags options.
+B<--cflags> and B<--libs> options.
+This option must be specified before any B<--libs>
+or B<--cflags> options.
+
+=back
=head1 SEE ALSO
diff -urN esound-0.2.29.orig/docs/esd.pod esound-0.2.29/docs/esd.pod
--- esound-0.2.29.orig/docs/esd.pod 2004-06-18 08:08:35.000000000 +0300
+++ esound-0.2.29/docs/esd.pod 2004-06-18 08:22:11.000000000 +0300
@@ -10,53 +10,79 @@
esd [options]
- -d DEVICE force esd to use sound device DEVICE
- -b run server in 8 bit sound mode
- -r RATE run server at sample rate of RATE
- -as SECS free audio device after SECS of inactivity
- -unix use unix domain sockets instead of tcp/ip
- -tcp use tcp/ip sockets instead of unix domain
- -public make tcp/ip access public (other than localhost)
- -terminate terminate esd daemone after last client exits
- -nobeeps do not play startup beeps
- -port PORT listen for connections at PORT (only for tcp/ip)
+=over 4
+=item B<-d I<DEVICE>>
-Possible devices are: /dev/dsp, /dev/dsp2, etc.
+Force esd to use sound device I<DEVICE>.
-=head1 FILES
+Possible devices are F</dev/dsp>, F</dev/dsp2>, etc.
-/etc/esound/esd.conf daemon configuration file
+=item B<-b>
-/etc/esound/esd.conf is a file of key=value pairs. There may also be a section
-delimiter to placate gnome_config. There are three options:
+Run server in 8-bit sound mode.
-=head2 auto_spawn
+=item B<-r I<RATE>>
-=over
+Run server at sample rate of I<RATE>.
-0 or 1 indicating whether the esd library should automatically spawn a
-daemon if one is not running when a sound is played. This option is
-not recommended for Gnome users who have enabled sound for events in
-Gnome.
+=item B<-as I<SECS>>
-=back
+Free audio device after SECS of inactivity.
+
+=item B<-unix>
+
+Use Unix domain sockets instead of TCP/IP.
+
+=item B<-tcp>
+
+Use TCP/IP sockets instead of UNIX domain sockets. (Default)
+
+=item B<-public>
+
+Make TCP/IP access public (other than localhost).
+
+=item B<-terminate>
+
+Terminate ESD daemon after last client exits.
-=head2 spawn_options
+=item B<-nobeeps>
-=over
+Do not play startup beeps.
-a string with the command line to be passed to esd when it is
-automatically spawned by the library
+=item B<-port I<PORT>>
+
+Listen for connections on PORT (only for TCP/IP).
=back
-=head2 spawn_wait_ms
+=head1 FILES
+
+F</etc/esound/esd.conf> is a the configuration file
+for the EsounD daemon. It is read by the daemon at startup.
+
+The file should contain key=value pairs.
+There may also be a section delimiter to placate B<gnome_config>.
+There are three options (keys):
+
+=over 2
+
+=item B<auto_spawn>
+
+0 or 1 indicating whether the esd library should automatically spawn a
+daemon if one is not running when a sound is played. This option is
+not recommended for Gnome users who have enabled sound for events in
+Gnome.
+
+=item B<spawn_options>
+
+A string with the command line to be passed to esd when it is
+automatically spawned by the library.
-=over
+=item B<spawn_wait_ms>
-the number of miliseconds to wait for the daemon to successfully
-start. If the daemon is not started by the timeout, the application
+The number of miliseconds to wait for the daemon to successfully
+start. If the daemon is not started within the timeout, the application
will act as if the audio open failed.
=back
diff -urN esound-0.2.29.orig/docs/esdcat.pod esound-0.2.29/docs/esdcat.pod
--- esound-0.2.29.orig/docs/esdcat.pod 2004-06-18 08:08:35.000000000 +0300
+++ esound-0.2.29/docs/esdcat.pod 2004-06-18 08:30:36.000000000 +0300
@@ -1,16 +1,18 @@
=head1 NAME
-esdcat - The Enlightened Sound Daemon
+esdcat - send a file or stream to the sound device using esd
=head1 DESCRIPTION
-esdcat pipes data from a pipe to the sound device
+B<esdcat> pipes data from a pipe to the sound device.
=head1 USAGE
-esdcat [C<-s> server] [C<-b>] [C<-m>] [C<-r> freq] < file
+esdcat [-s server] [-b] [-m] [-r freq] < I<file>
+
+See the esd(1) manual page for the meaning of the common options.
=head1 SEE ALSO
esd(1), esddsp(1), esdfilt(1), esdloop(1), esdplay(1), esdsample(1),
-esd-config(1), esdctl(1), esdmon(1), esdrec(1)
+esdctl(1), esdmon(1), esdrec(1)
diff -urN esound-0.2.29.orig/docs/esdctl.pod esound-0.2.29/docs/esdctl.pod
--- esound-0.2.29.orig/docs/esdctl.pod 2004-06-18 08:08:35.000000000 +0300
+++ esound-0.2.29/docs/esdctl.pod 2004-06-18 08:38:59.000000000 +0300
@@ -1,39 +1,107 @@
=head1 NAME
-esdctl - The Enlightened Sound Daemon
+esdctl - control the Enlightened Sound Daemon
=head1 DESCRIPTION
-Command-line control program for EsounD
+Command-line control program for EsounD.
=head1 USAGE
esdctl [options] [command]
-options:
-S<C<-s>, --server=host:port contact esd server on host at port>
+=head2 OPTIONS
-commands:
+=over 4
- lock foreign clients may not use the server
- unlock foreign clients may use the server
- standby, off suspend sound output for other programs
- resume, on resume sound output
- cache sample cache a sample in the server
- getid name retrieve a sample id from its name
- free name uncache a sample in the server
- play name play a cached sample once
- loop name make a cached sample loop
- stop name stop the looping sample at end
- serverinfo get server info from server
- allinfo get player and sample info from server
- panstream id left right set panning for a stream
- pansample id left right set default panning for a sample
- - left/right pan values scaled to 256.
- standbymode see if server's on standby, etc.
+=item B<-s>
+
+=item B<--server>=I<host:port>
+
+Contact esd server on I<host> at I<port>
+
+=back
+
+=head2 COMMANDS
+
+=over 12
+
+=item B<lock>
+
+Foreign clients may not use the server.
+
+=item B<unlock>
+
+Foreign clients may use the server.
+
+=item B<standby>
+
+=item B<off>
+
+Suspend sound output for other programs.
+
+=item B<resume>
+
+=item B<on>
+
+Resume sound output.
+
+=item B<cache> I<sample>
+
+Cache a sample in the server.
+
+=item B<getid> I<name>
+
+Retrieve a sample id from its name.
+
+=item B<free> I<name>
+
+Uncache a sample in the server.
+
+=item B<play> I<name>
+
+Play a cached sample once.
+
+=item B<loop> I<name>
+
+Make a cached sample loop.
+
+=item B<stop> I<name>
+
+Stop the looping sample at end.
+
+=item B<serverinfo>
+
+Get server info from server.
+
+=item B<allinfo>
+
+Get player and sample info from server.
+
+=item B<panstream> I<id> I<left> I<right>
+
+Set panning for a stream.
+
+Left/right pan values are scaled to 256.
+
+=item B<pansample> I<id> I<left> I<right>
+
+Set default panning for a sample.
+
+Left/right pan values are scaled to 256.
+
+=item B<standbymode>
+
+See if server is on standby, etc.
+
+=back
=head1 SEE ALSO
esd(1), esdcat(1), esddsp(1), esdloop(1), esdplay(1), esdsample(1),
-esd-config(1), esdfilt(1), esdmon(1), esdrec(1)
+esdfilt(1), esdmon(1), esdrec(1)
+
+=cut
+######## FIXME: check that panstream and pansample are correct
+######## FIXME: what does "scaled to 256" mean?
diff -urN esound-0.2.29.orig/docs/esddsp.pod esound-0.2.29/docs/esddsp.pod
--- esound-0.2.29.orig/docs/esddsp.pod 2004-06-18 08:08:35.000000000 +0300
+++ esound-0.2.29/docs/esddsp.pod 2004-06-18 08:42:21.000000000 +0300
@@ -4,21 +4,53 @@
=head1 DESCRIPTION
-esddsp can allow non-esd applications to be routed through esd.
+B<esddsp> can allow non-esd applications to be routed through esd.
=head1 USAGE
-esddsp [options] player arguments
+esddsp [options] I<player> I<arguments ...>
-options:
+Options:
- -h, --help show brief help
- -s, --server=HOST:PORT contact esd server on host at port
- -m, --mixer enable mixer support
- -n, --name=NAME use name to identify player to esd
- -v, --verbose show parameters
+=over 4
+
+=item B<-h>
+
+=item B<--help>
+
+Show brief help.
+
+=item B<-s>
+
+=item B<--server>=I<HOST>:I<PORT>
+
+Contact esd server at I<HOST> on I<PORT>.
+
+=item B<-m>
+
+=item B<--mixer>
+
+Enable mixer support.
+
+=item B<-n>
+
+=item B<--name>=I<NAME>
+
+Use I<NAME> to identify player to esd.
+
+=item B<-v>
+
+=item B<--verbose>
+
+Show parameters.
+
+=back
=head1 SEE ALSO
+esdmon(1)
+
esd(1), esdcat(1), esdloop(1), esdplay(1), esdsample(1),
-esd-config(1), esdctl(1), esdfilt(1), esdmon(1), esdrec(1)
+esdctl(1), esdfilt(1), esdrec(1)
+
+vsound(1)
diff -urN esound-0.2.29.orig/docs/esdfilt.pod esound-0.2.29/docs/esdfilt.pod
--- esound-0.2.29.orig/docs/esdfilt.pod 2004-06-18 08:08:35.000000000 +0300
+++ esound-0.2.29/docs/esdfilt.pod 2004-06-18 08:45:11.000000000 +0300
@@ -1,27 +1,50 @@
=head1 NAME
-esdfilt - The Enlightened Sound Daemon
+esdfilt - sample filters for esd
=head1 DESCRIPTION
EsounD filter. Sample esd filter program that implements halving and doubling,
-Optionally writing the new data to a seperate file.
+optionally writing the new data to a separate file.
=head1 USAGE
esdfilt [OPTIONS] [FILE]
-C<-s>, --server=HOSTNAME set EsounD server
-C<-b>, output file should be 8-bit
-C<-m>, output file should be mono
-C<-r> RATE, set output rate to RATE
-C<-half> halve each sample
-C<-double> double each sample
+=over 4
-If FILE is specified, the filtered output will be written there. Otherwise
+=item B<-s>
+
+=item B<--server>=I<HOSTNAME>
+
+Set EsounD server to I<HOSTNAME>.
+
+=item B<-b>
+
+Output file should be 8-bit.
+
+=item B<-m>
+
+Output file should be mono.
+
+=item B<-r> I<RATE>
+
+Set output rate to I<RATE>.
+
+=item B<-half>
+
+Halve each sample.
+
+=item B<-double>
+
+Double each sample.
+
+=back
+
+If I<FILE> is specified, the filtered output will be written there. Otherwise
it will be written back to esound to change the output to the sound device.
=head1 SEE ALSO
esd(1), esdcat(1), esddsp(1), esdloop(1), esdplay(1), esdsample(1),
-esd-config(1), esdctl(1), esdmon(1), esdrec(1)
+esdctl(1), esdmon(1), esdrec(1)
diff -urN esound-0.2.29.orig/docs/esdloop.pod esound-0.2.29/docs/esdloop.pod
--- esound-0.2.29.orig/docs/esdloop.pod 2004-06-18 08:08:35.000000000 +0300
+++ esound-0.2.29/docs/esdloop.pod 2004-06-18 08:48:13.000000000 +0300
@@ -1,17 +1,22 @@
=head1 NAME
-esdloop - The Enlightened Sound Daemon
+esdloop - esd test scaffolding for sample cache, loop, and free
=head1 DESCRIPTION
-esdloop is test scaffolding for sample cache, loop, and free.
+######## XXX FIXME: add a description here
=head1 USAGE
-esdloop [C<-s> server ] [C<-b>] [C<-m>] [C<-r> freq] < file
+esdloop [B<-s> server ] [B<-b>] [B<-m>] [B<-r> freq] < I<file>
=head1 SEE ALSO
esd(1), esdcat(1), esddsp(1), esdplay(1), esdsample(1),
-esd-config(1), esdctl(1), esdfilt(1), esdmon(1), esdrec(1)
+esdctl(1), esdfilt(1), esdmon(1), esdrec(1)
+=cut
+
+######## TODO: this needs elaboration!
+######## What does esdloop in fact do?
+######## What are sample cache, loop, and free?
diff -urN esound-0.2.29.orig/docs/esdmon.pod esound-0.2.29/docs/esdmon.pod
--- esound-0.2.29.orig/docs/esdmon.pod 2004-06-18 08:08:35.000000000 +0300
+++ esound-0.2.29/docs/esdmon.pod 2004-06-18 08:57:10.000000000 +0300
@@ -1,6 +1,6 @@
=head1 NAME
-esdmon - The Enlightened Sound Daemon
+esdmon - duplicate the esd sound stream to another file or device
=head1 DESCRIPTION
@@ -13,15 +13,35 @@
Options:
-C<-s>, --server=HOSTNAME set EsounD server
-C<-b>, output file should be 8-bit
-C<-m>, output file should be mono
-C<-r> RATE, set output rate to RATE
+=over 4
-FILE is the file to write the output stream to. Default is stdout.
+=item B<-s>
+
+=item B<--server>=I<HOSTNAME>
+
+Set EsounD server to I<HOSTNAME>.
+
+=item B<-b>
+
+Output file should be 8-bit.
+
+=item B<-m>
+
+Output file should be mono.
+
+=item B<-r> I<RATE>
+
+Set output rate to I<RATE>.
+
+=back
+
+I<FILE> is the file to write the output stream to. Default is stdout.
=head1 SEE ALSO
-esd(1), esdcat(1), esddsp(1), esdloop(1), esdplay(1), esdsample(1),
-esd-config(1), esdctl(1), esdfilt(1), esdrec(1)
+esddsp(1)
+
+esd(1), esdcat(1), esdloop(1), esdplay(1), esdsample(1),
+esdctl(1), esdfilt(1), esdrec(1)
+vsound(1)
diff -urN esound-0.2.29.orig/docs/esdplay.pod esound-0.2.29/docs/esdplay.pod
--- esound-0.2.29.orig/docs/esdplay.pod 2004-06-18 08:08:35.000000000 +0300
+++ esound-0.2.29/docs/esdplay.pod 2004-06-18 09:09:28.000000000 +0300
@@ -4,23 +4,39 @@
=head1 DESCRIPTION
-Plays the FILE with EsounD.
+Plays a file with EsounD.
=head1 USAGE
esdplay [OPTIONS] [FILE]
-Plays from standard in if FILE is not specified or is "-"
+Plays from standard inpuy if I<FILE> is not specified or is F<->.
Options:
-C<-s>, --server=HOSTNAME set EsounD server
+=over 4
-C<-h>, --help display this help and exit
+=item B<-s>
-C<-v>, --version output version information and exit
+=item B<--server>=I<HOSTNAME>
+
+Set EsounD server to I<HOSTNAME>.
+
+=item B<-h>
+
+=item B<--help>
+
+Display this help and exit.
+
+=item B<-v>
+
+=item B<--version>
+
+Output version information and exit.
+
+=back
=head1 SEE ALSO
esd(1), esdcat(1), esddsp(1), esdloop(1), esdsample(1),
-esd-config(1), esdctl(1), esdfilt(1), esdmon(1), esdrec(1)
+esdctl(1), esdfilt(1), esdmon(1), esdrec(1)
diff -urN esound-0.2.29.orig/docs/esdrec.pod esound-0.2.29/docs/esdrec.pod
--- esound-0.2.29.orig/docs/esdrec.pod 2004-06-18 08:08:35.000000000 +0300
+++ esound-0.2.29/docs/esdrec.pod 2004-06-18 09:11:17.000000000 +0300
@@ -1,6 +1,6 @@
=head1 NAME
-esdrec - The Enlightened Sound Daemon
+esdrec - esd recorder
=head1 DESCRIPTION
@@ -8,10 +8,16 @@
=head1 USAGE
-esdrec [C<-s> server] [C<-b>] [C<-m>] [C<-r> freq] < file
+esdrec [B<-s> I<SERVER>] [B<-b>] [B<-m>] [B<-r> I<FREQ>] < I<FILE>
+
+See esd(1) for the meaning of the options.
=head1 SEE ALSO
esd(1), esdcat(1), esddsp(1), esdloop(1), esdplay(1), esdsample(1),
-esd-config(1), esdctl(1), esdfilt(1), esdmon(1)
+esdctl(1), esdfilt(1), esdmon(1)
+
+=cut
+######## XXX FIXME: does this actually record from a file!?
+######## FIXME: or is this all just incorrect boilerplate?
diff -urN esound-0.2.29.orig/docs/esdsample.pod esound-0.2.29/docs/esdsample.pod
--- esound-0.2.29.orig/docs/esdsample.pod 2004-06-18 08:08:35.000000000
+0300
+++ esound-0.2.29/docs/esdsample.pod 2004-06-18 09:12:38.000000000 +0300
@@ -1,17 +1,22 @@
=head1 NAME
-esdsample - The Enlightened Sound Daemon
+esdsample - esd sampler
=head1 DESCRIPTION
-EsounD sampler
+######## XXX FIXME: add a description here
=head1 USAGE
-esdsample [C<-s> server] [C<-d> [C<-b>] [C<-m>] [C<-r> freq]] < file
+esdsample [B<-s> I<SERVER>] [B<-d> [B<-b>] [B<-m>] [B<-r> I<FREQ>]] < I<FILE>
+
+See esd(1) for the meaning of the options.
=head1 SEE ALSO
esd(1), esdcat(1), esddsp(1), esdloop(1), esdplay(1),
-esd-config(1), esdctl(1), esdfilt(1), esdmon(1), esdrec(1)
+esdctl(1), esdfilt(1), esdmon(1), esdrec(1)
+
+=cut
+######## XXX FIXME: is this correct at all?
-- System Information
Debian Release: 3.0
Kernel Version: Linux back 2.4.18-bf2.4 #1 Son Apr 14 09:53:28 CEST 2002 i586
unknown
--- End Message ---
