Re: Status of ALSA documentation?

Re: Status of ALSA documentation?

[Patrick Shirkey]

--- Paul Davis <pbd@Op.Net> wrote:
>>I recently showed a Mac user interested in using Linux
>>for live stage work (no gui needed) the ALSA site so they
>>could get some idea of progress... they just laughed and
>>said there was _nothing_ there to help them evaluate whether
>>ALSA (therefor Linux) was going to be useful to them... well,
>>not within a 5 minute perusal anyway.
>
>i think this is an excellent, critical point.
>
>with ALSA's adoption into the kernel, we have both (1) a chance that
>more people will write HOWTOs and code but also (2) more people saying
>"what is it?" and "how do i ....?" the current web site fails
>completely at both tasks.
>
>as much as i think we are still aiming for uniform operation for all
>cards (i.e. they just work), i think a good place to start with
>interface HOWTOs would be to take Dan's soundcard matrix, and add
>links from each card name to a HOWTO. The default set of HOWTOs can be
>empty, and we can add to them as time goes on. By empty, what I really
>mean is a boilerplate document that says "if you have this type of
>soundcard, just do X, Y, and Z and it will work". 
>
>there should also be a way to collect card-specific bug reports and
>accessing them all from the HOWTO page. 
>

Very good idea. The alsa-howto can easliy be linked to in this regard. Just needs a slight formatting change and a lot of tedious typing but give me a couple of months and it should be out of the way.

>of course a wiki would be an even better way of collecting card/setup
>specific quirks, but that seems a bit much to ask for right now.
>
>of course, it becomes critical that the matrix be kept up to date,
>which could also use a wiki-style input system.
>

I suggest updating it once every month. Once the bulk is done it should only take about a small amount of work to add new cards. Mostly just copy and paste.


>--p
>
>_______________________________________________
>Alsa-devel mailing list
>Alsa-devel@lists.sourceforge.net
>https://lists.sourceforge.net/lists/listinfo/alsa-devel

_____________________________________________________________
Want a new web-based email account ? ---> http://www.firstlinux.net

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

RE: Status of ALSA documentation?

[James Courtier-Dutton]

As ALSA is now in the linux kernel, should the HOWTO be part of the linux
documents HOWTO pages ?

Cheers
James


> -----Original Message-----
> From: alsa-devel-admin@lists.sourceforge.net
> [mailto:alsa-devel-admin@lists.sourceforge.net]On Behalf Of Patrick
> Shirkey
> Sent: 15 February 2002 07:35
> To: Paul Davis
> Cc: alsa-devel@lists.sourceforge.net
> Subject: Re: [Alsa-devel] Status of ALSA documentation?
>
>
> --- Paul Davis <pbd@Op.Net> wrote:
> >>I recently showed a Mac user interested in using Linux
> >>for live stage work (no gui needed) the ALSA site so they
> >>could get some idea of progress... they just laughed and
> >>said there was _nothing_ there to help them evaluate whether
> >>ALSA (therefor Linux) was going to be useful to them... well,
> >>not within a 5 minute perusal anyway.
> >
> >i think this is an excellent, critical point.
> >
> >with ALSA's adoption into the kernel, we have both (1) a chance that
> >more people will write HOWTOs and code but also (2) more people saying
> >"what is it?" and "how do i ....?" the current web site fails
> >completely at both tasks.
> >
> >as much as i think we are still aiming for uniform operation for all
> >cards (i.e. they just work), i think a good place to start with
> >interface HOWTOs would be to take Dan's soundcard matrix, and add
> >links from each card name to a HOWTO. The default set of HOWTOs can be
> >empty, and we can add to them as time goes on. By empty, what I really
> >mean is a boilerplate document that says "if you have this type of
> >soundcard, just do X, Y, and Z and it will work".
> >
> >there should also be a way to collect card-specific bug reports and
> >accessing them all from the HOWTO page.
> >
>
> Very good idea. The alsa-howto can easliy be linked to in this
> regard. Just needs a slight formatting change and a lot of
> tedious typing but give me a couple of months and it should be
> out of the way.
>
> >of course a wiki would be an even better way of collecting card/setup
> >specific quirks, but that seems a bit much to ask for right now.
> >
> >of course, it becomes critical that the matrix be kept up to date,
> >which could also use a wiki-style input system.
> >
>
> I suggest updating it once every month. Once the bulk is done it
> should only take about a small amount of work to add new cards.
> Mostly just copy and paste.
>
>
> >--p
> >
> >_______________________________________________
> >Alsa-devel mailing list
> >Alsa-devel@lists.sourceforge.net
> >https://lists.sourceforge.net/lists/listinfo/alsa-devel
>
> _____________________________________________________________
> Want a new web-based email account ? ---> http://www.firstlinux.net
>
> _______________________________________________
> Alsa-devel mailing list
> Alsa-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/alsa-devel


_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

RE: Status of ALSA documentation?

[Kevin Conder]

On Fri, 15 Feb 2002, James Courtier-Dutton wrote:

> As ALSA is now in the linux kernel, should the HOWTO be part of the linux
> documents HOWTO pages ?

	First of all, the ALSA-sound-mini-HOWTO *is* a part of the Linux
Documentation Project at http://www.linuxdoc.org. Is this what you were
referring to?

	Next, has anyone contacted the ALSA-sound-mini-HOWTO's maintainer,
Valentijn Sessink? His email address is valentyn@alsa-project.org. He's
probably the best person to coordinate any changes.

	Next, the standard format for the Linux Documentation project is 
DocBook/XML. I converted the HOWTO to DocBook/XML back in August of last 
year. I submitted it to Valentijn but I don't know what happened. I still
have my work, if anyone's interested.

<rant>
	Finally, if you're going to turn everything over to the Wikki
kiddies then count me out! I believe in quality over quantity.
</rant>


-- Kevin Conder, kevin@kevindumpscore.com



_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Paul Davis]

><rant>
>	Finally, if you're going to turn everything over to the Wikki
>kiddies then count me out! I believe in quality over quantity.
></rant>

isn't there a way to limit wiki access? what i like about wiki is the
ease of updating it every time something occurs to me. no CVS. it
"feels right". just my $0.02.

--p

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Andy Wingo]

On Fri, 15 Feb 2002, Kevin Conder wrote:

> <rant>
> 	Finally, if you're going to turn everything over to the Wikki
> kiddies then count me out! I believe in quality over quantity.
> </rant>

having written my share of documents, it's not the format that matters;
one format can be converted mechanically to another. it's the text. rant
all you want about how one format is better than another; but you've
demonstrated it best yourself, converting mark rage's document from the
wiki to docbook was easier than writing something yourself.

this is why writing docs is non-trivial.

regards,

wingo.

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Kevin Conder]

On Fri, 15 Feb 2002, Andy Wingo wrote:

> On Fri, 15 Feb 2002, Kevin Conder wrote:
> 
> > <rant>
> > 	Finally, if you're going to turn everything over to the Wikki
> > kiddies then count me out! I believe in quality over quantity.
> > </rant>
> 
> having written my share of documents, it's not the format that matters;

	I was unclear, I wasn't talking about format. IMHO, using a Wikki
for technical documentation is misguided. Since it's off-topic, we can
discuss this off of the list.

> but you've
> demonstrated it best yourself, converting mark rage's document from the
> wiki to docbook was easier than writing something yourself.

	I converted Mark Rage's document to DocBook as a demonstration.
Nobody asked me to re-write it. Was I supposed to?

	Too often, Open Source hackers develop NIH (Not-Invented-Here)
Syndrome. You see them do the same work over and over. I try to avoid
that, if possible. That's why I have worked with the maintainers of
the existing documents like Mark and Valentijn.

	I'm dumb-founded by this personal attack... Maintenance work might
be "mechanical" but it's necessary.


-- Kevin Conder, kevin@kevindumpscore.com



_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Patrick Shirkey]

I'll try again tonight on my home computer. That should sort out a lot of this windohs exp vs netscrap BS.

--
Patrick Shirkey - Boost Hardware Ltd
For the discerning hardware connoisseur
Http://www.boosthardware.com
Http://www.boosthardware.com/LAU/Linux_Audio_Users_Guide/


