Bug 114718

Comment 1 Marc Fonvieille 2007-07-19 06:06:18 UTC

Responsible Changed
From-To: freebsd-doc->blackend

I'll work on this one.

Comment 2 dfilter service 2007-07-31 07:23:48 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"

Comment 3 Marc Fonvieille 2007-07-31 07:24:20 UTC

State Changed
From-To: open->closed

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.

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
>

Comment 5 Marc Fonvieille 2007-08-07 13:09:06 UTC

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

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 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 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
-- 
That must be wonderful!  I don't understand it at all.
                                                  -- Moliere

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

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
>

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


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
-- 
That must be wonderful!  I don't understand it at all.
                                                  -- Moliere