There are two lines of actual description in the esd (Enlightened Sound Daemon) manual page. I know this is not useful or constructive criticism– and I don’t know enough about how they’re supposed to work to begin to help with these documents. I just want to point out a bad example for you to avoid emulating as you go about your own development.
DESCRIPTION
esdcat pipes data from a pipe to the sound device
USAGE
esdcat [“-s” server] [“-n” name] [“-b”] [“-m”] [“-r” freq] < file
Let me count the ways this is bad. I’m not talking about how it should have an “OPTIONS” section where the options are described, although to fit standard manual page layout, it should. I’m talking about basic, basic failure to write anything at all useful to anyone other than the developers.
-s server: So, we’re specifying… the host or destination for our audio data?
-n name The name of the pipe? The name of the server? The audio device? The user?
-b and -m I think that -b and -m mean 8-bit and mono, because they’re used for that in other related applications. But the manual page doesn’t explain them here.
-r frequency Setting frequency with -r is strange– Maybe you meant -f? Or did you mean sample rate? Other esd-related commands use -r to set the sample rate. Maybe in this application it’s set in Hertz rather than bits per second. Or is it samples per millisecond? Or does it set the frequency of the sound you want to hear come out of the speakers, so you could put in audio recordings of a concert and have them come out as a single, even tone. Or you could increase or decrease the pitch by the frequency specified?
< file What kind of file? Is this the file used for output? Input? Probably a named pipe or a device of some sort, since esd doesn’t handle any audio file formats directly.
Esdctl and the rest of the esd docs are almost as vague.
Secretly Ironic 