--- Paul Davis <pbd@Op.Net> wrote:
>>http://www.boosthardware.com/LAU/alsa/index5-pd.html
>
>there's a bug, because all the main text is invisible in netscape 4.
>
>i've tried to fix it, but i can't deal with automatically generated
>HTML. the indentation is unreadable - nested tables where inner tables
>are indented less than outer tables, etc.
>
>i tried ripping out large chunks, and got something, but when i tried
>to narrow it down, i couldn't.

_____________________________________________________________
Want a new web-based email account ? ---> http://www.firstlinux.net

_____________________________________________________________
You deserve a better email address! Get personalized email @yourname
or @yourcompany from Everyone.net --> http://www.everyone.net?tag

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Samuel S Chessman]

I also can't see the tabled text in netscape 4.77, mozilla renders it fine.
Could you consider using .png files instead of .gif for the various
images?

>From an aesthetic point, I would say the buttons are hard to read and a little
cramped (1280x1024 resolution).  Perhaps you could use some alternates.
The gimp is real good at this sort of thing.  If you need assistance,
I can offer up some alternates.

Is the green #BED1BE cast in stone?  It appears all over, and while fine
for some areas, is a bit overpowering when it's the only other color besides
black and white.

Overall the layout seems quite readable, and usable.

Thanks for making the effort!



-- 
   Sam Chessman                                               chessman@tux.org
        First do the necessary, then the possible, then the impossible!


_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Paul Davis]

>I also can't see the tabled text in netscape 4.77, mozilla renders it fine.

i used mozilla to take a look again. i had originally suggested making
the font of the main "text" table larger. i still think is a good idea
- this text is just as critical as everything else on the page, and at
its current "-2" size, i find it unpleasant to read.

--p

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Patrick Shirkey]

I have just done some work on the alsa-howto wiki for the cmipci card.

I intend to use this as the template for all the other cards. I appreciate any constructive criticism.

http://alsa.opensrc.org/index.php?page=cmipci

--
Patrick Shirkey - Boost Hardware Ltd
For the discerning hardware connoisseur
Http://www.boosthardware.com
Http://www.boosthardware.com/LAU/Linux_Audio_Users_Guide/


--- Patrick Shirkey <kotau@firstlinux.net> wrote:
>I have had another go at cleaning up the page.
>
>Here's the latest.
>
>http://www.boosthardware.com/LAU/alsa/index5-pd.html
>
>This is just to get an impression of the layout. Obviously the link buttons need to be changed and resized correctly.
>
>
>
>
>--
>Patrick Shirkey - Boost Hardware Ltd
>For the discerning hardware connoisseur
>Http://www.boosthardware.com
>Http://www.boosthardware.com/LAU/Linux_Audio_Users_Guide/
>
>
>--- Juhana Sadeharju <kouhia@nic.funet.fi> wrote:
>>>From: Patrick Shirkey <kotau@firstlinux.net>
>>>
>>>http://www.boosthardware.com/LAU/alsa/index4-pd.html
>>
>>Please ignore my previous mail, posted minute ago.
>>It looks like my help is not needed at all...
>>
>>Juhana
>>
>>_______________________________________________
>>Alsa-devel mailing list
>>Alsa-devel@lists.sourceforge.net
>>https://lists.sourceforge.net/lists/listinfo/alsa-devel
>
>_____________________________________________________________
>Want a new web-based email account ? ---> http://www.firstlinux.net
>
>_____________________________________________________________
>You deserve a better email address! Get personalized email @yourname
>or @yourcompany from Everyone.net --> http://www.everyone.net?tag
>
>_______________________________________________
>Alsa-devel mailing list
>Alsa-devel@lists.sourceforge.net
>https://lists.sourceforge.net/lists/listinfo/alsa-devel

_____________________________________________________________
Want a new web-based email account ? ---> http://www.firstlinux.net

_____________________________________________________________
You deserve a better email address! Get personalized email @yourname
or @yourcompany from Everyone.net --> http://www.everyone.net?tag

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Patrick Shirkey]

I have had another go at cleaning up the page.

Here's the latest.

http://www.boosthardware.com/LAU/alsa/index5-pd.html

This is just to get an impression of the layout. Obviously the link buttons need to be changed and resized correctly.




--
Patrick Shirkey - Boost Hardware Ltd
For the discerning hardware connoisseur
Http://www.boosthardware.com
Http://www.boosthardware.com/LAU/Linux_Audio_Users_Guide/


--- Juhana Sadeharju <kouhia@nic.funet.fi> wrote:
>>From: Patrick Shirkey <kotau@firstlinux.net>
>>
>>http://www.boosthardware.com/LAU/alsa/index4-pd.html
>
>Please ignore my previous mail, posted minute ago.
>It looks like my help is not needed at all...
>
>Juhana
>
>_______________________________________________
>Alsa-devel mailing list
>Alsa-devel@lists.sourceforge.net
>https://lists.sourceforge.net/lists/listinfo/alsa-devel

_____________________________________________________________
Want a new web-based email account ? ---> http://www.firstlinux.net

_____________________________________________________________
You deserve a better email address! Get personalized email @yourname
or @yourcompany from Everyone.net --> http://www.everyone.net?tag

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Paul Davis]

>http://www.boosthardware.com/LAU/alsa/index5-pd.html

there's a bug, because all the main text is invisible in netscape 4.

i've tried to fix it, but i can't deal with automatically generated
HTML. the indentation is unreadable - nested tables where inner tables
are indented less than outer tables, etc.

i tried ripping out large chunks, and got something, but when i tried
to narrow it down, i couldn't.


_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Juhana Sadeharju]

>Here's the latest.
>
>http://www.boosthardware.com/LAU/alsa/index5-pd.html

I liked better the version which had the explanation of the
project. What were its problems? I.e., why it was taken off?

This new page is too wide. Could the title be broken to two lines?
Then title's height would match the height of the logos.

The search tool too makes the page wide. The search utility could be
on its own subpage. How often you search the Alsa pages? The search
page could also contain the site tree.

The text on the subpage links is not well readable, but I don't
know what to do without making the text smaller.

How about this layout:

     logo1  two line title  logo2

            subpage links

  Two line explanation........and link to more information

  Packages:                 News:

  driver     short
  <version>  explanation

  library    short
  <version>  explanation

  utilities  short
  <version>  explanation

  tools      short
  <version>  explanation

  OSS Combat short
  library    explanation
  <version>

Best regards,

Juhana

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Paul Davis]

>>Here's the latest.
>>
>>http://www.boosthardware.com/LAU/alsa/index5-pd.html
>
>I liked better the version which had the explanation of the
>project. What were its problems? I.e., why it was taken off?

i didn't "take it off". i tried to rewrite it so that it didn't sound
as if we were just starting out. ALSA isn't complete, but its hardly
in a "still working on the basic design" phase. i thought the text
should reflect this so that first-time visitors would get a better
feeling for it as a working system. the old description sounded to me
like a reflection of where ALSA was a year or two ago.

>This new page is too wide. Could the title be broken to two lines?
>Then title's height would match the height of the logos.

Sounds good to me.

>  Two line explanation........and link to more information

I tried hard to write a two line explanation, but I couldn't.

>  OSS Combat short
   ^^^^^^^^^^

I think its very VERY VERY important that this not be presented this
way. ALSA offers binary OSS compatibility with no modifications needed
(except for some OSS-mmap apps like quake) Nothing extra is needed to
make them work.

the OSS compat library does a *lot* more than provide OSS
compatibility. we need a new name for it that reflects it capabilities
(routing OSS apps through alsa-lib).

we do not want anyone imagining they have to relink their apps to get
them to work with ALSA, since thats not true.

--p

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Juhana Sadeharju]

>From: Patrick Shirkey <kotau@firstlinux.net>
>
>http://www.boosthardware.com/LAU/alsa/index4-pd.html

Please ignore my previous mail, posted minute ago.
It looks like my help is not needed at all...

Juhana

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Juhana Sadeharju]

>From: Jaroslav Kysela <perex@suse.cz>
>
>> I think that simply for working on this, Patrick should be made
>> webmaster for alsa-project.org. The simple fact that he has bothered
>
>It's fine with me. I offered write access to WWW tree to him a few days 
>ago.

