Date: Thu, 4 Apr 2002 15:38:19 +0100 From: Ceri <setantae@submonkey.net> To: Giorgos Keramidas <keramida@FreeBSD.org> Cc: freebsd-doc@FreeBSD.org Subject: Re: RFC: Removing "try and <verb>" from the docs Message-ID: <20020404143819.GB8766@submonkey.net> In-Reply-To: <20020404133226.GA8872@hades.hell.gr> References: <20020404133226.GA8872@hades.hell.gr>
next in thread | previous in thread | raw e-mail | index | archive | help
On Thu, Apr 04, 2002 at 04:32:27PM +0300, Giorgos Keramidas wrote:
> I've tried to remove "try and <verb>" 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
>
> - <para>If there are any problems, you should try and sort them out now
> + <para>If there are any problems, you should try to sort them out now
> before proceeding.</para>
s/try to// perhaps ?
> RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/developers-handbook/tools/chapter.sgml,v
>
> <para>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
> <listitem>
> <para>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;</para>
> + 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:</para>
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20020404143819.GB8766>