[PATCH] sound(4) related manpages 5.3 TODO item

Gang,

[ Please keep me Cc:ed when replying. ]

I've picked up the "sound(4) related manual pages" item from
the 5.3-RELEASE TODO list.

While working on adopting the pcm(4) and related manpages to
the new world order, I have noticed some odds that I'd like
your comments on first, before I proceed further.

One and most important thing I'm not sure I understand, and
that's causing a lot of confusion, is why "device pcm" was
renamed to "device sound" in the first place?  I believe the
reason is that "device sound" is a generic sound driver,
which has support for PCM playback, mixer, /dev/sndstat,
eventually MIDI, sequencer, and so on.  Individual sound
drivers are free to implement either of these interfaces.
Most of them implement "pcm" nowadays, so saying that
"pcm was renamed to sound" is not quite correct.  In other
words, the sound.ko module provides the infrastructure for
more than just PCM, and the sound(4) manpage should eventually
document more than just PCM.  Does that sound correct?

Also, there seems to be some confusion between the modules,
drivers, and devices that they implement, which are different
beasties, and are often named differently, and this causes
some misunderstandings and bugs (see below).

Anyway, the attached patch adopts the sound(4) related man
pages to the new world order.  How to proceed:

1.  The following repo-copies in /home/ncvs/src/share/man/man4
    should be made (there were made locally to produce the
    patch):

	pcm.4,v -> sound.4,v
	csa.4,v -> snd_csa.4,v
	gusc.4,v -> snd_gusc.4,v 
	maestro3.4,v -> snd_maestro3.4,v 
	sbc.4,v -> snd_sbc.4,v
	uaudio.4,v -> snd_uaudio.4,v

2.  The old manpages (on the left) were removed, and aren't
    included in the patch.

3.  After repo-copies and deletes, the attached patch should be
    applied.  It's mostly mechanical (foo -> snd_foo, pcm -> sound),
    with the following notable exceptions:

  - Note that non-PnP ISA cards, such as those handled by snd_mss(4)
    and snd_ad1816(4), still require hints of the form

	hint.pcm.0.at="isa"
	hint.pcm.0.irq="5"
	hint.pcm.0.drq="1"
	hint.pcm.0.flags="0x0"

    because they implement device "pcm".  Granted, the difference
    between module and driver name is confusing enough that Seigo
    misspelled hints names in sys/conf/NOTES, and Simon misspelled
    them in the new snd_ad1816(4) manpage.  The patch corrects the
    hints names in the snd_ad1816(4) manpage and NOTES.  The patch
    removes the "hint.snd_mss" from NOTES because (like was said)
    the snd_mss(4) module implements the "pcm" device, hence the
    hints start with "hint.pcm", and this is already documented
    in the sound(4) manpage.  Module snd_sbc(4) and snd_gusc(4)
    are special in that they implement PCM support through the
    bridge device ("sbc" and "gusc", respectively), with "pcm"
    device as a child.  For them, ISA hints should be spelled
    "hint.sbc" and "hint.gusc", respectively.  This is also fixed
    in NOTES.

  - The patch also fixes the SYNOPSIS section of the snd_maestro3(4)
    manpage to align it with other sound drivers manpages, and adds
    missing "device sound" to almost all of the snd_*(4) manpages.

Does that look sane?  I'd be grateful is someone more fluent with
our sound subsystem could review this.


Cheers,
-- 
Ruslan Ermilov
ru_at_FreeBSD.org
FreeBSD committer