Great. Just let me know when I can start sending material for
the new version of the Alsa webpages! (But please let me know if
there will no be any face lift for those pages.)

Best regards,

Juhana

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Patrick Shirkey]

--- Paul Davis <pbd@Op.Net> wrote:
>>I disagree. I just went through the process of teaching a friend how to use li
>>nux and he needed every piece of information I could give him. It is my opinio
>>n that repetiton and hand holding is the key to success for all newbies. (Base
>>d on teaching ESL for the past two years and teaching myself how to use linux 
>>for the past 3). 
>
>well, then i'd use language like:
>
>      edit the file /foo/bar/baz. you can use any text editor for
>      this, including such programs as vi and emacs.
>
>you cannot usefully make a document on a specific audio interface into
>a tutorial on basic unix system skills. i think that someone who
>doesn't know how to use a text editor will *not* be able to follow
>your instructions without additional help from someone else.
>

That's a good point. Someone else also mentioned why not have a more user friendly example. I will eventually. I think I will make a page with maybe 5 examples of how to edit a file to make a working modules.conf and provide it as a link in the doc. The info in the doc will be as above.

If anybody wants to write a corresponding example for their favorite editor please send it to me. It should take about 1 minute. The text that needs changing is this:

---------
To copy and paste the above to your /etc/modules.conf file follow these instructions.

Using the vi text editor:

Change to root.


	su

Open the file with your favorite text editor.

	vi /etc/modules.conf

Copy the above text to the bottom of the file by highlighting it with your mouse and paste it by clicking in the appropriate spot with your middle mouse button. If you don't have a middle mouse button then you can press the left and right button at the same time.
If you use the above text editor you will need to put the cursor in the correct place and type: 

	a

Which allows you to write to the file. Then save the file. If you use the above text editor type:

	ESC
	q
	then type:
	wq!
	and press enter.


---------


>>>The problem is that these documents will become reference sheets for
>>>each soundcard. Browsing through a couple of pages of install info for
>>>ALSA every time you want to check on that detail about the
>>>CmRMiceCreatEmu Y18kJA card is going to annoy most people. 
>>>
>>
>>Hence the hyperlinks in the contents of the page. Once I learn some more comma
>>nds for the wiki then having these shouldn't be a problem. Someone correct me 
>>if I'm wrong.
>
>I would just invert the order of the information. Put the card
>specific info at the top, and follow it with the generic information.
>

That works too. But more experienced users can easily follow a link whereas the newbies will get very confused with lots of technical info at the top of the document. I think a linked TOC is a good compromise.

>>I'm attacking the install howto from the point of view of a "complete" newbie.
>> Someone who needs to be spoonfeed. 
>
>Thats a different goal than I was originally outlining. We get lots of
>mail on alsa-devel (and probably even more on alsa-user) asking "how
>do i use this card?" or "how do i get this card to do ...?". the mail
>isn't from complete newbies, who probably wouldn't even know that
>alsa-devel exists, but from people who know how to use a text editor
>yet have no clue how to get their audio interface working. Thats the
>audience I was aiming for.
>

Sure, currently we do but in the not too distant future we may be overloaded with new users who don't know this information. Better to cover our bases now than field hundreds of the same questions later. We just need to organise the page in a layout that makes it as easy as possible for everyone.


--
Patrick Shirkey - Boost Hardware Ltd
For the discerning hardware connoisseur
Http://www.boosthardware.com
Http://www.boosthardware.com/LAU/Linux_Audio_Users_Guide/


_____________________________________________________________
Want a new web-based email account ? ---> http://www.firstlinux.net

_____________________________________________________________
You deserve a better email address! Get personalized email @yourname
or @yourcompany from Everyone.net --> http://www.everyone.net?tag

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Patrick Shirkey]

Paul sent me a revised edition of the alsa home page with more of a current feel than the previous version so you can find it here:

http://www.boosthardware.com/LAU/alsa/index4-pd.html

I have retained the link to the LAU-guide because I know it helps new users to find needed information. However for those of you who are anti my link to Boost Hardware being so prominent I have restructured the page slightly.

I intend to start getting in knee deep on the alsa-howto wiki which Mark created.
Once that is in more of a working condition I will add that and the new midi howto (at the linux doc project) to the LAU-guide too.

I will also attempt to create a docbook version of all the info in the alsa-howto wiki. Once I get cosy with docbook markup. 


--
Patrick Shirkey - Boost Hardware Ltd
For the discerning hardware connoisseur
Http://www.boosthardware.com
Http://www.boosthardware.com/LAU/Linux_Audio_Users_Guide/


_____________________________________________________________
Want a new web-based email account ? ---> http://www.firstlinux.net

_____________________________________________________________
You deserve a better email address! Get personalized email @yourname
or @yourcompany from Everyone.net --> http://www.everyone.net?tag

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Paul Davis]

>Paul sent me a revised edition of the alsa home page with more of a current fe
>el than the previous version so you can find it here:
>
>http://www.boosthardware.com/LAU/alsa/index4-pd.html

a few questions/comments on the new one.

1) is a requirement that the SuSE logo be where it is?

2) i think that we should come up with a consistent design for all the
   ALSA pages. that probably means making the LHS navigation bar
   smaller, removing extraneous logos (i don't think we need the SF
   logo here - this is not hosted by sf.net), remove the "statistics"
   links etc. I would personally get rid of the image based navigation
   bar and use text instead. see equalarea.com for an example of
   what i mean (and buy the CD if you feel like it! :)

3) the document at alsa-project.org/api.php3 contains zero links to
     the current API documenation. its critical that this be in place.
     I like the layout, have some ideas for improvements. I don't know
     where the current docs live - the current "Documentation" link
     is dead.

4) I would be happy to work on the API documentation "index" page if
   someone will tell me where I can find the current one. I will
   rework it to be a combination of the current api.php3 and the new
   stuff, and make it friendly toward people coming to ALSA for the
   first time. This page should not, IMHO, be generated by docbook,
   even though the rest of the ALSA API pages will be.

--p

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Patrick Shirkey]

>>You could try.
>>
>>http://www.boosthardware.com/LAU/alsa/index.html
>>
>>Otherwise it's windohs or bpftp that are corrupting the files somewhere.
>
>same deal. i get the page source, it looks OK, but doesn't render.
>

There was some cruft at the end of the file so I may have fixed it now. 

--
Patrick Shirkey - Boost Hardware Ltd
For the discerning hardware connoisseur
Http://www.boosthardware.com
Http://www.boosthardware.com/LAU/Linux_Audio_Users_Guide/




_____________________________________________________________
Want a new web-based email account ? ---> http://www.firstlinux.net

_____________________________________________________________
You deserve a better email address! Get personalized email @yourname
or @yourcompany from Everyone.net --> http://www.everyone.net?tag

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Paul Davis]

>There was some cruft at the end of the file so I may have fixed it now. 

yep, that worked.

--p

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Patrick Shirkey]

--- Paul Davis <pbd@Op.Net> wrote:
>>Ok I can give the command to load the soundcore module instead. 
>>
>>eg. modrobe soundcore
>
>modprobe -n soundcore will test for its existence without doing anything.
>

Ok.

>>Well it is the most popular unix editor. It is just an example for new users w
>>ho may not even know how to edit a file.
>
>pointing them at vi will not help such users. just tell them to edit
>the file - if they don't know how to do that, this document can't be
>of any help to them, really.
>

I disagree. I just went through the process of teaching a friend how to use linux and he needed every piece of information I could give him. It is my opinion that repetiton and hand holding is the key to success for all newbies. (Based on teaching ESL for the past two years and teaching myself how to use linux for the past 3). 


>>>more generally, it doesn't seem useful to me to duplicate the
>>>instructions for building+installing+configuring ALSA for each
>>>card. isn't this what hyperlinks are for? what we need on a per-card
>>>basis is the stuff thats really specific for that card:
>>> 
>>
>>I'm only thinking of LCD. People who may get confused by following links. The 
>>easier Linux is for these people the more chance we have of getting hardware w
>>orking.
>
>The problem is that these documents will become reference sheets for
>each soundcard. Browsing through a couple of pages of install info for
>ALSA every time you want to check on that detail about the
>CmRMiceCreatEmu Y18kJA card is going to annoy most people. 
>

