ALSA docs

ALSA docs

[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.

Rgds.

-- 
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

Re: ALSA docs

[Takashi Iwai]

At Sat, 20 Jul 2002 01:17:46 +0900,
Patrick Shirkey wrote:
> 
> 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.

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

Re: ALSA docs

[Patrick Shirkey]

Takashi Iwai wrote:
> At Sat, 20 Jul 2002 01:17:46 +0900,
> Patrick Shirkey wrote:
> 
>>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.
> 
> 
> 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.

> 
> 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.


-- 
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

Re: ALSA docs

[Patrick Shirkey]

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.



-- 
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

Re: ALSA docs

[Paul Davis]

>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

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

Re: ALSA docs

[Patrick Shirkey]

Paul Davis wrote:

> 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.


-- 
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

Re: ALSA docs

[Patrick Shirkey]

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)


-- 
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

Re: ALSA docs

[Paul Davis]

>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.

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

Re: ALSA docs

[Patrick Shirkey]

Paul Davis wrote:
>>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.
> 
> 
> 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?

> 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.

-- 
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

Re: ALSA docs

[Paul Davis]

>> 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.

>> 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

Re: ALSA docs

[Patrick Shirkey]

Paul Davis wrote:
>>>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.
> 
> 
>>>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.
> 

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 ???


-- 
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

Re: ALSA docs

[Paul Davis]

>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

Re: ALSA docs

[Patrick Shirkey]

Paul Davis wrote:
>>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 ...
> 

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 ;] ).

-- 
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

Re: ALSA docs

[Patrick Shirkey]

>> 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]);
>>           }
>> }
>>
>> 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.

-- 
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

Re: ALSA docs

[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.

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