From nobody@FreeBSD.org  Thu Jul 19 03:23:06 2007
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52])
	by hub.freebsd.org (Postfix) with ESMTP id 9043F16A401
	for <freebsd-gnats-submit@FreeBSD.org>; Thu, 19 Jul 2007 03:23:06 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (groups.freebsd.org [69.147.83.33])
	by mx1.freebsd.org (Postfix) with ESMTP id 8031613C491
	for <freebsd-gnats-submit@FreeBSD.org>; Thu, 19 Jul 2007 03:23:06 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (localhost [127.0.0.1])
	by www.freebsd.org (8.14.1/8.14.1) with ESMTP id l6J3N6es059479
	for <freebsd-gnats-submit@FreeBSD.org>; Thu, 19 Jul 2007 03:23:06 GMT
	(envelope-from nobody@www.freebsd.org)
Received: (from nobody@localhost)
	by www.freebsd.org (8.14.1/8.14.1/Submit) id l6J3N6xV059478;
	Thu, 19 Jul 2007 03:23:06 GMT
	(envelope-from nobody)
Message-Id: <200707190323.l6J3N6xV059478@www.freebsd.org>
Date: Thu, 19 Jul 2007 03:23:06 GMT
From: Ben Kaduk <minimarmot@gmail.com>
To: freebsd-gnats-submit@FreeBSD.org
Subject: grammar, etc. in handbook/multimedia (part 1)
X-Send-Pr-Version: www-3.0

>Number:         114718
>Category:       docs
>Synopsis:       grammar, etc. in handbook/multimedia (part 1)
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    blackend
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Jul 19 03:30:03 GMT 2007
>Closed-Date:    Tue Jul 31 06:27:23 GMT 2007
>Last-Modified:  Wed Aug  8 08:50:03 GMT 2007
>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@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> &gt; /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 &mdash; 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:
Responsible-Changed-From-To: freebsd-doc->blackend 
Responsible-Changed-By: blackend 
Responsible-Changed-When: Thu Jul 19 05:06:18 UTC 2007 
Responsible-Changed-Why:  
I'll work on this one. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=114718 
State-Changed-From-To: open->closed 
State-Changed-By: blackend 
State-Changed-When: Tue Jul 31 06:24:20 UTC 2007 
State-Changed-Why:  
I committed a slightly different version of your patch: 

I removed the s/which/that cause of 
http://itre.cis.upenn.edu/~myl/languagelog/archives/002189.html 

I kept reference to snd_sb16 with: 
<literal>snd_sb16</literal> instead of snd_sb16(4) 

&man.snd.gusc.4; is not necessary where you added it. 


http://www.freebsd.org/cgi/query-pr.cgi?pr=114718 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/114718: commit references a PR
Date: Tue, 31 Jul 2007 06:23:48 +0000 (UTC)

 blackend    2007-07-31 06:23:43 UTC
 
   FreeBSD doc repository
 
   Modified files:
     en_US.ISO8859-1/books/handbook/multimedia chapter.sgml 
   Log:
   - Various rewordings, style and grammar fixes.
   - Some common sense changes: use of 50 instead of 100 for the volume
     channel example.
   
   PR:             docs/114718
   Submitted by:   Ben Kaduk <minimarmot@gmail.com>
   
   Revision  Changes    Path
   1.127     +38 -41    doc/en_US.ISO8859-1/books/handbook/multimedia/chapter.sgml
 _______________________________________________
 cvs-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/cvs-all
 To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"
 

