From owner-freebsd-doc Thu Apr 4 6:38:32 2002 Delivered-To: freebsd-doc@freebsd.org Received: from rhadamanth.submonkey.net (pc4-card4-0-cust162.cdf.cable.ntl.com [80.4.14.162]) by hub.freebsd.org (Postfix) with ESMTP id 23C9437B419; Thu, 4 Apr 2002 06:38:21 -0800 (PST) Received: from setantae by rhadamanth.submonkey.net with local (Exim 3.35 #1) id 16t8NX-0002Od-00; Thu, 04 Apr 2002 15:38:19 +0100 Date: Thu, 4 Apr 2002 15:38:19 +0100 From: Ceri To: Giorgos Keramidas Cc: freebsd-doc@FreeBSD.org Subject: Re: RFC: Removing "try and " from the docs Message-ID: <20020404143819.GB8766@submonkey.net> Mail-Followup-To: Ceri , Giorgos Keramidas , freebsd-doc@FreeBSD.org References: <20020404133226.GA8872@hades.hell.gr> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20020404133226.GA8872@hades.hell.gr> User-Agent: Mutt/1.3.28i Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org On Thu, Apr 04, 2002 at 04:32:27PM +0300, Giorgos Keramidas wrote: > I've tried to remove "try and " from the English part of the > documentation. The patch below shows what changes I made. Since this > touches several files, I'd be glad to hear any comments or suggestions > you might have. If nobody objects to this, I'll try to have it > committed in a few days. Excellent work! As usual, I have a few suggestions. here goes : > RCS file: /home/ncvs/doc/en_US.ISO8859-1/articles/filtering-bridges/article.sgml,v > > - If there are any problems, you should try and sort them out now > + If there are any problems, you should try to sort them out now > before proceeding. s/try to// perhaps ? > RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/developers-handbook/tools/chapter.sgml,v > > Although Emacs does have menus, it is well worth learning > the key bindings, as it is much quicker when you are editing > - something to press a couple of keys than to try and find the > - mouse and then click on the right place. And, when you are > + something to press a couple of keys than finding the > + mouse and then clicking on the right place. And, when you are I don't think the grammar really fits now. Either it should be : ...as it is much quicker when you are editing something to press a couple of keys than to find the mouse and then click on the right place. or: ...as pressing a couple of keys when you are editing is much quicker than finding the mouse and then clicking in the right place. I don't know why I prefer those, but the proposed change doesn't sound right somehow. > RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/faq/book.sgml,v > > The document's format. We produce the documentation in a > - number of different output formats to try and make it as > - flexible as possible. The current formats are; > + number of different output formats. Each format has its own > + advantages and disadvantages. Some formats are better suited > + for online reading, while others are beautiful when printed on > + paper. Having the documentation available in any of these > + formats ensures that our readers will be able to read the > + parts they are interested in, either online on their monitor, > + or after printing the documents on paper. The current formats > + are: I'd like to drop the word "online" from "online on their monitor". I do know what you mean, and it makes sense, but it looks bizarre and could be confusing. Also, I'm not convinced that the handbook is "beautiful" :) > RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml,v > retrieving revision 1.10 > diff -u -r1.10 chapter.sgml > --- en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml 26 Mar 2002 22:31:55 -0000 1.10 > +++ en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml 3 Apr 2002 22:22:35 -0000 > @@ -242,7 +242,7 @@ > separate directories prepares for future plans for the Handbook. > Specifically, it will soon be possible to include images in each > chapter. It makes more sense for each image to be stored in a > - directory with the text for the chapter than to try and keep the > + directory with the text for the chapter than keeping the > text for all the chapters, and all the images, in one large > directory. Namespace collisions would be inevitable, and it is > easier to work with several directories with a few files in them Same problem here that I have with the emacs one above. I'd prefer : ...It makes more sense to store each image in a directory with the accompanying chapter text than to keep the text for all the chapters and all the images in one large directory. Actually, I probably wouldn't prefer that exact text, because the end part doesn't go with the beginning properly, but the grammar in the proposed version sounds weird again. > Index: en_US.ISO8859-1/books/handbook/basics/chapter.sgml > =================================================================== > RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/handbook/basics/chapter.sgml,v > retrieving revision 1.59 > diff -u -r1.59 chapter.sgml > --- en_US.ISO8859-1/books/handbook/basics/chapter.sgml 26 Mar 2002 23:37:38 -0000 1.59 > +++ en_US.ISO8859-1/books/handbook/basics/chapter.sgml 3 Apr 2002 22:23:39 -0000 > @@ -890,7 +890,7 @@ > send—some of them have a specific meaning, others are interpreted > by the application, and the application's documentation will tell you > how that application interprets signals. You can only send a signal to > - a process that you own. If you try and send a signal to someone else's > + a process that you own. If you send a signal to someone else's > process it will be ignored. The exception to this is the Slightly bigger problem here. If you try to send a signal to someone else's process your attempt will fail with EPERM, as opposed to being ignored. This is the only one that I'd definitely want to see fixed, the others are just MHO. Ceri -- keep a mild groove on To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message