ALSA docs
I'm in the process of reading up about different ways of setting up the new alsa docs so that they are in the style of the new website design and have the look and feel of current documentation on other websites.
I'm using the online manual for http://www.php.net as the design basis.
Before I spend any more time on coding up a dynamic user maintained/contributed site what is the general consensus on allowing contribution to the documentation from anybody?
I have an almost fully working setup now which will allow users to contribute ideas and helpful hints. The problem I now face is whether or not to automate the input or filter it by having it sent to me (or other people) so I/we can post it at our discretion.
I note that a lot of sites that seemed to originally have allowed input from users to be automatically added to their webpages have decided to change their policy to filtering due to spam or misleading information being posted.
Rgds.
Signature · 12 lines
Patrick Shirkey - Boost Hardware Ltd. For the discerning hardware connoisseur Http://www.boosthardware.com Http://www.boosthardware.com/LAU/guide/ ======================================== ------------------------------------------------------- This sf.net email is sponsored by:ThinkGeek Welcome to geek heaven. http://thinkgeek.com/sf
At Sat, 20 Jul 2002 01:17:46 +0900,
Quoted 16 lines · Patrick Shirkey
I'm in the process of reading up about different ways of setting up the new alsa docs so that they are in the style of the new website design and have the look and feel of current documentation on other websites.
I'm using the online manual for http://www.php.net as the design basis.
Before I spend any more time on coding up a dynamic user maintained/contributed site what is the general consensus on allowing contribution to the documentation from anybody?
I have an almost fully working setup now which will allow users to contribute ideas and helpful hints. The problem I now face is whether or not to automate the input or filter it by having it sent to me (or other people) so I/we can post it at our discretion.
Quoted 4 lines
I note that a lot of sites that seemed to originally have allowed input from users to be automatically added to their webpages have decided to change their policy to filtering due to spam or misleading information being posted.
imo, the documents on the "official" web site should be reviewed and moderated. one reason is to keep the contents technically correct, and another is to keep the consistency of the page design (and to avoid possible spam problems as you mentioned above, of course).
for auto-generated documents, we already have wiki. isn't it enough?
i've been very impressed by the convenience of wiki.
well, if you think it's too much for you to moderate the input from users, then i don't mind to change this policy.
Takashi
-------------------------------------------------------
This sf.net email is sponsored by:ThinkGeek
Welcome to geek heaven.
http://thinkgeek.com/sf
Quoted 14 lines · Takashi Iwai
At Sat, 20 Jul 2002 01:17:46 +0900,
Quoted 9 lines · Patrick Shirkey
I'm in the process of reading up about different ways of setting up the new alsa docs so that they are in the style of the new website design and have the look and feel of current documentation on other websites.
I'm using the online manual for http://www.php.net as the design basis.
Before I spend any more time on coding up a dynamic user maintained/contributed site what is the general consensus on allowing contribution to the documentation from anybody?
I have an almost fully working setup now which will allow users to contribute ideas and helpful hints. The problem I now face is whether or not to automate the input or filter it by having it sent to me (or other people) so I/we can post it at our discretion.
I note that a lot of sites that seemed to originally have allowed input from users to be automatically added to their webpages have decided to change their policy to filtering due to spam or misleading information being posted.
Quoted 9 lines
imo, the documents on the "official" web site should be reviewed and moderated. one reason is to keep the contents technically correct, and another is to keep the consistency of the page design (and to avoid possible spam problems as you mentioned above, of course).
for auto-generated documents, we already have wiki. isn't it enough?
i've been very impressed by the convenience of wiki.
Yes me too.
Quoted 3 lines
well, if you think it's too much for you to moderate the input from users, then i don't mind to change this policy.
I don't mind being a moderator if people trust my judgement enough. If it becomes a too much work then we can change how it's done. Keep things fluid.
Signature · 12 lines
Patrick Shirkey - Boost Hardware Ltd. For the discerning hardware connoisseur Http://www.boosthardware.com Http://www.boosthardware.com/LAU/guide/ ======================================== ------------------------------------------------------- This sf.net email is sponsored by:ThinkGeek Welcome to geek heaven. http://thinkgeek.com/sf
I have the working version of the template for the new improved docs.
Can people who have a spare moment have a look through it for obvious mistakes. Any additions to the text will also be appreciated.
I've looked at it so many times now I need a fresh eye to spot my mistakes.
http://www.alsa-project.org/alsa-doc/doc-php/cmipci.php3
I have added a form mailer which will allow anyone to contribute. Currently the messages are sent to me where I will moderate and add info that is relevant.
I still need to work on other topics like .asoundrc and using alsa via the 2.5.x kernel. But now the form mailer is done I will have more time for those things.
There is one bug that I haven't figured out yet. The text for the notes can be corrupted by certain characters like ' " `. I need to figure out how to get the text to be formatted as <pre> html and that should fix the bug.
Signature · 10 lines
Patrick Shirkey - Boost Hardware Ltd. For the discerning hardware connoisseur Http://www.boosthardware.com Http://www.boosthardware.com/LAU/guide/ ======================================== ------------------------------------------------------- This sf.net email is sponsored by: Jabber - The world's fastest growing real-time communications platform! Don't just IM. Build it in! http://www.jabber.com/osdn/xim
Quoted 8 lines
I have the working version of the template for the new improved docs.
Can people who have a spare moment have a look through it for obvious mistakes. Any additions to the text will also be appreciated.
I've looked at it so many times now I need a fresh eye to spot my mistakes.
no mistakes, but i still think it very, very important that the link to the section on card-specific options be clear and distinct from everything else.
new users may want to see the rest, but in a relatively short time, most of the views of this page will be by people who are looking up specific information. there is a link to this already, but its not obvious enough for my taste.
put it as the first element in the "table of contents", and use a couple of <br> elements to make it stand apart from the rest.
there also needs to be a place for information about card-specific control switches too.
--p
-------------------------------------------------------
This sf.net email is sponsored by: Jabber - The world's fastest growing real-time communications platform! Don't just IM. Build it in!
http://www.jabber.com/osdn/xim
Quoted 3 lines · Paul Davis
there also needs to be a place for information about card-specific control switches too.
Are there many cards that have controls switches? If there are not then I can see a reason to make that component optional to the template.
How should I describe them? I have never used a card that has them before.
Signature · 10 lines
Patrick Shirkey - Boost Hardware Ltd. For the discerning hardware connoisseur Http://www.boosthardware.com Http://www.boosthardware.com/LAU/guide/ ======================================== ------------------------------------------------------- This sf.net email is sponsored by: Jabber - The world's fastest growing real-time communications platform! Don't just IM. Build it in! http://www.jabber.com/osdn/xim
I'm looking into ways to automate the modules options component file for
the docs.
At the moment I am considering using perl or mysql. Does anyone know which is easier to setup to do the following.
Parse the INSTALL file for a module name.
Return the info for that module.
Then either
Write the module info to a temp file which is inserted into the template
or
insert the module info into the template.
The problem with mysql is that I would need access to the database. The good thing is that it wouldn't have to get the info everytime a webpage was accessed only when the info changed. (I think)
Signature · 10 lines
Patrick Shirkey - Boost Hardware Ltd. For the discerning hardware connoisseur Http://www.boosthardware.com Http://www.boosthardware.com/LAU/guide/ ======================================== ------------------------------------------------------- This sf.net email is sponsored by: Jabber - The world's fastest growing real-time communications platform! Don't just IM. Build it in! http://www.jabber.com/osdn/xim
Quoted 9 lines
I'm looking into ways to automate the modules options component file for
the docs.At the moment I am considering using perl or mysql. Does anyone know which is easier to setup to do the following.
Parse the INSTALL file for a module name.
Return the info for that module.
Quoted 7 lines
Then either
Write the module info to a temp file which is inserted into the template
or
insert the module info into the template.
i would personally work from a complete set of snd-* modules, and use modinfo(1) + perl to get the information and put that into the temp file that is inserted into the template, or if possible, put it straight into the template.
--p
-------------------------------------------------------
This sf.net email is sponsored by:ThinkGeek
Welcome to geek heaven.
http://thinkgeek.com/sf
Quoted 8 lines
Quoted 3 lines
there also needs to be a place for information about card-specific control switches too.
Are there many cards that have controls switches? If there are not then I can see a reason to make that component optional to the template.
How should I describe them? I have never used a card that has them before.
every card with s/pdif i/o has them, just as a start. this is a bad example, since the format of this switch is supposed to be standard, but thats true of many module options too.
--p
-------------------------------------------------------
This sf.net email is sponsored by:ThinkGeek
Welcome to geek heaven.
http://thinkgeek.com/sf
Quoted 11 lines · Paul Davis
Quoted 11 lines
I'm looking into ways to automate the modules options component file for the docs.
At the moment I am considering using perl or mysql. Does anyone know which is easier to setup to do the following.
Parse the INSTALL file for a module name.
Return the info for that module.Then either
Write the module info to a temp file which is inserted into the template
Quoted 7 lines
Quoted 3 lines
or
insert the module info into the template.
i would personally work from a complete set of snd-* modules, and use modinfo(1) + perl to get the information
Isn't that what happens in the INSTALL file anyway?
Quoted 4 lines
and put that into the temp
file that is inserted into the template, or if possible, put it straight into the template.
IIRC doing the above would need access to a set of modules online. Seems unneccesary when the INSTALL file is already available.
But I'm willing to be told otherwise if it makes the info more reliable.
Signature · 12 lines
Patrick Shirkey - Boost Hardware Ltd. For the discerning hardware connoisseur Http://www.boosthardware.com Http://www.boosthardware.com/LAU/guide/ ======================================== ------------------------------------------------------- This sf.net email is sponsored by: Dice - The leading online job board for high-tech professionals. Search and apply for tech jobs today! http://seeker.dice.com/seeker.epl?rel_code=31
Quoted 4 lines
Quoted 2 lines
i would personally work from a complete set of snd-* modules, and use modinfo(1) + perl to get the information
Isn't that what happens in the INSTALL file anyway?
it doesn't look like it. there are several cards missing there, and it looks hand-written rather then fetched from the source.
Quoted 9 lines
Quoted 4 lines
and put that into the temp
file that is inserted into the template, or if possible, put it straight into the template.IIRC doing the above would need access to a set of modules online. Seems unneccesary when the INSTALL file is already available.
But I'm willing to be told otherwise if it makes the info more reliable.
it would be much more reliable if you got the options from the modules themselves. even just running grep for MOD_PARM etc. would be better than using the INSTALL file.
--p
-------------------------------------------------------
This sf.net email is sponsored by: Dice - The leading online job board for high-tech professionals. Search and apply for tech jobs today!
http://seeker.dice.com/seeker.epl?rel_code=31
Quoted 15 lines · Paul Davis
Quoted 4 lines
Quoted 2 lines
i would personally work from a complete set of snd-* modules, and use modinfo(1) + perl to get the information
Isn't that what happens in the INSTALL file anyway?
it doesn't look like it. there are several cards missing there, and it looks hand-written rather then fetched from the source.
Quoted 5 lines
Quoted 4 lines
and put that into the temp
file that is inserted into the template, or if possible, put it straight into the template.
Quoted 9 lines
Quoted 3 lines
IIRC doing the above would need access to a set of modules online. Seems unneccesary when the INSTALL file is already available.
But I'm willing to be told otherwise if it makes the info more reliable.
it would be much more reliable if you got the options from the modules themselves. even just running grep for
MOD_PARMetc. would be better than using the INSTALL file.
Do you mean that I should be parsing each driver file seperately?
I think it would be easier to get the autoconf process to create a file which prints all the modules options and controls to a file which is included in the main alsa-drivers source dir eg the INSTALL file. Then I can just parse that with php.
This will definitely save on server traffic. And hence bills.
Is there anyone who has the time to write this or at least give me a good very specific how to do it?
I guess some/most of the work is already done in the alsaconf scripts ???
Signature · 12 lines
Patrick Shirkey - Boost Hardware Ltd. For the discerning hardware connoisseur Http://www.boosthardware.com Http://www.boosthardware.com/LAU/guide/ ======================================== ------------------------------------------------------- This sf.net email is sponsored by: Dice - The leading online job board for high-tech professionals. Search and apply for tech jobs today! http://seeker.dice.com/seeker.epl?rel_code=31
Quoted 1 line
Do you mean that I should be parsing each driver file seperately?
not really, just do a single pass over each one of them at some point in time. store the results, and use them. this should get you started (its not perfect, but it doesn't do a bad job.
#!/usr/local/bin/perl
while(<>) {
if (/MODULE_PARM_DESC/) {
@foo = split /[()]/;
@bar = split (/,/, $foo[1], 2);
$bar[1] =~ s/"//g;
printf ("%-32s %s\n", $bar[0], $bar[1]);
}
}add something to recurse through the source tree, and include the module name and card name info, and you're pretty much done ...
--p
-------------------------------------------------------
This sf.net email is sponsored by: Dice - The leading online job board for high-tech professionals. Search and apply for tech jobs today!
http://seeker.dice.com/seeker.epl?rel_code=31
Quoted 18 lines · Paul Davis
Quoted 1 line
Do you mean that I should be parsing each driver file seperately?
not really, just do a single pass over each one of them at some point in time. store the results, and use them. this should get you started (its not perfect, but it doesn't do a bad job.
#!/usr/local/bin/perl
while(<>) { if (/MODULE_PARM_DESC/) { @foo = split /[()]/; @bar = split (/,/, $foo[1], 2); $bar[1] =~ s/"//g; printf ("%-32s %s\n", $bar[0], $bar[1]); } }
Quoted 3 lines
add something to recurse through the source tree, and include the module name and card name info, and you're pretty much done ...
Now that I think about it I could probably get away with doing this on my computer everytime that a new driver is added. We have to add the info manually for the soundcard matrix anyway.
Although If I don't have access to a working Linux computer in the future this will cause problems. Ideally I would like a way to do this all from online preferably automagically.
I'm loathe to admit but I am very new to perl so I don't even know how to call the above code from a webpage. Is it possible to get the perl script to parse the files and then use php to parse the output of the perl script? I have various variables from a form which php can understand and use to create the correct output in the template.
Unless Dan Hollis speaks up soon (I tried to contact him last Friday) I'm officially commandeering the Soundcard matrix from his dir and putting it in the alsa-docs dir. Where it will become the opening page to the driver docs. He will need to get cvs access for the www dir from Jaroslav to edit the new version of the matrix.
You can see what I'm trying to do here:
http://www.alsa-project.org/alsa-doc/ALSA_Soundcard_Matrix.php3
That is unless other people have a better idea for how to make the docs more user friendly (and competitive ;] ).
Signature · 12 lines
Patrick Shirkey - Boost Hardware Ltd. For the discerning hardware connoisseur Http://www.boosthardware.com Http://www.boosthardware.com/LAU/guide/ ======================================== ------------------------------------------------------- This sf.net email is sponsored by: Dice - The leading online job board for high-tech professionals. Search and apply for tech jobs today! http://seeker.dice.com/seeker.epl?rel_code=31
Quoted 13 lines
Quoted 13 lines
Paul Davis wrote:
#!/usr/local/bin/perl
while(<>) { if (/MODULE_PARM_DESC/) { @foo = split /[()]/; @bar = split (/,/, $foo[1], 2); $bar[1] =~ s/"//g; printf ("%-32s %s\n", $bar[0], $bar[1]); } }
Quoted 3 lines
Quoted 3 lines
add something to recurse through the source tree, and include the module name and card name info, and you're pretty much done ...
I tried the above but it didn't work for me by itself and I don't have the insight at the moment to get it to. Thanks anyway because you jogged my memory.
I remembered that Jaroslav had given me a command a while ago (last year) to get the module options for each module.
modinfo $(modprobe -l snd-*) | cat > /art/code/alsa/modinfo
This returns a reasonably readable file. If I make a perl script to parse that and print a more readable version then I have what I need for now.
Signature · 12 lines
Patrick Shirkey - Boost Hardware Ltd. For the discerning hardware connoisseur Http://www.boosthardware.com Http://www.boosthardware.com/LAU/guide/ ======================================== ------------------------------------------------------- This sf.net email is sponsored by: Dice - The leading online job board for high-tech professionals. Search and apply for tech jobs today! http://seeker.dice.com/seeker.epl?rel_code=31