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) Fix: Patch attached with submission follows: How-To-Repeat: http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/multimedia.html
Responsible Changed From-To: freebsd-doc->blackend I'll work on this one.
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"
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 >
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