docs/114718: grammar, etc. in handbook/multimedia (part 1)
Ben Kaduk
minimarmot at gmail.com
Thu Jul 19 03:30:04 UTC 2007
>Number: 114718
>Category: docs
>Synopsis: grammar, etc. in handbook/multimedia (part 1)
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Thu Jul 19 03:30:03 GMT 2007
>Closed-Date:
>Last-Modified:
>Originator: Ben Kaduk
>Release: 7.0-CURRENT
>Organization:
>Environment:
System: FreeBSD prolepsis.scs.uiuc.edu 7.0-CURRENT FreeBSD 7.0-CURRENT #1: Sun Apr 1 16:59:00 UTC 2007 kaduk at prolepsis.scs.uiuc.edu:/usr/obj/usr/src/sys/GENERIC i386
>Description:
I've been sitting on this for a while, and I'm nowhere near the end of the chapter. Since I've already accumulated a fair number of changes, I'll batch them up a bit.
Justifications/explanations for changes follow:
experimentation: this seems marginally better grammar, though the meaning is still a bit awkward
ports collection: clear grammar change
sample applications-->\0: unnecessary
information-->content: seems more consistent with modern use
this document-->hardware notes: why use pronouns when we could be non-ambiguous?
adding-->add: tense correction
we-->you: the reader is the interested party
[kernel configuration syntax]: we just gave some information here; NOTES is the definitive source
[non-PnP ISA stuff]: we only care about sound cards, here, so mention ``sound card'' first and then use ``card'' unadorned; at system boot feels awkward here, to me
[axe snd_sb16(4)]: I see no reference to this at this time
as well as the following in-->and these to: less awkward
[sound driver manual page]: be explicit here (I had to think for a while to figure out what was meant)
show up-->are listed: more formal
is chosen-->was chosen: the past tense seems more appropriate to me
properly coupled-->...connected: ``coupled'' isn't quite right; be specific about what hardware topology needs to exist for playback to work
[cat >/dev/dsp]: new idea; new paragraph. Also, use ``another'' because we already gave one way to test the sound card (play a CD)
[remove ``unsupported subdevice XX'']: this is a relic of the MKNOD era (this faq was present in the first revision of this chapter)
set-->enabled: the channels are enabled; the number of them is set
playback channels-->playback: the playback is multiplexed, not the sound card's channels (it is the channels of the programs playing audio which are multiplexed)
to the user-->to a program...:something has to ask for /dev/dsp, and the programs are what do it. Actually, we could probably remove this, since devfs is essentially obligatory these days
[default mixer levels]: general cleanup. Give sample volume of 50 because 75 is the default and setting to 100 can lead to distortion (so ariff@ claims, and I believe)
>How-To-Repeat:
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/multimedia.html
>Fix:
Patch attached with submission follows:
--- chapter.sgml.orig.0 2007-07-06 15:03:22.000000000 -0500
+++ chapter.sgml.orig 2007-07-18 22:13:15.000000000 -0500
@@ -27,12 +27,12 @@
applications allowing you to edit your recorded audio, add sound
effects, and control attached MIDI devices.</para>
- <para>With some willingness to experiment, FreeBSD can support
+ <para>With some experimentation, FreeBSD can support
playback of video files and DVD's. The number of applications
to encode, convert, and playback various video media is more
limited than the number of sound applications. For example as
of this writing, there is no good re-encoding application in the
- FreeBSD Ports Collection, which could be used to convert
+ FreeBSD Ports Collection that can be used to convert
between formats, as there is with <filename
role="package">audio/sox</filename>. However, the software
landscape in this area is changing rapidly.</para>
@@ -52,8 +52,7 @@
</listitem>
<listitem>
- <para>Methods to test that your card is working using
- sample applications.</para>
+ <para>Methods to test whether your card is working.</para>
</listitem>
<listitem>
@@ -78,7 +77,7 @@
</listitem>
<listitem>
- <para>How to rip CD and DVD information into files.</para>
+ <para>How to rip CD and DVD content into files.</para>
</listitem>
<listitem>
@@ -140,7 +139,7 @@
FreeBSD supports a wide variety of both PCI and ISA cards.
Check the supported audio devices list of the <ulink
url="&rel.current.hardware;">Hardware Notes</ulink> to see if
- your card is supported. This document will also mention which
+ your card is supported. The Hardware Notes will also mention which
driver supports your card.</para>
<indexterm>
@@ -190,14 +189,14 @@
<sect3>
<title>Configuring a Custom Kernel with Sound Support</title>
- <para>The first thing to do is adding the generic audio driver
- &man.sound.4; to the kernel, for that you will need to
+ <para>The first thing to do is add the audio framework driver
+ &man.sound.4; to the kernel; for that you will need to
add the following line to the kernel configuration file:</para>
<programlisting>device sound</programlisting>
- <para>Then we have to add the support for our sound card.
- Therefore, we need to know which driver supports the card.
+ <para>Next, you have to add the support for your sound card.
+ Therefore, you need to know which driver supports the card.
Check the supported audio devices list of the <ulink
url="&rel.current.hardware;">Hardware Notes</ulink>, to
determine the correct driver for your sound card. For
@@ -208,24 +207,24 @@
<programlisting>device snd_emu10k1</programlisting>
<para>Be sure to read the manual page of the driver for the
- syntax to use. Information regarding the syntax of sound
- drivers in the kernel configuration can also be found in the
+ syntax to use. The explicit syntax for the kernel configuration
+ of every supported sound driver can also be found in the
<filename>/usr/src/sys/conf/NOTES</filename> file.</para>
- <para>Non-PnP ISA cards may require you to provide the kernel
- with information on the sound card settings (IRQ, I/O port,
- etc). This is done via the
- <filename>/boot/device.hints</filename> file. At system boot,
+ <para>Non-PnP ISA sound cards may require you to provide the kernel
+ with information on the card settings (IRQ, I/O port,
+ etc), as is true of all non-PnP ISA cards. This is done via the
+ <filename>/boot/device.hints</filename> file. During the boot process,
the &man.loader.8; will read this file and pass the settings
to the kernel. For example, an old
Creative &soundblaster; 16 ISA non-PnP card will use the
- &man.snd.sbc.4; driver in conjunction with snd_sb16(4). For this card the following lines have to be added to
+ &man.snd.sbc.4; driver. For this card the following lines must be added to
the kernel configuration file:</para>
<programlisting>device snd_sbc
device snd_sb16</programlisting>
- <para>as well as the following in
+ <para>and these to
<filename>/boot/device.hints</filename>:</para>
<programlisting>hint.sbc.0.at="isa"
@@ -239,12 +238,13 @@
<para>The syntax used in the
<filename>/boot/device.hints</filename> file is covered in the
- sound driver manual page.</para>
+ &man.sound.4; driver manual page and the manual page
+ for the driver in question.</para>
<para>The settings shown above are the defaults. In some
cases, you may need to change the IRQ or the other settings to
- match your card. See the &man.snd.sbc.4; manual page for more
- information.</para>
+ match your card. See the &man.snd.sbc.4; and &man.snd.gusc.4;
+ manual pages for more information about these cards.</para>
</sect3>
</sect2>
@@ -269,14 +269,14 @@
kld snd_ich (1p/2r/0v channels duplex default)</screen>
<para>The output from your system may vary. If no
- <devicename>pcm</devicename> devices show up, go back and review
+ <devicename>pcm</devicename> devices are listed, go back and review
what was done earlier. Go through your kernel
configuration file again and make sure the correct
- device is chosen. Common problems are listed in <xref
+ device driver was chosen. Common problems are listed in <xref
linkend="troubleshooting">.</para>
<para>If all goes well, you should now have a functioning sound
- card. If your CD-ROM or DVD-ROM drive is properly coupled to
+ card. If your CD-ROM or DVD-ROM drive's audio-out pins are properly connected to
your sound card, you can put a CD in the drive and play it
with &man.cdcontrol.1;:</para>
@@ -286,8 +286,10 @@
role="package">audio/workman</filename> can provide a friendlier
interface. You may want to install an application such as
<filename role="package">audio/mpg123</filename> to listen to
- MP3 audio files. A quick way to test the card is sending data
- to the <filename>/dev/dsp</filename>, like this:</para>
+ MP3 audio files.</para>
+
+ <para>Another quick way to test the card is sending data
+ to <filename>/dev/dsp</filename>, like this:</para>
<screen>&prompt.user; <userinput>cat <replaceable>filename</replaceable> > /dev/dsp</userinput></screen>
@@ -317,12 +319,6 @@
</thead>
<tbody>
- <row>
- <entry><errorname>unsupported subdevice XX</errorname></entry>
- <entry><para>One or more of the device nodes was not created
- correctly. Repeat the steps above.</para></entry>
- </row>
-
<row>
<entry><errorname>sb_dspwr(XX) timed out</errorname></entry>
<entry><para>The I/O port is not set correctly.</para></entry>
@@ -372,9 +368,9 @@
sound device with a certain application.</para>
<para>FreeBSD lets you do this through <emphasis>Virtual Sound
- Channels</emphasis>, which can be set with the &man.sysctl.8;
+ Channels</emphasis>, which can be enabled with the &man.sysctl.8;
facility. Virtual channels allow you to multiplex your sound
- card's playback channels by mixing sound in the kernel.</para>
+ card's playback by mixing sound in the kernel.</para>
<para>To set the number of virtual channels, there are two sysctl
knobs which, if you are the <username>root</username> user, can
@@ -406,7 +402,8 @@
where <replaceable>x</replaceable> is 0 to 3 if
<varname>hw.snd.pcm.0.vchans</varname> is set to 4 as in the
above example. On a system using &man.devfs.5;, the above will
- automatically be allocated transparently to the user.</para>
+ automatically be allocated transparently to a program
+ that requests <filename>/dev/dsp0</filename>.</para>
</sect2>
<sect2>
@@ -424,17 +421,17 @@
<para>The default values for the different mixer channels are
hardcoded in the sourcecode of the &man.pcm.4; driver. There are
- a lot of different applications and daemons that allow
- you to set values for the mixer they remember and set
- each time they are started, but this is not a clean
- solution, we want to have default values at the driver
- level. This is accomplished by defining the appropriate
- values in <filename>/boot/device.hints</filename>. E.g.:</para>
+ many different applications and daemons that allow
+ you to set values for the mixer that are remembered between
+ invocations, but this is not a clean solution. It is possible
+ to set default mixer values at the driver level — this
+ is accomplished by defining the appropriate
+ values in <filename>/boot/device.hints</filename>, e.g.:</para>
-<programlisting>hint.pcm.0.vol="100"</programlisting>
+<programlisting>hint.pcm.0.vol="50"</programlisting>
<para>This will set the volume channel to a default value of
- 100, when the &man.pcm.4; module is loaded.</para>
+ 50 when the &man.pcm.4; module is loaded.</para>
</sect2>
</sect1>
>Release-Note:
>Audit-Trail:
>Unformatted:
More information about the freebsd-doc
mailing list