I've re-written the existing ALSA guide to fix Bug 89521 and make the doc a wee bit more better to understand and make the install options clear to the end user. This is complete re-write of the doc from scratch....this means that except for at most 2 sections, the rest of the doc has completely changed. Attaching two image files as well, for alsamixer. There is no section on Joystick support in the new doc as my sound card has no joystick port and I couldn't verify the correctness of the earlier doc as well. I aslo just had a look at overview.xml and saw Bug 48733 which again, I couldn't test. Would be nice if someone could. Attachments to follow.
Created attachment 58891 [details] New alsa-guide.xml
Created attachment 58892 [details] Fig 1 - AlsaMixer Muted
Created attachment 58893 [details] Fig 2 - AlsaMixer Unmuted
see http://neverland.ncssm.edu/~smithj/gentoo/alsa-guide.html for the rendered html (total rewrites and new docs are a pain to read by hand sometimes)
I have several remarks: a) Last section about saying "thanks" - I see that author tried to give credits to the original authors, but I don't know about any other guide doing so. b) `cat .config | grep blah` - use `grep blah .config` instead ;-) c) Ad in-kernel ALSA vs. alsa-driver usage - I'm not sure that the guide should suggest using alsa-driver as it requires rebuild after every kernel upgrade, and, to my current knowledge, Portage can't automate it yet. So I think that the warning about this topic should be added to the second paragraph where the reader is presented with his/her choices. So, my suggestions coming from c): 1) Add note about need of rebuilding to the beginning of the guide (I know it is in the middle) 2) Don't recommend alsa-driver as default just because it is newer And finally d): d) In the Handbook, text above code listings often end with colon. I vote for style unification.
a) Personally, I don't see the problem in thanking people for their work. And hey, lets set a good precedent :) Part of this guide were taken verbatim from the old one (timidity++) and well, those guys did the old doc, I think there's nothing wrong in mentioning them. b) Totally agreed. Dumb mistake ;) c) This needs to be debated/pros-cons discussed. Personally, I'm in favor of ALSA in the kernel as its less painful. Also, genkernel seems to be configured with modularized ALSA built-in by default. Which means, no alsa-driver. Also do you think a pros vs cons analysis would be good in the guide? d) Will add colons as appropriate, if it makes it look better ;) And I guess I'll be the best one to make the mods, so I'll handle the doc till it goes live. Thanks!
a) Isn't it enough to mark them as authors/editors/contributors/whatever? c) Good idea d) It's up to you, do whatever you consider appropriate ;-)
a) Too long a list. Easier thanking them this way.
the other problem with listing them in the author's section is that they had very little to do with this new document. we would be giving them credit/blame (depending on your view ;-) for something that they had no part in... i like fox2mike's solution
Good doc, fox2mike! Might I suggest that we advise people going with the "in-kernel" option to add "media-sound/alsa-driver" to /etc/portage/package.provided ? This way, the user will not have to worry about alsa-driver getting emerge'd when some other package depends on it. Also, a simple, unbiased Pros/Cons list at the beginning of the doc to help pick alsa-driver vs. in-kernel would help the impatient. Something like: Replace: -<p> -The main difference between using <c>alsa-driver</c> and ALSA that comes with -the kernel is that <c>alsa-driver</c> is generally more up to date than the -version in the kernel. Although this does not make any huge difference as -such, people are encouraged to use <c>alsa-driver</c> since it is the latest. -</p> With: +Advantages of In-Kernel: +1) Don't have to remerge alsa-driver for each kernel compile + +Advantages of alsa-driver: +1) Don't have to manually compile your kernel +2) Being a part of 'portage' it's the Better(tm) option +3) Might be slightly more recent than the kernel version Gosh, this *must* makes the user a bit biased towards alsa-driver. :)
Arun, iirc there are shouldn't be any packages depending at alsa-driver, we have something like virtual/alsa for it. Ad advantages of alsa-driver: 1) Incorrect, genkernel provides correct ALSA environment (sometimes, should be fixed - bug 92711) 2) Irrelevant - sys-kernel/*-sources are part of Portage tree, too.
Jan, I remember having to add alsa-driver to packages.provided...but that issue does seem to have been resolved now. Arun, I think I'll go ahead with a pros/cons analysis...seems a nice way to present it to the end-user. I shall do that after we have a decent set of pros and cons.
What can I do with virtuals/alsa? And would it not be a good thing to document it in this guide?
re comment 13: Nothing, Arun. You don't have to care about it, as all kernel ebuilds based on kernel-2.eclass provide virtual/alsa.
*** Bug 89521 has been marked as a duplicate of this bug. ***
*** Bug 92912 has been marked as a duplicate of this bug. ***
*** Bug 92909 has been marked as a duplicate of this bug. ***
FWIW, I would have prefered to see 'kernel modules vs. alsa-driver modules', recommend kernel modules, explain how to install each, configure modules which is identical in both cases. Using modules in both cases makes it easier to try alsa-driver
(In reply to comment #18) > FWIW, I would have prefered to see 'kernel modules vs. alsa-driver modules', > recommend kernel modules, explain how to install each, configure modules which > is identical in both cases. Using modules in both cases makes it easier to try > alsa-driver I see what you're getting at. Will change the kernel method to modules. Though "trying" alsa-driver means disabling kernel support for ALSA altogether, not even as a module. CONFIG_SND should not be set or alsa-driver will fail.
*** Bug 92914 has been marked as a duplicate of this bug. ***
Created attachment 59208 [details] Updated new alsa-guide.xml Righto, this is pretty much a final draft, unless there are any major changes.... a) Pros and Cons for Kernel ALSA vs alsa-driver b) Kernel ALSA recommended as default c) Kernel ALSA now recommends modular kernel d) genkernel users have now been asked to go ahead and configure ALSA, since their current config builds ALSA support in the kernel. This may change, based on the outcome of Bug 92711
(In reply to comment #21) > Created an attachment (id=59208) [edit] > Updated new alsa-guide.xml Could the person who commits the doc please bump version to 1.1 and date to 18 May. I forgot to do that in the attachment. TIA
fox2mike, i was looking through the bugs which had been marked LATER by the docs-team, and came accross bug 48733, which might be useful to integrate into yoru guide besides, it will give you something to do while waiting for ro cvs access from infra ;-)
Shyam: a couple of comments. 1/ You use a link to "ALSA Utilities" in your guide but call the link "ALSA Utils". Perhaps it would be easier if you stick with the name. Also, perhaps using id="alsa-utils" and then <uri link="#alsa-utils"> instead of <uri link="#doc_chap3_sect1"> might make that a bit better. 2/ Having a link <uri link="...">this</uri> isn't good writing. This is called the "here-syndrome" (like "Click _here_"). It might also be interesting to view the CVS history of the ALSA Guide to see what issues we had and the resolution. One mistake I frequently make when I rewrite stuff is to undo changes (fixes) made to a guide. Also, although I have been victim of this myself until recently, do we want to stick with correct grammar/spelling or with common grammar/spelling? For instance: soundcard isn't good English, "sound card" is. But "soundcard" is commonly used for a "sound card".
(In reply to comment #24) > 1/ You use a link to "ALSA Utilities" in your guide but call the link "ALSA > Utils". Perhaps it would be easier if you stick with the name. Also, perhaps > using id="alsa-utils" and then <uri link="#alsa-utils"> instead of <uri > link="#doc_chap3_sect1"> might make that a bit better. Agreed. Have changed the sect links. > 2/ Having a link <uri link="...">this</uri> isn't good writing. This is called > the "here-syndrome" (like "Click _here_"). Changed. The only place that had this now reads : If you don't have an idea of what drivers your soundcard might need, please take a look at the "lspci" section of this guide. > It might also be interesting to view the CVS history of the ALSA Guide to see > what issues we had and the resolution. One mistake I frequently make when I > rewrite stuff is to undo changes (fixes) made to a guide. I've been keeping the current alsa-guide for reference throughout...so I guess that any fixes in place on the old guide have been carried over.... > Also, although I have been victim of this myself until recently, do we want to > stick with correct grammar/spelling or with common grammar/spelling? I'd go for correct grammar/spelling. But that's your call :) Either is fine with me. Also, could you please look at Bug 48733, which you've marked as LATER? If we could push that into the doc as well, would be nice.
I'm a "Correct English" Nazi myself, but I think soundcard is easier to read than sound card. Correct English rules should be slightly flexible when the context is technical.
http://xinetd.accosted.net/gentoo/alsa-guide-beta.html Absolute latest version, changes made (wrt comment #24) haven't yet been attached to this bug, but are online at the above URL.
1) alsa-driver pros: Bleeding edge, latest drivers. You probably want to make this latest drivers (or latest and greatest :) ). Bleeding edge implies that stuff might be broken/not fully tested. 2) This message ... "Important: genkernel users have their config built such a way that the ALSA sub-system in the kernel is active. Therefore genkernel users can proceed to the ALSA Utilities section directly. " ... might make more sense near the beginning of the "Options Galore" section. If the user doesn't have to consider his options, let him/her know it at the earliest OTOH, it might make sense to make this one more option (in addition to a hand-compiled kernel and alsa-driver), since this implies a whole different path for the user - one that involves *very* little work. 3) The options listed as: "The first method of getting ALSA support running on Gentoo is to compile ALSA support into your kernel and is the preferred/recommended one. The second method is to use media-sound/alsa-driver provided by Gentoo. We shall take a peek into both before finally deciding on one." Would look better as a numbered list - options, when presented as a list, are easier for the user to parse. 4) Don't know if this is a good idea, but in the alsamixer section, do we want to tell the user to use Q/A and W/S keys to increase/decrease the volumes of the left and right channels separately? 5) If the user is using a desktop like KDE/GNOME, do we want to mention that he/she can use whatever mixer application they wish instead of alsamixer? This also applies to the part about emerge'ing xmms/mpg123/madplay. The downside of all this is that we're being very verbose about a straightforward process.
(In reply to comment #28) > 1) alsa-driver pros: Bleeding edge, latest drivers. > You probably want to make this latest drivers (or latest and greatest :) ). > Bleeding edge implies that stuff might be broken/not fully tested. Done. > 2) This message ... > ... might make more sense near the beginning of the "Options Galore" section. Done. > OTOH, it might make sense to make this one more option (in addition to a > hand-compiled kernel and alsa-driver), since this implies a whole different path > for the user - one that involves *very* little work. Not right now. Genkernel -> SuX0r :) Let that settle down first. > 3) The options listed as: > Would look better as a numbered list - options, when presented as a list, are > easier for the user to parse. Done. > 4) Don't know if this is a good idea, but in the alsamixer section, do we want > to tell the user to use Q/A and W/S keys to increase/decrease the volumes of the > left and right channels separately? Doesn't actually matter. > 5) If the user is using a desktop like KDE/GNOME, do we want to mention that > he/she can use whatever mixer application they wish instead of alsamixer? This > also applies to the part about emerge'ing xmms/mpg123/madplay. The downside of > all this is that we're being very verbose about a straightforward process. I ran alsaconf and the sound applet in Gnome was reloaded....I couldn't unmute using the applet. I *had* to run alsamixer to fix that. Instead of confusing everyone, I guess alsamixer = straightforward + easy method. The emerge xmms/blahfoo is *only* there as an example. Use what you like. The doc isn't a "have to follow", just a "how-to" :) Other changes in the upcoming version : 1) Changes of <e>XYZ</e> to <e>xyz</e> 2) alsaconf corrections 3) Minor changes to code listing(s) 4) Typos + Grammatical errors corrected. 5) ogg and ogg examples added coz Xavier would have killed me otherwise ;)
Created attachment 60469 [details] New alsa-guide.xml, take 3 Changes according to Comment #29
Created attachment 60473 [details] New alsa-guide.xml, take 4 Tons of spelling + grammar corrections.... Thanks (or no thanks) to Sven and Xavier :)
wrt bug #92711, plasmaroo says the genkernel config patch I submitted is in portage but that release of genkernel is p.masked. If that goes live, this doc will undergo a few minor changes...to the effect that running genkernel or not doesn't make a difference...you would still be able to choose in-kernel or alsa-driver. No timeframe on when that release of Genkernel will go live, so I guess we won't wait for that. Doc can be patched later in case genkernel is still masked at time of commit.
the images are available under: - "/images/docs/alsa-mixermuted.png" - "/images/docs/alsa-mixerunmuted.png" Adjust your guide accordingly.
Commited to CVS, thanks everyone for their suggestions!