Hence the hyperlinks in the contents of the page. Once I learn some more commands for the wiki then having these shouldn't be a problem. Someone correct me if I'm wrong.

I'm attacking the install howto from the point of view of a "complete" newbie. Someone who needs to be spoonfeed. 

>same deal. i get the page source, it looks OK, but doesn't render.
>

I'll have a look through the source for any uncapped commands :(

>--p

_____________________________________________________________
Want a new web-based email account ? ---> http://www.firstlinux.net

_____________________________________________________________
You deserve a better email address! Get personalized email @yourname
or @yourcompany from Everyone.net --> http://www.everyone.net?tag

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Paul Davis]

>I disagree. I just went through the process of teaching a friend how to use li
>nux and he needed every piece of information I could give him. It is my opinio
>n that repetiton and hand holding is the key to success for all newbies. (Base
>d on teaching ESL for the past two years and teaching myself how to use linux 
>for the past 3). 

well, then i'd use language like:

      edit the file /foo/bar/baz. you can use any text editor for
      this, including such programs as vi and emacs.

you cannot usefully make a document on a specific audio interface into
a tutorial on basic unix system skills. i think that someone who
doesn't know how to use a text editor will *not* be able to follow
your instructions without additional help from someone else.

>>The problem is that these documents will become reference sheets for
>>each soundcard. Browsing through a couple of pages of install info for
>>ALSA every time you want to check on that detail about the
>>CmRMiceCreatEmu Y18kJA card is going to annoy most people. 
>>
>
>Hence the hyperlinks in the contents of the page. Once I learn some more comma
>nds for the wiki then having these shouldn't be a problem. Someone correct me 
>if I'm wrong.

I would just invert the order of the information. Put the card
specific info at the top, and follow it with the generic information.

>I'm attacking the install howto from the point of view of a "complete" newbie.
> Someone who needs to be spoonfeed. 

Thats a different goal than I was originally outlining. We get lots of
mail on alsa-devel (and probably even more on alsa-user) asking "how
do i use this card?" or "how do i get this card to do ...?". the mail
isn't from complete newbies, who probably wouldn't even know that
alsa-devel exists, but from people who know how to use a text editor
yet have no clue how to get their audio interface working. Thats the
audience I was aiming for.

--p

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Patrick Shirkey]

--- Paul Davis <pbd@Op.Net> wrote:
>>On Tue, 19 Feb 2002, Patrick Shirkey wrote:
>>
>>> I have just uploaded a template for the idea PD had to make a complete
>>> howto for each card and link it to the sound card matrix or something
>>> similar.
>>[...]
>>> http://www.boosthardware.com/LAU/alsa/template2.html
>
>looks OK. a few nitpicks:
>
>  1) don't point people at /lib/modules ... the structure of this
>      tree is different in 2.0, 2.2 and 2.4

Ok I can give the command to load the soundcore module instead. 

eg. modrobe soundcore

>  2) don't put a reference to alsamixer in the template; some cards
>      have no mixer and so it won't do anything useful

I could add that some cards don't use it and provide a link to an amixer howto.

>  3) don't assume that they use vi(1)

Well it is the most popular unix editor. It is just an example for new users who may not even know how to edit a file.

>  4) defining the card name to be of type "hw" might not
>       be too smart for naive "consumer" users who
>       then try to use any old app with that as the PCM
>       device name.
>

This is still fuzzy for me. Should I replace that with "hwshare"? I have started writing a more complete .asoundrc document but haven't finished it yet.

>more generally, it doesn't seem useful to me to duplicate the
>instructions for building+installing+configuring ALSA for each
>card. isn't this what hyperlinks are for? what we need on a per-card
>basis is the stuff thats really specific for that card:
> 

I'm only thinking of LCD. People who may get confused by following links. The easier Linux is for these people the more chance we have of getting hardware working.

> * what modules to load  
> * what module parameters the driver takes
> * a lot of explanation about what they do
> * a list of every Control and PCM switch
> * a lot of explanation about what they do
> * a "FAQ" detailing things like:
>      - how to get sound from the rear speakers?
>      - how to download firmware?
>      - how to get new sounds from the synth?
>      - how to make the synth work?
>      - why do i have to preload module XXX?
>
>>> http://www.boosthardware.com/LAU/alsa/
>
>doesn't render under netscape 4.0
>

You could try.

http://www.boosthardware.com/LAU/alsa/index.html

Otherwise it's windohs or bpftp that are corrupting the files somewhere.

>I think that simply for working on this, Patrick should be made
>webmaster for alsa-project.org. The simple fact that he has bothered
>to do some work on the website moves him beyond almost anybody else on
>the list, though in most cases, for all the right reasons.
>

Sure. At least I have my computers now so can work on things at home. Unfortunately I haven't got net connected yet.

>--p


--
Patrick Shirkey - Boost Hardware Ltd
For the discerning hardware connoisseur
Http://www.boosthardware.com
Http://www.boosthardware.com/LAU/Linux_Audio_Users_Guide/



_____________________________________________________________
Want a new web-based email account ? ---> http://www.firstlinux.net

_____________________________________________________________
You deserve a better email address! Get personalized email @yourname
or @yourcompany from Everyone.net --> http://www.everyone.net?tag

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Paul Davis]

>Ok I can give the command to load the soundcore module instead. 
>
>eg. modrobe soundcore

modprobe -n soundcore will test for its existence without doing anything.

>Well it is the most popular unix editor. It is just an example for new users w
>ho may not even know how to edit a file.

pointing them at vi will not help such users. just tell them to edit
the file - if they don't know how to do that, this document can't be
of any help to them, really.

>>  4) defining the card name to be of type "hw" might not
>>       be too smart for naive "consumer" users who
>>       then try to use any old app with that as the PCM
>>       device name.
>>
>
>This is still fuzzy for me. Should I replace that with "hwshare"? I have start
>ed writing a more complete .asoundrc document but haven't finished it yet.

for most people, their most used PCM device will be of type "plug" or
"plughw" (the latter just being a notational convenience rather than
anything truly different).

>>more generally, it doesn't seem useful to me to duplicate the
>>instructions for building+installing+configuring ALSA for each
>>card. isn't this what hyperlinks are for? what we need on a per-card
>>basis is the stuff thats really specific for that card:
>> 
>
>I'm only thinking of LCD. People who may get confused by following links. The 
>easier Linux is for these people the more chance we have of getting hardware w
>orking.

The problem is that these documents will become reference sheets for
each soundcard. Browsing through a couple of pages of install info for
ALSA every time you want to check on that detail about the
CmRMiceCreatEmu Y18kJA card is going to annoy most people. 

>>>> http://www.boosthardware.com/LAU/alsa/
>>
>>doesn't render under netscape 4.0
>>
>
>You could try.
>
>http://www.boosthardware.com/LAU/alsa/index.html
>
>Otherwise it's windohs or bpftp that are corrupting the files somewhere.

same deal. i get the page source, it looks OK, but doesn't render.

--p

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Patrick Shirkey]

I have just uploaded a template for the idea PD had to make a complete howto for each card and link it to the sound card matrix or something similar.

You can find it here:

http://www.boosthardware.com/LAU/alsa/template2.html

I would appreciate help from people to collect these things. Working modules.conf parameters and working .asoundrc files.  Obviously I could do this myself but the parameters I provide will be next to useless for some cards. eg rme9652.

Please send me the info as text.

Also I have not recieved any feedback on my attempt at updating the mainpage to meet peoples requests. In case you missed it you can find it here:

http://www.boosthardware.com/LAU/alsa/



--
Patrick Shirkey - Boost Hardware Ltd
For the discerning hardware connoisseur
Http://www.boosthardware.com
Http://www.boosthardware.com/LAU/Linux_Audio_Users_Guide/