From: "Ben Kaduk" <minimarmot@gmail.com>
To: bug-followup@freebsd.org
Cc:  
Subject: Re: docs/114718: grammar, etc. in handbook/multimedia (part 1)
Date: Fri, 3 Aug 2007 22:57:20 -0500

 Re-send because I think I hit blackend@'s spam filter
 
 ---------- Forwarded message ----------
 From: Ben Kaduk <minimarmot@gmail.com>
 Date: Aug 1, 2007 12:08 AM
 Subject: Re: docs/114718: grammar, etc. in handbook/multimedia (part 1)
 To: "blackend@freebsd.org" <blackend@freebsd.org>
 
 
 Hi Marc,
 
 On 7/31/07, blackend@freebsd.org <blackend@freebsd.org> wrote:
 > Synopsis: grammar, etc. in handbook/multimedia (part 1)
 >
 > State-Changed-From-To: open->closed
 > State-Changed-By: blackend
 > State-Changed-When: Tue Jul 31 06:24:20 UTC 2007
 > State-Changed-Why:
 > I committed a slightly different version of your patch:
 >
 > I removed the s/which/that cause of
 > http://itre.cis.upenn.edu/~myl/languagelog/archives/002189.html
 >
 
 Well, it's not exactly s/which/that/; it's s/, which/ that/.  I was
 experiencing something similar to this:
 http://itre.cis.upenn.edu/~myl/languagelog/archives/002156.html
 (using the same source you cite above).
 
 A bit of browsing the same blog finds this page:
 http://itre.cis.upenn.edu/~myl/languagelog/archives/002146.html
 (the page you linked didn't mention exactly what the supposed rule is...)
 I had to check on wikipedia what ``restrictive'' means in this context
 (which shows how much I know formally about the topic), but the
 that/which seems to be restrictive here (on the set of applications
 (in the ports collection)).
 If I am reading correctly, there should then not be a comma in this situation.
 I changed which to that because I had to make a change anyways (the
 comma), and ``that'' reads a bit more easily to me, but I really don't
 care about the that vs. which, it's the comma about which I'm
 concerned.
 
 > I kept reference to snd_sb16 with:
 > <literal>snd_sb16</literal> instead of snd_sb16(4)
 >
 
 That makes sense -- it is needed, but it has no man page.
 
 > &man.snd.gusc.4; is not necessary where you added it.
 >
 
 I thought I checked before adding that change. . . it seems to be here:
 http://www.freebsd.org/cgi/cvsweb.cgi/doc/share/sgml/man-refs.ent?rev=1.434
 
 Those two cards were the only ones I found that used hints.  I have
 used sbc before, but I have no idea if gusc is still in common use.
 I won't argure too hard for its inclusion.
 
 -Ben Kaduk
 
 >
 > http://www.freebsd.org/cgi/query-pr.cgi?pr=114718
 >

From: Marc Fonvieille <blackend@freebsd.org>
To: Ben Kaduk <minimarmot@gmail.com>
Cc: bug-followup@freebsd.org, murray@freebsd.org, ceri@freebsd.org
Subject: Re: docs/114718: grammar, etc. in handbook/multimedia (part 1)
Date: Tue, 7 Aug 2007 14:09:06 +0200

 On Sat, Aug 04, 2007 at 04:30:09AM +0000, Ben Kaduk wrote:
 > The following reply was made to PR docs/114718; it has been noted by GNATS.
 > 
 > From: "Ben Kaduk" <minimarmot@gmail.com>
 > To: bug-followup@freebsd.org
 > Cc:  
 > Subject: Re: docs/114718: grammar, etc. in handbook/multimedia (part 1)
 > Date: Fri, 3 Aug 2007 22:57:20 -0500
 > 
 >  Re-send because I think I hit blackend@'s spam filter
 >  
 >  ---------- Forwarded message ----------
 >  From: Ben Kaduk <minimarmot@gmail.com>
 >  Date: Aug 1, 2007 12:08 AM
 >  Subject: Re: docs/114718: grammar, etc. in handbook/multimedia (part 1)
 >  To: "blackend@freebsd.org" <blackend@freebsd.org>
 >  
 >  
 >  Hi Marc,
 >  
 >  On 7/31/07, blackend@freebsd.org <blackend@freebsd.org> wrote:
 >  > Synopsis: grammar, etc. in handbook/multimedia (part 1)
 >  >
 >  > State-Changed-From-To: open->closed
 >  > State-Changed-By: blackend
 >  > State-Changed-When: Tue Jul 31 06:24:20 UTC 2007
 >  > State-Changed-Why:
 >  > I committed a slightly different version of your patch:
 >  >
 >  > I removed the s/which/that cause of
 >  > http://itre.cis.upenn.edu/~myl/languagelog/archives/002189.html
 >  >
 >  
 >  Well, it's not exactly s/which/that/; it's s/, which/ that/.  I was
 >  experiencing something similar to this:
 >  http://itre.cis.upenn.edu/~myl/languagelog/archives/002156.html
 >  (using the same source you cite above).
 >  
 >  A bit of browsing the same blog finds this page:
 >  http://itre.cis.upenn.edu/~myl/languagelog/archives/002146.html
 >  (the page you linked didn't mention exactly what the supposed rule is...)
 >  I had to check on wikipedia what ``restrictive'' means in this context
 >  (which shows how much I know formally about the topic), but the
 >  that/which seems to be restrictive here (on the set of applications
 >  (in the ports collection)).
 >  If I am reading correctly, there should then not be a comma in this situation.
 >  I changed which to that because I had to make a change anyways (the
 >  comma), and ``that'' reads a bit more easily to me, but I really don't
 >  care about the that vs. which, it's the comma about which I'm
 >  concerned.
 
 Hello Ben,
 
 English is not my native tongue, so these grammar and style rules are
 sometimes a bit difficult to understand for me, well in fact I should
 say that it's difficult for me to say if it's correct or not.  If I did
 not perform the change it's cause of a private mail of one committer
 mentioning the link I pasted in my previous message.
 I think I need the help of some grammar experts hence the Cc to murray@
 and ceri@.
 
 >  
 >  > I kept reference to snd_sb16 with:
 >  > <literal>snd_sb16</literal> instead of snd_sb16(4)
 >  >
 >  
 >  That makes sense -- it is needed, but it has no man page.
 >  
 >  > &man.snd.gusc.4; is not necessary where you added it.
 >  >
 >  
 >  I thought I checked before adding that change. . . it seems to be here:
 >  http://www.freebsd.org/cgi/cvsweb.cgi/doc/share/sgml/man-refs.ent?rev=1.434
 >  
 >  Those two cards were the only ones I found that used hints.  I have
 >  used sbc before, but I have no idea if gusc is still in common use.
 >  I won't argure too hard for its inclusion.
 >  
 
 In fact, that part was just an example of the use of hints, the example
 was about a sb16 (ISA) so it has nothing to do with the gravis
 soundcard.
 
 -- 
 Marc

From: Ceri Davies <ceri@submonkey.net>
To: Marc Fonvieille <blackend@freebsd.org>
Cc: Ben Kaduk <minimarmot@gmail.com>, bug-followup@freebsd.org,
	murray@freebsd.org
Subject: Re: docs/114718: grammar, etc. in handbook/multimedia (part 1)
Date: Tue, 7 Aug 2007 13:41:42 +0100

 --47eKBCiAZYFK5l32
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline
 Content-Transfer-Encoding: quoted-printable
 
 On Tue, Aug 07, 2007 at 02:09:06PM +0200, Marc Fonvieille wrote:
 > On Sat, Aug 04, 2007 at 04:30:09AM +0000, Ben Kaduk wrote:
 > > The following reply was made to PR docs/114718; it has been noted by GN=
 ATS.
 > >=20
 > > From: "Ben Kaduk" <minimarmot@gmail.com>
 > > To: bug-followup@freebsd.org
 > > Cc: =20
 > > Subject: Re: docs/114718: grammar, etc. in handbook/multimedia (part 1)
 > > Date: Fri, 3 Aug 2007 22:57:20 -0500
 > >=20
 > >  Re-send because I think I hit blackend@'s spam filter
 > > =20
 > >  ---------- Forwarded message ----------
 > >  From: Ben Kaduk <minimarmot@gmail.com>
 > >  Date: Aug 1, 2007 12:08 AM
 > >  Subject: Re: docs/114718: grammar, etc. in handbook/multimedia (part 1)
 > >  To: "blackend@freebsd.org" <blackend@freebsd.org>
 > > =20
 > > =20
 > >  Hi Marc,
 > > =20
 > >  On 7/31/07, blackend@freebsd.org <blackend@freebsd.org> wrote:
 > >  > Synopsis: grammar, etc. in handbook/multimedia (part 1)
 > >  >
 > >  > State-Changed-From-To: open->closed
 > >  > State-Changed-By: blackend
 > >  > State-Changed-When: Tue Jul 31 06:24:20 UTC 2007
 > >  > State-Changed-Why:
 > >  > I committed a slightly different version of your patch:
 > >  >
 > >  > I removed the s/which/that cause of
 > >  > http://itre.cis.upenn.edu/~myl/languagelog/archives/002189.html
 > >  >
 > > =20
 > >  Well, it's not exactly s/which/that/; it's s/, which/ that/.  I was
 > >  experiencing something similar to this:
 > >  http://itre.cis.upenn.edu/~myl/languagelog/archives/002156.html
 > >  (using the same source you cite above).
 > > =20
 > >  A bit of browsing the same blog finds this page:
 > >  http://itre.cis.upenn.edu/~myl/languagelog/archives/002146.html
 > >  (the page you linked didn't mention exactly what the supposed rule is.=
 =2E.)
 > >  I had to check on wikipedia what ``restrictive'' means in this context
 > >  (which shows how much I know formally about the topic), but the
 > >  that/which seems to be restrictive here (on the set of applications
 > >  (in the ports collection)).
 > >  If I am reading correctly, there should then not be a comma in this si=
 tuation.
 > >  I changed which to that because I had to make a change anyways (the
 > >  comma), and ``that'' reads a bit more easily to me, but I really don't
 > >  care about the that vs. which, it's the comma about which I'm
 > >  concerned.
 >=20
 > Hello Ben,
 >=20
 > English is not my native tongue, so these grammar and style rules are
 > sometimes a bit difficult to understand for me, well in fact I should
 > say that it's difficult for me to say if it's correct or not.  If I did
 > not perform the change it's cause of a private mail of one committer
 > mentioning the link I pasted in my previous message.
 > I think I need the help of some grammar experts hence the Cc to murray@
 > and ceri@.
 
 I can't even begin to follow the URLs quoted at the moment, but I can
 say that the change in Ben's patch was correct, or at least clearer :)
 
 The original text was:
 
   For example as of this writing, there is no good re-encoding
    application in the FreeBSD Ports Collection, which could be used
    to convert between formats, as there is with audio/sox.
 
 Ben changed this to:
 
   For example as of this writing, there is no good re-encoding
    application in the FreeBSD Ports Collection that could be used
    to convert between formats, as there is with audio/sox.
 
 If I have those the wrong way around, then Ben's patch was wrong :)
 
 No time to explain why at the moment, but the first forms looks like the
 "which..." bit is parenthetical, which it isn't.
 
 Ceri
 --=20
 That must be wonderful!  I don't understand it at all.
                                                   -- Moliere
 
 --47eKBCiAZYFK5l32
 Content-Type: application/pgp-signature
 Content-Disposition: inline
 
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1.4.6 (FreeBSD)
 
 iD8DBQFGuGiGocfcwTS3JF8RAs3jAKCMFlXrwmCN4J2VSnqNX9ZfdiaGLQCfVAj+
 wTCwj435nx42f8r1j8K142E=
 =Hwnh
 -----END PGP SIGNATURE-----
 
 --47eKBCiAZYFK5l32--

From: "Ben Kaduk" <minimarmot@gmail.com>
To: "Ceri Davies" <ceri@submonkey.net>
Cc: "Marc Fonvieille" <blackend@freebsd.org>, bug-followup@freebsd.org, 
	murray@freebsd.org
Subject: Re: docs/114718: grammar, etc. in handbook/multimedia (part 1)
Date: Tue, 7 Aug 2007 18:51:34 -0500

 On 8/7/07, Ceri Davies <ceri@submonkey.net> wrote:
 > On Tue, Aug 07, 2007 at 02:09:06PM +0200, Marc Fonvieille wrote:
 > > On Sat, Aug 04, 2007 at 04:30:09AM +0000, Ben Kaduk wrote:
 [snip build-up; leave links that are referred to below]
 > > >  Marc Fonvielle wrote:
 > > >  > I removed the s/which/that cause of
 > > >  > http://itre.cis.upenn.edu/~myl/languagelog/archives/002189.html
 > > >  >
 > > >
 > > >  Well, it's not exactly s/which/that/; it's s/, which/ that/.  I was
 > > >  experiencing something similar to this:
 > > >  http://itre.cis.upenn.edu/~myl/languagelog/archives/002156.html
 > > >  (using the same source you cite above).
 > > >
 > > >  A bit of browsing the same blog finds this page:
 > > >  http://itre.cis.upenn.edu/~myl/languagelog/archives/002146.html
 > > >  (the page you linked didn't mention exactly what the supposed rule is...)
 > > >  I had to check on wikipedia what ``restrictive'' means in this context
 > > >  (which shows how much I know formally about the topic), but the
 > > >  that/which seems to be restrictive here (on the set of applications
 > > >  (in the ports collection)).
 > > >  If I am reading correctly, there should then not be a comma in this situation.
 > > >  I changed which to that because I had to make a change anyways (the
 > > >  comma), and ``that'' reads a bit more easily to me, but I really don't
 > > >  care about the that vs. which, it's the comma about which I'm
 > > >  concerned.
 > >
 > > Hello Ben,
 > >
 > > English is not my native tongue, so these grammar and style rules are
 > > sometimes a bit difficult to understand for me, well in fact I should
 > > say that it's difficult for me to say if it's correct or not.  If I did
 > > not perform the change it's cause of a private mail of one committer
 > > mentioning the link I pasted in my previous message.
 > > I think I need the help of some grammar experts hence the Cc to murray@
 > > and ceri@.
 >
 > I can't even begin to follow the URLs quoted at the moment, but I can
 > say that the change in Ben's patch was correct, or at least clearer :)
 
 Hi Ceri,
 
 It took me a long time to figure out whether those URLs were
 supporting or contradicting my argument.  One of the nice things about
 being forced to defend my editorial changes is that I have to learn
 the reasoning behind my intuition.  I am a native English speaker, but
 ``it just feels right'' is not justification for anything (other than
 choosing a carpet, perhaps).
 
 I hope no one feels that I'm wasting their time with threads like
 this.  I know that there are many places in our documentation that
 need massive changes, and it sometimes doesn't feel right to make
 others put effort into minor grammatical changes.  However, I have set
 myself the task of doing a grammar overhaul of the handbook, and it
 would feel worse to abandon it halfway :).
 
 -Ben Kaduk
 
 >
 > The original text was:
 >
 >   For example as of this writing, there is no good re-encoding
 >    application in the FreeBSD Ports Collection, which could be used
 >    to convert between formats, as there is with audio/sox.
 >
 > Ben changed this to:
 >
 >   For example as of this writing, there is no good re-encoding
 >    application in the FreeBSD Ports Collection that could be used
 >    to convert between formats, as there is with audio/sox.
 >
 > If I have those the wrong way around, then Ben's patch was wrong :)
 >
 > No time to explain why at the moment, but the first forms looks like the
 > "which..." bit is parenthetical, which it isn't.
 >
 > Ceri
 > --
 > That must be wonderful!  I don't understand it at all.
 >                                                   -- Moliere
 >
 >

From: "Ben Kaduk" <minimarmot@gmail.com>
To: "Marc Fonvieille" <blackend@freebsd.org>
Cc: bug-followup@freebsd.org
Subject: Re: docs/114718: grammar, etc. in handbook/multimedia (part 1)
Date: Tue, 7 Aug 2007 19:04:23 -0500

 On 8/7/07, Marc Fonvieille <blackend@freebsd.org> wrote:
 > On Sat, Aug 04, 2007 at 04:30:09AM +0000, Ben Kaduk wrote:
 > > The following reply was made to PR docs/114718; it has been noted by GNATS.
 > >
 > > From: "Ben Kaduk" <minimarmot@gmail.com>
 > > To: bug-followup@freebsd.org
 > > Cc:
 > > Subject: Re: docs/114718: grammar, etc. in handbook/multimedia (part 1)
 > > Date: Fri, 3 Aug 2007 22:57:20 -0500
 > >
 > >  Re-send because I think I hit blackend@'s spam filter
 > >
 > >  ---------- Forwarded message ----------
 > >  From: Ben Kaduk <minimarmot@gmail.com>
 > >  Date: Aug 1, 2007 12:08 AM
 > >  Subject: Re: docs/114718: grammar, etc. in handbook/multimedia (part 1)
 > >  To: "blackend@freebsd.org" <blackend@freebsd.org>
 > >
 > >
 > >  Hi Marc,
 > >
 > >  On 7/31/07, blackend@freebsd.org <blackend@freebsd.org> wrote:
 > >  > Synopsis: grammar, etc. in handbook/multimedia (part 1)
 > >  >
 > >  > State-Changed-From-To: open->closed
 > >  > State-Changed-By: blackend
 > >  > State-Changed-When: Tue Jul 31 06:24:20 UTC 2007
 > >  > State-Changed-Why:
 > >  > I committed a slightly different version of your patch:
 > >  >
 > >  > I removed the s/which/that cause of
 > >  > http://itre.cis.upenn.edu/~myl/languagelog/archives/002189.html
 > >  >
 > >
 > >  Well, it's not exactly s/which/that/; it's s/, which/ that/.  I was
 > >  experiencing something similar to this:
 > >  http://itre.cis.upenn.edu/~myl/languagelog/archives/002156.html
 > >  (using the same source you cite above).
 > >
 > >  A bit of browsing the same blog finds this page:
 > >  http://itre.cis.upenn.edu/~myl/languagelog/archives/002146.html
 > >  (the page you linked didn't mention exactly what the supposed rule is...)
 > >  I had to check on wikipedia what ``restrictive'' means in this context
 > >  (which shows how much I know formally about the topic), but the
 > >  that/which seems to be restrictive here (on the set of applications
 > >  (in the ports collection)).
 > >  If I am reading correctly, there should then not be a comma in this situation.
 > >  I changed which to that because I had to make a change anyways (the
 > >  comma), and ``that'' reads a bit more easily to me, but I really don't
 > >  care about the that vs. which, it's the comma about which I'm
 > >  concerned.
 >
 > Hello Ben,
 
 Hi Marc,
 
 >
 > English is not my native tongue, so these grammar and style rules are
 > sometimes a bit difficult to understand for me, well in fact I should
 
 J'en compris.  Je peu parler (un peu) le francais, mais sa grammaire
 est tres difficile pour moi.  I am very impressed that you are able to
 do as much with the FreeBSD english documentation as you do.
 
 > say that it's difficult for me to say if it's correct or not.  If I did
 > not perform the change it's cause of a private mail of one committer
 > mentioning the link I pasted in my previous message.
 
 Caution is usually a good thing.  I do agree with the sentiment that
 we shouldn't blindly do s/which/that/; they can both be correct.
 Here, however, as Ceri mentions (later in the thread), the comma makes
 quite a difference.
 
 > I think I need the help of some grammar experts hence the Cc to murray@
 > and ceri@.
 
 I will echo the sentiment expressed in another message: thanks for
 bringing in the help, but I hope no one feels that their time is being
 wasted.
 
 >
 > >
 > >  > I kept reference to snd_sb16 with:
 > >  > <literal>snd_sb16</literal> instead of snd_sb16(4)
 > >  >
 > >
 > >  That makes sense -- it is needed, but it has no man page.
 > >
 > >  > &man.snd.gusc.4; is not necessary where you added it.
 > >  >
 > >
 > >  I thought I checked before adding that change. . . it seems to be here:
 > >  http://www.freebsd.org/cgi/cvsweb.cgi/doc/share/sgml/man-refs.ent?rev=1.434
 > >
 > >  Those two cards were the only ones I found that used hints.  I have
 > >  used sbc before, but I have no idea if gusc is still in common use.
 > >  I won't argure too hard for its inclusion.
 > >
 >
 > In fact, that part was just an example of the use of hints, the example
 > was about a sb16 (ISA) so it has nothing to do with the gravis
 > soundcard.
 
 Ah, I see how the final paragraph of the <sect3> can be interpreted as
 still dealing with the sbc example (I originally read it as a
 transition relating the example to the general case).  I am not sure
 how to best treat this, since as far as I can tell, there are only two
 soundcard drivers in the tree that use hints.  To mention only one of
 them explicitly seems a bit unfair (though sbc does seem to be much
 more common, and both are probably dying with the ISA card in
 general).  I'm tempted to just kill the entire paragraph and merge
 changing IRQ (and other settings) into the above paragraph which
 points the reader to the man pages in question as well (for the hints
 syntax).
 
 -Ben Kaduk
 
 > --
 > Marc
 >

From: Ceri Davies <ceri@submonkey.net>
To: Ben Kaduk <minimarmot@gmail.com>
Cc: Marc Fonvieille <blackend@freebsd.org>, bug-followup@freebsd.org,
	murray@freebsd.org
Subject: Re: docs/114718: grammar, etc. in handbook/multimedia (part 1)
Date: Wed, 8 Aug 2007 09:43:19 +0100

 --cz6wLo+OExbGG7q/
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline
 Content-Transfer-Encoding: quoted-printable
 
 On Tue, Aug 07, 2007 at 06:51:34PM -0500, Ben Kaduk wrote:
 > On 8/7/07, Ceri Davies <ceri@submonkey.net> wrote:
 > > On Tue, Aug 07, 2007 at 02:09:06PM +0200, Marc Fonvieille wrote:
 > > > On Sat, Aug 04, 2007 at 04:30:09AM +0000, Ben Kaduk wrote:
 > [snip build-up; leave links that are referred to below]
 > > > >  Marc Fonvielle wrote:
 > > > >  > I removed the s/which/that cause of
 > > > >  > http://itre.cis.upenn.edu/~myl/languagelog/archives/002189.html
 > > > >  >
 > > > >
 > > > >  Well, it's not exactly s/which/that/; it's s/, which/ that/.  I was
 > > > >  experiencing something similar to this:
 > > > >  http://itre.cis.upenn.edu/~myl/languagelog/archives/002156.html
 > > > >  (using the same source you cite above).
 > > > >
 > > > >  A bit of browsing the same blog finds this page:
 > > > >  http://itre.cis.upenn.edu/~myl/languagelog/archives/002146.html
 > > > >  (the page you linked didn't mention exactly what the supposed rule=
  is...)
 > > > >  I had to check on wikipedia what ``restrictive'' means in this con=
 text
 > > > >  (which shows how much I know formally about the topic), but the
 > > > >  that/which seems to be restrictive here (on the set of applications
 > > > >  (in the ports collection)).
 > > > >  If I am reading correctly, there should then not be a comma in thi=
 s situation.
 > > > >  I changed which to that because I had to make a change anyways (the
 > > > >  comma), and ``that'' reads a bit more easily to me, but I really d=
 on't
 > > > >  care about the that vs. which, it's the comma about which I'm
 > > > >  concerned.
 > > >
 > > > Hello Ben,
 > > >
 > > > English is not my native tongue, so these grammar and style rules are
 > > > sometimes a bit difficult to understand for me, well in fact I should
 > > > say that it's difficult for me to say if it's correct or not.  If I d=
 id
 > > > not perform the change it's cause of a private mail of one committer
 > > > mentioning the link I pasted in my previous message.
 > > > I think I need the help of some grammar experts hence the Cc to murra=
 y@
 > > > and ceri@.
 > >
 > > I can't even begin to follow the URLs quoted at the moment, but I can
 > > say that the change in Ben's patch was correct, or at least clearer :)
 >=20
 > Hi Ceri,
 >=20
 > It took me a long time to figure out whether those URLs were
 > supporting or contradicting my argument.  One of the nice things about
 > being forced to defend my editorial changes is that I have to learn
 > the reasoning behind my intuition.  I am a native English speaker, but
 > ``it just feels right'' is not justification for anything (other than
 > choosing a carpet, perhaps).
 >=20
 > I hope no one feels that I'm wasting their time with threads like
 > this.  I know that there are many places in our documentation that
 > need massive changes, and it sometimes doesn't feel right to make
 > others put effort into minor grammatical changes.  However, I have set
 > myself the task of doing a grammar overhaul of the handbook, and it
 > would feel worse to abandon it halfway :).
 
 I'm glad you're doing it Ben, but I'm afraid that I do feel that you are
 wasting my time a little if you want me to discuss something that is
 clearly correct to a native speaker.  It is August, I work at a
 university, I just don't have the time, sorry.
 
 Ceri
 --=20
 That must be wonderful!  I don't understand it at all.
                                                   -- Moliere
 
 --cz6wLo+OExbGG7q/
 Content-Type: application/pgp-signature
 Content-Disposition: inline
 
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1.4.6 (FreeBSD)
 
 iD8DBQFGuYInocfcwTS3JF8RAieMAJ982FSgvSin4FRFUGQ4dgJZrjc2owCeKUqS
 ZF+ZWitaOCKAhU78pnISqzs=
 =8Us3
 -----END PGP SIGNATURE-----
 
 --cz6wLo+OExbGG7q/--
>Unformatted:
