Re: documentation - yeah right!

[Takashi Iwai <tiwai@suse.de>]

At Wed, 21 May 2003 12:09:28 -0400,
Richard Cochran wrote:
> 
> On Wed, May 21, 2003 at 11:24:35AM -0400, Paul Davis wrote:
> > Nobody disagress with the sentiment of the original poster. At least a
> > half-dozen to a dozen people have wandered onto this list and said
> > they would write documentation. It hasn't happened. Why? Its not
> > because its considered to be useless. It hasn't happened because
> > nobody has the time or inclination to write it. So far. Thats
> > all. There is no opposition to higher level documentation, only a lack
> > of time or motivation.
> 
> It is really hard to write higher level documentation after the
> project is finished!
 
oh, already finished?  i didn't know.
version 1.0 is the "starting point", i'd like to call :)

> With a name like "Advanced Linux Sound Architecture", I would expect
> to be able to read about:
> 
> 1. What is advanced (over OSS) in Alsa?
> 
> 2. What is the architecture?

many people already explained about the first point, so i won't say
much.  the following points are however still noteworthy:


- ALSA is not only the driver.

  ALSA consists of ALSA drivers, ALSA libraries and some utilities.
  that's why ALSA stands for "architecture".

  hence, comparison only the ALSA driver with OSS makes no sense at
  all.  as you know, OSS is only the driver.  (i know there is liboss,
  but AFAIK, no one uses it.)

  using sox or your own library is, of course, a workaround for OSS.
  but then you need extra things apart from the standard -- that is,
  it's no longer OSS itself.


- ALSA model is still Unix style (somehow).

  it's still based on open/close/read/write style (except for mmap).
  you'll need ioctl additionally to set up, but it's anyway necessary
  for "normal" OSS apps.
  

- ALSA library is the low-level library.

  ALSA-lib is written to cover the whole functionality of ALSA
  kernel drivers, plus the user-space extensions (such as plugins) and
  user-drivers.

  sure, OSS API is much simpler and easier to understand.
  it's because OSS API provides only too simple models and functions,
  which are not applicable to professional audio software.

  the ALSA-lib is not what makes programming easier but provides you
  the fundamental to access the ALSA system.  there are so many
  functions which are usually not necessary.
  you can see some analogy to Xlib -- you can write apps with it, but
  it's not easy as you think (although the minimal codes wouldn't be
  too difficult).


i personally do NOT recommend to write EVERYTHING with ALSA-lib.
it would be much better to have a higher-level abstraction library,
just like many graphic toolkit libraries do.  then you can hide the
complex things in a higher library without knowing the detail of
lowlevel implementations.

so, to my eyes, the real problem is that there are not many such
libraries yet.  of course, the documentation is inevitablly
necessary -- i mean apart from that.


ciao,

Takashi


-------------------------------------------------------
This SF.net email is sponsored by: ObjectStore.
If flattening out C++ or Java code to make your application fit in a
relational database is painful, don't do it! Check out ObjectStore.
Now part of Progress Software. http://www.objectstore.net/sourceforge