--- Kevin Conder <kconder@interaccess.com> wrote:
>On Fri, 15 Feb 2002, Andy Wingo wrote:
>
>> On Fri, 15 Feb 2002, Kevin Conder wrote:
>> 
>> > <rant>
>> > 	Finally, if you're going to turn everything over to the Wikki
>> > kiddies then count me out! I believe in quality over quantity.
>> > </rant>
>> 
>> having written my share of documents, it's not the format that matters;
>
>	I was unclear, I wasn't talking about format. IMHO, using a Wikki
>for technical documentation is misguided. Since it's off-topic, we can
>discuss this off of the list.
>
>> but you've
>> demonstrated it best yourself, converting mark rage's document from the
>> wiki to docbook was easier than writing something yourself.
>
>	I converted Mark Rage's document to DocBook as a demonstration.
>Nobody asked me to re-write it. Was I supposed to?
>
>	Too often, Open Source hackers develop NIH (Not-Invented-Here)
>Syndrome. You see them do the same work over and over. I try to avoid
>that, if possible. That's why I have worked with the maintainers of
>the existing documents like Mark and Valentijn.
>
>	I'm dumb-founded by this personal attack... Maintenance work might
>be "mechanical" but it's necessary.
>
>
>-- Kevin Conder, kevin@kevindumpscore.com
>
>
>
>_______________________________________________
>Alsa-devel mailing list
>Alsa-devel@lists.sourceforge.net
>https://lists.sourceforge.net/lists/listinfo/alsa-devel

_____________________________________________________________
Want a new web-based email account ? ---> http://www.firstlinux.net

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Mark Constable]

On Wed, 20 Feb 2002 01:01, Patrick Shirkey wrote:

> http://www.boosthardware.com/LAU/alsa/template2.html

I hope you don't mind me adding the above contents to this Wiki below...

 http://alsa.opensrc.org/?page=cmipci

It took me less than 2 minutes to create the above page, and anyone
can revise or add new material without any impediments... too easy.

> Also I have not recieved any feedback on my attempt at updating the
> mainpage to meet peoples requests. In case you missed it you can find it
> here:
>
> http://www.boosthardware.com/LAU/alsa/

That is an excllent intro, I'd certainly vote that it gets merged into the official
site. Pity is wasn't a Wiki where you could have already made the changes
rather than having to waste time lobbying.

--markc

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Kai Vehmanen]

On Tue, 19 Feb 2002, Patrick Shirkey wrote:

> I have just uploaded a template for the idea PD had to make a complete
> howto for each card and link it to the sound card matrix or something
> similar.
[...]
> http://www.boosthardware.com/LAU/alsa/template2.html

Looks very good.

> Also I have not recieved any feedback on my attempt at updating the
> mainpage to meet peoples requests. In case you missed it you can find it
> here:
[...]
> http://www.boosthardware.com/LAU/alsa/

I guess the amount of feedback is to be expected (kind of explains why the
web pages haven't been updated...). Anyway, this too looks good. One thing
that might raise discussion is the five primary goals of ALSA. Are these
still up-to-date or should they be upgraded to the post-alsa-in-2.5 era.

One thing that the front page should answer is why ALSA, what makes it 
better than OSS?

PS Also, the applications page requires updating (doesn't even
   mention 0.6-0.9 APIs). 

-- 
 http://www.eca.cx
 Audio software for Linux!


_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Paul Davis]

>On Tue, 19 Feb 2002, Patrick Shirkey wrote:
>
>> I have just uploaded a template for the idea PD had to make a complete
>> howto for each card and link it to the sound card matrix or something
>> similar.
>[...]
>> http://www.boosthardware.com/LAU/alsa/template2.html

looks OK. a few nitpicks:

  1) don't point people at /lib/modules ... the structure of this
      tree is different in 2.0, 2.2 and 2.4
  2) don't put a reference to alsamixer in the template; some cards
      have no mixer and so it won't do anything useful
  3) don't assume that they use vi(1)
  4) defining the card name to be of type "hw" might not
       be too smart for naive "consumer" users who
       then try to use any old app with that as the PCM
       device name.

more generally, it doesn't seem useful to me to duplicate the
instructions for building+installing+configuring ALSA for each
card. isn't this what hyperlinks are for? what we need on a per-card
basis is the stuff thats really specific for that card:
 
 * what modules to load  
 * what module parameters the driver takes
 * a lot of explanation about what they do
 * a list of every Control and PCM switch
 * a lot of explanation about what they do
 * a "FAQ" detailing things like:
      - how to get sound from the rear speakers?
      - how to download firmware?
      - how to get new sounds from the synth?
      - how to make the synth work?
      - why do i have to preload module XXX?

>> http://www.boosthardware.com/LAU/alsa/

doesn't render under netscape 4.0

I think that simply for working on this, Patrick should be made
webmaster for alsa-project.org. The simple fact that he has bothered
to do some work on the website moves him beyond almost anybody else on
the list, though in most cases, for all the right reasons.

--p





_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Jaroslav Kysela]

On Mon, 25 Feb 2002, Paul Davis wrote:

> I think that simply for working on this, Patrick should be made
> webmaster for alsa-project.org. The simple fact that he has bothered
> to do some work on the website moves him beyond almost anybody else on
> the list, though in most cases, for all the right reasons.

It's fine with me. I offered write access to WWW tree to him a few days 
ago.

						Jaroslav

-----
Jaroslav Kysela <perex@suse.cz>
Linux Kernel Sound Maintainer
ALSA Project  http://www.alsa-project.org
SuSE Linux    http://www.suse.com


_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Patrick Shirkey]

--- Mark Constable <markc@renta.net> wrote:
>
>FWIW here is a quick and dirty Wiki that might encourage
>someone to set up something for real, if it proves useful.
>Having a Wiki is one thing, encouraging folks to actually
>input something useful is another... but, it can't get any
>easier than this for _anyone_ to contribute.
>
> http://alsa.opensrc.org/
>

Can I suggest that we input all the data from the alsa-howto into this wiki in a standardised format before anyone gets a chance to make it unreadable?

And here's my attempt at incorporating a few of the ideas for the home page.

http://www.boosthardware.com/LAU/alsa/index.html

Possibly finished but the idea is there. KISS. If anyone can be bothered cutting the borders off the links buttons then I can make a nice border for them that will look almost exactly the same and have the added bonus of always being centered. I have tried gimp here but funnily enough the windohs version doesn't have very good support for gifs or jpegs infact I couldn't save anything. 

I incorporated the LAU guide because it has nearly everything a new user needs to get into Linux audio except a midi howto which has just been released so I should link it in. Plus the link on the docs page is incorrect and I have worked hard on it for a while now. Also very soon it will become linked to something much more interesting. But you'll have to wait for that one ;]

We could link each card in the soundcard matrix to the new wiki once it is ready for public use. And there are also a few dead links that need to be squashed around the rest of the site.

I can get cvs working in doze but I tried a couple of weeks ago to get some software and it seems that doze corrupted a lot of the files. It's probably worth another try though.

So Jaroslav if you want to give me cvs access to the site I can attempt to get something going from here. 

Great thing about broadband is I can go anywhere round here and have a working setup within 10 minutes. If only it was on a linux machine.

--
Patrick Shirkey - Boost Hardware Ltd
For the discerning hardware connoisseur
Http://www.boosthardware.com
Http://www.boosthardware.com/LAU/Linux_Audio_Users_Guide/


--- Mark Constable <markc@renta.net> wrote:
>On Fri, 15 Feb 2002 15:03, Paul Davis wrote:
>
>> of course a wiki would be an even better way of collecting card/setup
>> specific quirks, but that seems a bit much to ask for right now.
>>
>> of course, it becomes critical that the matrix be kept up to date,
>> which could also use a wiki-style input system.
>
>FWIW here is a quick and dirty Wiki that might encourage
>someone to set up something for real, if it proves useful.
>Having a Wiki is one thing, encouraging folks to actually
>input something useful is another... but, it can't get any
>easier than this for _anyone_ to contribute.
>
> http://alsa.opensrc.org/
>
>--markc
>
>_______________________________________________
>Alsa-devel mailing list
>Alsa-devel@lists.sourceforge.net
>https://lists.sourceforge.net/lists/listinfo/alsa-devel

_____________________________________________________________
Want a new web-based email account ? ---> http://www.firstlinux.net

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[James Tappin]

