From owner-freebsd-doc@FreeBSD.ORG Tue Dec 25 18:03:27 2012 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id 9503EA52 for ; Tue, 25 Dec 2012 18:03:27 +0000 (UTC) (envelope-from bjk@freebsd.org) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:1900:2254:206c::16:87]) by mx1.freebsd.org (Postfix) with ESMTP id 731228FC13; Tue, 25 Dec 2012 18:03:27 +0000 (UTC) Received: from freefall.freebsd.org (localhost [127.0.0.1]) by freefall.freebsd.org (8.14.5/8.14.5) with ESMTP id qBPI3RiV095960; Tue, 25 Dec 2012 18:03:27 GMT (envelope-from bjk@freebsd.org) Received: from localhost (bjk@localhost) by freefall.freebsd.org (8.14.5/8.14.5/Submit) with ESMTP id qBPI3QZg095957; Tue, 25 Dec 2012 18:03:26 GMT (envelope-from bjk@freebsd.org) X-Authentication-Warning: freefall.freebsd.org: bjk owned process doing -bs Date: Tue, 25 Dec 2012 18:03:26 +0000 (UTC) From: Benjamin Kaduk To: Lowell Gilbert Subject: Re: [freebsd-doc] Re: confusing sentence in hardware notes boilerplate In-Reply-To: <44ehie9l2c.fsf_-_@lowell-desk.lan> Message-ID: References: <20121225001355.GC16584@whisperer.chthonixia.net> <44ehie9l2c.fsf_-_@lowell-desk.lan> User-Agent: Alpine 2.00 (BSF 1167 2008-08-23) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; format=flowed; charset=US-ASCII Cc: freebsd-doc@freebsd.org X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 25 Dec 2012 18:03:27 -0000 [reintroducing the patch so as to get the current version of the text for reference] Index: article.xml =================================================================== --- article.xml (revision 244663) +++ article.xml (working copy) @@ -53,7 +53,7 @@ This document contains the hardware compatibility notes for &os; &release.current;. It lists the hardware platforms supported by &os;, as well as the various types of hardware - devices (storage controllers, network interfaces, and so on), + devices supported (storage controllers, network interfaces, and so on), along with known working instances of these devices. On Tue, 25 Dec 2012, Lowell Gilbert wrote: > Joe Altman writes: > >> On Mon, Dec 24, 2012 at 10:08:11PM +0000, Benjamin Kaduk wrote: >>> I was going over the various release notes documents to do some editing, >>> and spent entirely too much time trying to understand a sentence at the >>> top of the hardware notes, which has been there since r172098 by bmah in >>> 2007. I think that adding a word per below helps the readability, but I >>> am no longer an impartial reader (having read the sentence too much). >>> Thoughts? >> >> I try to refrain from using the same word more than once, when they are >> in proximity. To me, adding "supported" as you propose is such. >> Additionally, the phrase "...known working instances..." seems to >> re-state the word "supported". > > I agree. It's not just awkward, it could be confusing, because a reader > might assume that the repetition had semantic content, and read > something into the sentence that wasn't there. Well, I wanted to add semantic content. My response to reading the current (unpatched) text is to say "hardware devices that what?". The intent is clearly that these hardware devices are those supported, but at least to me, reading the sentence is confusing. >> OTOH, it could be written: >> >> This document lists the supported hardware platforms and devices such as >> storage controllers, network interfaces, and so on, for &os; >> &release.current;. > > That's not bad. To my ear, it's even a bit of an improvement on the > original. The original tries harder to make a distinction between hardware platforms (e.g., i386, amd64, arm, etc.) and peripheral devices which may be attached to a particular instance of such a platform. I do not think that merging them together as having near-equal importance in the list is necessarily the best choice. I guess I will ponder more extensive rewordings, then. -Ben