On Friday 15 February 2002 12:12, Patrick Shirkey wrote:
>
> And here's my attempt at incorporating a few of the ideas for the home
> page.
>
> http://www.boosthardware.com/LAU/alsa/index.html
>
> Possibly finished but the idea is there. KISS. If anyone can be bothered
> cutting the borders off the links buttons then I can make a nice border for
> them that will look almost exactly the same and have the added bonus of
> always being centered. I have tried gimp here but funnily enough the
> windohs version doesn't have very good support for gifs or jpegs infact I
> couldn't save anything.

This one shares one major problem with the current official version. There 
are too many news items, events from 18 months ago shouldn't be on the front 
page. I'd suggest having:
* Items in the last 2 months, or 3 items whichever is the greater
* An "old news" link for those who really want to trace the history.

James

-- 
+------------------------+-------------------------------+---------+
| James Tappin           | School of Physics & Astronomy |  O__    |
| sjt@star.sr.bham.ac.uk | University of Birmingham      | --  \/` |
| Ph: 0121-414-6462. Fax: 0121-414-3722                  |         |
+--------------------------------------------------------+---------+

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Patrick Shirkey]

--- Mark Constable <markc@renta.net> wrote:
>On Thu, 14 Feb 2002 20:02, Patrick Shirkey wrote:
>
>> 1: Less developer news
>> 2: A mission statement
>> 3: More emphasis on information related to vendors
>>
>> What else do people want to see changed?
>
>Developers are usually familiar with ALSA and know where
>to look for further information. To me, the main strength
>of the website should be for end-user information like
>how to set up and configure ALSA drivers and modules so
>clear links to HOWTOS and anything that eases the pain
>for new ALSA users to get the most out of their audio
>systems would be great.
>
>I recently showed a Mac user interested in using Linux
>for live stage work (no gui needed) the ALSA site so they
>could get some idea of progress... they just laughed and
>said there was _nothing_ there to help them evaluate whether
>ALSA (therefor Linux) was going to be useful to them... well,
>not within a 5 minute perusal anyway.
>
>No doubt a slash/nuke-like portal would be asking too much ?
>

I have nailed that design recently but haven't started on the whole user configuration deal yet. That's slightly more daunting. I personally don't think that design is appropriate to the alsa site.

More coming soon....

--
Patrick Shirkey - Boost Hardware Ltd
For the discerning hardware connoisseur
Http://www.boosthardware.com
Http://www.boosthardware.com/LAU/Linux_Audio_Users_Guide/



>--markc
>
>_______________________________________________
>Alsa-devel mailing list
>Alsa-devel@lists.sourceforge.net
>https://lists.sourceforge.net/lists/listinfo/alsa-devel

_____________________________________________________________
Want a new web-based email account ? ---> http://www.firstlinux.net

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Patrick Shirkey]

[-- Attachment #1: Type: text/plain, Size: 177 bytes --]


*** There is an attachment in this mail. ***

_____________________________________________________________
Want a new web-based email account ? ---> http://www.firstlinux.net

[-- Attachment #2: Type: message/rfc822, Size: 2286 bytes --]

From: Patrick Shirkey <kotau@firstlinux.net>
To: Jaroslav Kysela <perex@suse.cz>
Subject: Re: [Alsa-devel] Status of ALSA documentation?
Date: Thu, 14 Feb 2002 23:30:07 -0800 (PST)

--- Jaroslav Kysela <perex@suse.cz> wrote:
>I stated that the current layout is result of combination of HTML code and
>PHP3 scripts. I don't think that we can get standartized set of pages with
>static HTML contents. In my opinion, it would be better to debug new web
>layout directly on server, otherwise we may reach unexpected problems when
>migrating from some private site.
>

I understand. Unless I copy the entire site this rules me out as the admin for the time being as I currently do not have my machines online. This could change in the near future so if no one else has volunteered by then my offer still stands.

However I can still attempt some basic layout design which other people could adapt.

No time like the present.



--
Patrick Shirkey - Boost Hardware Ltd
For the discerning hardware connoisseur
Http://www.boosthardware.com
Http://www.boosthardware.com/LAU/Linux_Audio_Users_Guide/


--- Jaroslav Kysela <perex@suse.cz> wrote:
>On Thu, 14 Feb 2002, Patrick Shirkey wrote:
>
>> >
>> >If you are interested to reorganize contents of ALSA web site, I can give
>> >you CVS write access and you can show your ideas in some subdirectory for
>> >clarification.
>>
>> I have a site where I can put up a revised homepage for now.
>
>I stated that the current layout is result of combination of HTML code and
>PHP3 scripts. I don't think that we can get standartized set of pages with
>static HTML contents. In my opinion, it would be better to debug new web
>layout directly on server, otherwise we may reach unexpected problems when
>migrating from some private site.
>
>						Jaroslav
>
>-----
>Jaroslav Kysela <perex@suse.cz>
>Linux Kernel Sound Maintainer
>ALSA Project  http://www.alsa-project.org
>SuSE Linux    http://www.suse.com

_____________________________________________________________
Want a new web-based email account ? ---> http://www.firstlinux.net

Re: Status of ALSA documentation?

[Patrick Shirkey]

>
>If you are interested to reorganize contents of ALSA web site, I can give
>you CVS write access and you can show your ideas in some subdirectory for
>clarification.

I have a site where I can put up a revised homepage for now. 

I was just responding to the call for people to help with the administration of the site. 

I will work on a new layout over the next couple of days and let y'all know when I have it online.

Firstly can Juhana and others please let me know what you consider most important to be on the homepage?

So far I have gleaned this information:

1: Less developer news 
2: A mission statement
3: More emphasis on information related to vendors

What else do people want to see changed?




--
Patrick Shirkey - Boost Hardware Ltd
For the discerning hardware connoisseur
Http://www.boosthardware.com
Http://www.boosthardware.com/LAU/Linux_Audio_Users_Guide/


--- Jaroslav Kysela <perex@suse.cz> wrote:
>On Wed, 13 Feb 2002, Patrick Shirkey wrote:
>
>> ALSA is not an easy code base to come to grips with so we should apply the kiss rule (keep it simple stupid) to help newbies coders get their heads around it.
>>
>> >From my perspective the comments are not standardised enough. I haven't checked the code for a couple of months but last time I looked each file had a different approach to where and when comments were added.
>>
>> IMO if the developers could agree on a standard layout for every file then new developers would have much more chance of understanding how things work. Simply a matter of repetition.
>>
>> Apart from that what are the job requirements of an ALSA web maintainer and a documentation leader?
>>
>> EG.
>>
>> - How many hours per week are expected?
>> - What are the knowledge requirements?
>> - What are the legalities?
>> - What are the target responsibilties?
>> - What are the benefits?
>>
>> I am interested in the web site maintainer depending on the above requirements.
>
>Actually, our web is based on apache and PHP3 scripts. Perhaps, we can
>move to python (nice language) or PHP4 in future. I've created a CVS
>repository for WWW contents. Each commit automatically updates the WWW
>pages, so we have good management system for web.
>
>If you are interested to reorganize contents of ALSA web site, I can give
>you CVS write access and you can show your ideas in some subdirectory for
>clarification.
>
>Anyway, I am ready to answer any questions regarding ALSA. It's obvious.
>
>						Jaroslav
>
>-----
>Jaroslav Kysela <perex@suse.cz>
>Linux Kernel Sound Maintainer
>ALSA Project  http://www.alsa-project.org
>SuSE Linux    http://www.suse.com
>
>
>_______________________________________________
>Alsa-devel mailing list
>Alsa-devel@lists.sourceforge.net
>https://lists.sourceforge.net/lists/listinfo/alsa-devel

_____________________________________________________________
Want a new web-based email account ? ---> http://www.firstlinux.net

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Jaroslav Kysela]

On Thu, 14 Feb 2002, Patrick Shirkey wrote:

> >
> >If you are interested to reorganize contents of ALSA web site, I can give
> >you CVS write access and you can show your ideas in some subdirectory for
> >clarification.
>
> I have a site where I can put up a revised homepage for now.

I stated that the current layout is result of combination of HTML code and
PHP3 scripts. I don't think that we can get standartized set of pages with
static HTML contents. In my opinion, it would be better to debug new web
layout directly on server, otherwise we may reach unexpected problems when
migrating from some private site.

						Jaroslav

-----
Jaroslav Kysela <perex@suse.cz>
Linux Kernel Sound Maintainer
ALSA Project  http://www.alsa-project.org
SuSE Linux    http://www.suse.com


_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Mark Constable]

On Thu, 14 Feb 2002 20:02, Patrick Shirkey wrote:

> 1: Less developer news
> 2: A mission statement
> 3: More emphasis on information related to vendors
>
> What else do people want to see changed?

Developers are usually familiar with ALSA and know where
to look for further information. To me, the main strength
of the website should be for end-user information like
how to set up and configure ALSA drivers and modules so
clear links to HOWTOS and anything that eases the pain
for new ALSA users to get the most out of their audio
systems would be great.

I recently showed a Mac user interested in using Linux
for live stage work (no gui needed) the ALSA site so they
could get some idea of progress... they just laughed and
said there was _nothing_ there to help them evaluate whether
ALSA (therefor Linux) was going to be useful to them... well,
not within a 5 minute perusal anyway.

No doubt a slash/nuke-like portal would be asking too much ?

--markc

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Paul Davis]

>I recently showed a Mac user interested in using Linux
>for live stage work (no gui needed) the ALSA site so they
>could get some idea of progress... they just laughed and
>said there was _nothing_ there to help them evaluate whether
>ALSA (therefor Linux) was going to be useful to them... well,
>not within a 5 minute perusal anyway.

i think this is an excellent, critical point.

with ALSA's adoption into the kernel, we have both (1) a chance that
more people will write HOWTOs and code but also (2) more people saying
"what is it?" and "how do i ....?" the current web site fails
completely at both tasks.

as much as i think we are still aiming for uniform operation for all
cards (i.e. they just work), i think a good place to start with
interface HOWTOs would be to take Dan's soundcard matrix, and add
links from each card name to a HOWTO. The default set of HOWTOs can be
empty, and we can add to them as time goes on. By empty, what I really
mean is a boilerplate document that says "if you have this type of
soundcard, just do X, Y, and Z and it will work". 

there should also be a way to collect card-specific bug reports and
accessing them all from the HOWTO page. 

of course a wiki would be an even better way of collecting card/setup
specific quirks, but that seems a bit much to ask for right now.

of course, it becomes critical that the matrix be kept up to date,
which could also use a wiki-style input system.

--p

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Mark Constable]

On Fri, 15 Feb 2002 15:03, Paul Davis wrote:

> of course a wiki would be an even better way of collecting card/setup
> specific quirks, but that seems a bit much to ask for right now.
>
> of course, it becomes critical that the matrix be kept up to date,
> which could also use a wiki-style input system.

FWIW here is a quick and dirty Wiki that might encourage
someone to set up something for real, if it proves useful.
Having a Wiki is one thing, encouraging folks to actually
input something useful is another... but, it can't get any
easier than this for _anyone_ to contribute.

 http://alsa.opensrc.org/

--markc

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Patrick Shirkey]

ALSA is not an easy code base to come to grips with so we should apply the kiss rule (keep it simple stupid) to help newbies coders get their heads around it.

>From my perspective the comments are not standardised enough. I haven't checked the code for a couple of months but last time I looked each file had a different approach to where and when comments were added.

IMO if the developers could agree on a standard layout for every file then new developers would have much more chance of understanding how things work. Simply a matter of repetition.

Apart from that what are the job requirements of an ALSA web maintainer and a documentation leader?

EG.

- How many hours per week are expected?
- What are the knowledge requirements?
- What are the legalities?
- What are the target responsibilties?
- What are the benefits?

I am interested in the web site maintainer depending on the above requirements. 

As long as I can add it to my resume.

--
Patrick Shirkey - Boost Hardware Ltd
For the discerning hardware connoisseur
Http://www.boosthardware.com
Http://www.boosthardware.com/LAU/Linux_Audio_Users_Guide/


--- Kai Vehmanen <kai.vehmanen@wakkanet.fi> wrote:
>On Tue, 12 Feb 2002, Kevin Conder wrote:
>
>>>> last time I checked, the ALSA developers were adding doxygen comments to
>>>> the source code.
>>> The best part of javadoc is that it adds very little overhead.
>> 	I'm confused. Is the ALSA project using javadoc or doxygen?
>
>Good point. Javadoc is both a tool for extracting documentation (html)
>from Java code and a name for referring to the style of documenting (ie.
>putting documentation in the source code files). There are many tools for
>extracting javadoc-style documentations. Javadoc and doxygen are two
>well-known tools, but I've also used at least kdoc and scandoc. There are
>probably quite a few others available. Doxygen has been my personal 
>favorite for a while now (for C, C++ and Java).
>
>>> This may sound pessimistic, but a fact is that lots of time went to
>>> writing API docs for ALSA 0.3, 0.4 and 0.5. That time could have been
>>> instead spent on working on the code.
>> 	Are you implying that writing documentation is a waste of time?
>
>No, no. I just think a short but up-to-date reference manual is a lot
>better than huge amounts of unmaintained documentation. I've used this
>minimal approach in ecasound and it has worked really well. There's quite
>a lot of documentation available (and all of up-to-date!), but not too
>much for me to maintain (= I can spend most of my time on fixing bugs,
>implementing new features and improving old ones; things that I really
>like to do).
>
>For instance, let's say the following documents would exist:
>	- javadoc comments stored in CVS
>	- online implementation docs generated from 
>	  the javadocs
>	- reference manuals for alsa-kernel and alsa-lib APIs;
>	  possibly SGML stored in CVS
>	- web-version of the manuals at www.alsa-project.org;
>	  generated from SGML-files
>	- tutorial for writing ALSA apps; web site
>
>If you now add a new feature, you might need to update all the above. If
>you redesign some part of the system, you will have to rewrite the
>related chapters. In any case you have to remember what is documented
>where so you know when you need to update something.
>
>And just to make sure, these comments are aimed at ALSA as a free software
>project. In commercial software development the situation is completely
>different. There developers are expected to document their work and they
>get money from doing it.
>
>-- 
> http://www.eca.cx
> Audio software for Linux!
>
>
>_______________________________________________
>Alsa-devel mailing list
>Alsa-devel@lists.sourceforge.net
>https://lists.sourceforge.net/lists/listinfo/alsa-devel

_____________________________________________________________
Want a new web-based email account ? ---> http://www.firstlinux.net

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Kai Vehmanen]

On Wed, 13 Feb 2002, Patrick Shirkey wrote:

> Apart from that what are the job requirements of an ALSA web maintainer
> and a documentation leader?

Ok, do note that I'm not a member of the ALSA dev team, so I can't make
any real claims. Hopefully the dev team agrees with at least some of what
I'm about to say. :)

> - How many hours per week are expected?
> - What are the knowledge requirements?
> - What are the legalities?
> - What are the target responsibilties?
  
Like in most free sw project jobs, nobody can demand you any of the above.
If someone has problems with how you do the job, or how much time you
spend on the work, she should be prepared to work on it and do it better
(the 'show me the code' attitude :)). But if you take the job, complaints
_will_ be directed to you, whether justified or not.  On the other hand,
when you do your job well, people will appreciate it and also your
opinions will have more weight.

In the end, it's probably Jaroslav who decides who has access to modifying 
www.alsa-project.org (he owns the domain).

> - What are the benefits?

Big salary, fast cars and beautiful women! (or at least, your bug 
reports might get a priority flag every now and then) ;)

-- 
 http://www.eca.cx
 Audio software for Linux!


_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Jaroslav Kysela]

On Wed, 13 Feb 2002, Patrick Shirkey wrote:

> ALSA is not an easy code base to come to grips with so we should apply the kiss rule (keep it simple stupid) to help newbies coders get their heads around it.
>
> >From my perspective the comments are not standardised enough. I haven't checked the code for a couple of months but last time I looked each file had a different approach to where and when comments were added.
>
> IMO if the developers could agree on a standard layout for every file then new developers would have much more chance of understanding how things work. Simply a matter of repetition.
>
> Apart from that what are the job requirements of an ALSA web maintainer and a documentation leader?
>
> EG.
>
> - How many hours per week are expected?
> - What are the knowledge requirements?
> - What are the legalities?
> - What are the target responsibilties?
> - What are the benefits?
>
> I am interested in the web site maintainer depending on the above requirements.

Actually, our web is based on apache and PHP3 scripts. Perhaps, we can
move to python (nice language) or PHP4 in future. I've created a CVS
repository for WWW contents. Each commit automatically updates the WWW
pages, so we have good management system for web.

If you are interested to reorganize contents of ALSA web site, I can give
you CVS write access and you can show your ideas in some subdirectory for
clarification.

Anyway, I am ready to answer any questions regarding ALSA. It's obvious.

						Jaroslav

-----
Jaroslav Kysela <perex@suse.cz>
Linux Kernel Sound Maintainer
ALSA Project  http://www.alsa-project.org
SuSE Linux    http://www.suse.com


_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Status of ALSA documentation?

[Kevin Conder]

	I was wondering about the status of ALSA's API documentation. The
last time I checked, the ALSA developers were adding doxygen comments to
the source code. Was that project completed?


-- Kevin Conder, kevin@kevindumpscore.com



_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Kai Vehmanen]

On Tue, 12 Feb 2002, Kevin Conder wrote:

> 	I was wondering about the status of ALSA's API documentation. The
> last time I checked, the ALSA developers were adding doxygen comments to
> the source code. Was that project completed?

Yes and no. Just like code, there's always room for improvement. Anyway,
almost all functions are already documented, see:

http://www.alsa-project.org/alsa-doc/alsa-lib/index.html

It's not a tutorial, but as a reference documentation it really is quite 
good!

The best part of javadoc is that it adds very little overhead. Even if we
had complete documentation for ALSA0.9 available, I don't think the ALSA
team would have resources for maintaining it at the moment. Keeping the
javadoc comments up-to-date on the other hand involves much less work. No
reason to write more documentation if it's known before hand that nobody
has time to maintain it.

This may sound pessimistic, but a fact is that lots of time went to
writing API docs for ALSA 0.3, 0.4 and 0.5. That time could have been
instead spent on working on the code.

I've said this before and I'll say it again; my biggest worry is that ALSA
team will lose their interest because of the huge amount work they are
facing.  In free sw projects people should be able to concentrate on doing
what they love to do. If someone likes to write code, it's best for
everyone involved that he can keep on doing just that. In the end this is
the only way to keep projects going on for long periods of time.

-- 
 http://www.eca.cx
 Audio software for Linux!


_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Kevin Conder]

On Tue, 12 Feb 2002, Kai Vehmanen wrote:

> On Tue, 12 Feb 2002, Kevin Conder wrote:
> > The
> > last time I checked, the ALSA developers were adding doxygen comments to
> > the source code.
> 
> The best part of javadoc is that it adds very little overhead.

	I'm confused. Is the ALSA project using javadoc or doxygen?

> This may sound pessimistic, but a fact is that lots of time went to
> writing API docs for ALSA 0.3, 0.4 and 0.5. That time could have been
> instead spent on working on the code.

	Are you implying that writing documentation is a waste of time?


-- Kevin Conder, kevin@kevindumpscore.com



_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Kai Vehmanen]

On Tue, 12 Feb 2002, Kevin Conder wrote:

>>> last time I checked, the ALSA developers were adding doxygen comments to
>>> the source code.
>> The best part of javadoc is that it adds very little overhead.
> 	I'm confused. Is the ALSA project using javadoc or doxygen?

Good point. Javadoc is both a tool for extracting documentation (html)
from Java code and a name for referring to the style of documenting (ie.
putting documentation in the source code files). There are many tools for
extracting javadoc-style documentations. Javadoc and doxygen are two
well-known tools, but I've also used at least kdoc and scandoc. There are
probably quite a few others available. Doxygen has been my personal 
favorite for a while now (for C, C++ and Java).

>> This may sound pessimistic, but a fact is that lots of time went to
>> writing API docs for ALSA 0.3, 0.4 and 0.5. That time could have been
>> instead spent on working on the code.
> 	Are you implying that writing documentation is a waste of time?

No, no. I just think a short but up-to-date reference manual is a lot
better than huge amounts of unmaintained documentation. I've used this
minimal approach in ecasound and it has worked really well. There's quite
a lot of documentation available (and all of up-to-date!), but not too
much for me to maintain (= I can spend most of my time on fixing bugs,
implementing new features and improving old ones; things that I really
like to do).

For instance, let's say the following documents would exist:
	- javadoc comments stored in CVS
	- online implementation docs generated from 
	  the javadocs
	- reference manuals for alsa-kernel and alsa-lib APIs;
	  possibly SGML stored in CVS
	- web-version of the manuals at www.alsa-project.org;
	  generated from SGML-files
	- tutorial for writing ALSA apps; web site

If you now add a new feature, you might need to update all the above. If
you redesign some part of the system, you will have to rewrite the
related chapters. In any case you have to remember what is documented
where so you know when you need to update something.

And just to make sure, these comments are aimed at ALSA as a free software
project. In commercial software development the situation is completely
different. There developers are expected to document their work and they
get money from doing it.

-- 
 http://www.eca.cx
 Audio software for Linux!


_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Jaroslav Kysela]

On Tue, 12 Feb 2002, Kevin Conder wrote:

> On Tue, 12 Feb 2002, Kai Vehmanen wrote:
>
> > On Tue, 12 Feb 2002, Kevin Conder wrote:
> > > The
> > > last time I checked, the ALSA developers were adding doxygen comments to
> > > the source code.
> >
> > The best part of javadoc is that it adds very little overhead.
>
> 	I'm confused. Is the ALSA project using javadoc or doxygen?

doxygen, but the core of both systems is same, although doxygen is a bit
more enhanced.

> > This may sound pessimistic, but a fact is that lots of time went to
> > writing API docs for ALSA 0.3, 0.4 and 0.5. That time could have been
> > instead spent on working on the code.
>
> 	Are you implying that writing documentation is a waste of time?

We all know that it's not wasting time. Unfortunately, our group is not
very big and documentation process is not very quick at the moment. We
welcome any patches / additions / corrections regarding alsa-lib
documentation. I think that I put my ideas about documentation structure
to our current sources (the result is available at
http://www.alsa-project.org/alsa-doc/alsa-lib/)

We welcome any real documetation volunteers.

						Jaroslav

-----
Jaroslav Kysela <perex@suse.cz>
SuSE Linux    http://www.suse.com
ALSA Project  http://www.alsa-project.org


_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Guenther Sohler]

> Yes and no. Just like code, there's always room for improvement. Anyway,
> almost all functions are already documented, see:
> 
> http://www.alsa-project.org/alsa-doc/alsa-lib/index.html
> 
As I see, just the pcm functions are documented but the functions about midi
and about sequencer are much more impotant. they are not there.
I have seen documentation about 0.5.x for alsa and they are documented there,
but the functions have changed too much to be able to use it.
Where can I find the latest documetnation on midi and sequencer for alsa ?

rds guenther

_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Re: Status of ALSA documentation?

[Jaroslav Kysela]

On Wed, 13 Feb 2002, Guenther Sohler wrote:

> > Yes and no. Just like code, there's always room for improvement. Anyway,
> > almost all functions are already documented, see:
> >
> > http://www.alsa-project.org/alsa-doc/alsa-lib/index.html
> >
> As I see, just the pcm functions are documented but the functions about midi
> and about sequencer are much more impotant. they are not there.
> I have seen documentation about 0.5.x for alsa and they are documented there,
> but the functions have changed too much to be able to use it.
> Where can I find the latest documetnation on midi and sequencer for alsa ?

They will be available when someone (probably my and Takashi's hands)
write it.  There are no many changes in principles for these interfaces.
The main difference is that the access to most data structures goes via
functions.

						Jaroslav

-----
Jaroslav Kysela <perex@suse.cz>
SuSE Linux    http://www.suse.com
ALSA Project  http://www.alsa-project.org


_______________________________________________
Alsa-devel mailing list
Alsa-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/alsa-devel