From owner-freebsd-doc@freebsd.org Thu Apr 28 22:38:02 2016 Return-Path: Delivered-To: freebsd-doc@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 50472B1D246 for ; Thu, 28 Apr 2016 22:38:02 +0000 (UTC) (envelope-from wblock@wonkity.com) Received: from wonkity.com (wonkity.com [67.158.26.137]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "wonkity.com", Issuer "wonkity.com" (not verified)) by mx1.freebsd.org (Postfix) with ESMTPS id 080791181; Thu, 28 Apr 2016 22:38:01 +0000 (UTC) (envelope-from wblock@wonkity.com) Received: from wonkity.com (localhost [127.0.0.1]) by wonkity.com (8.15.2/8.15.2) with ESMTPS id u3SMc0Jf015672 (version=TLSv1.2 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO); Thu, 28 Apr 2016 16:38:00 -0600 (MDT) (envelope-from wblock@wonkity.com) Received: from localhost (wblock@localhost) by wonkity.com (8.15.2/8.15.2/Submit) with ESMTP id u3SMc0sU015669; Thu, 28 Apr 2016 16:38:00 -0600 (MDT) (envelope-from wblock@wonkity.com) Date: Thu, 28 Apr 2016 16:38:00 -0600 (MDT) From: Warren Block To: Pedro Giffuni cc: FreeBSD-doc@FreeBSD.org Subject: Re: Where did we lurn to spel? In-Reply-To: <8bfec353-748c-68e2-ddad-fd9a79790b97@FreeBSD.org> Message-ID: References: <5ac139d2-a9ed-e7bf-081b-2e841f4be22a@FreeBSD.org> <8bfec353-748c-68e2-ddad-fd9a79790b97@FreeBSD.org> User-Agent: Alpine 2.20 (BSF 67 2015-01-07) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII; format=flowed X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3 (wonkity.com [127.0.0.1]); Thu, 28 Apr 2016 16:38:00 -0600 (MDT) X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 28 Apr 2016 22:38:02 -0000 On Thu, 28 Apr 2016, Pedro Giffuni wrote: > On 04/28/16 16:36, Warren Block wrote: >> On Thu, 28 Apr 2016, Warren Block wrote: >> >>> On Thu, 28 Apr 2016, Pedro Giffuni wrote: >>> >>>> Hello; >>>> >>>> I just updated locally the textproc/codespell to the latest version >>>> (bugzilla 209128 for the curious), and it finds a *crazy* amount of >>>> issues in code comments. >>>> >>>> I can't handle it on my own, indeed I got tired just be checking >>>> sys/arm ! Anyways, here is what I went "thru": >>>> >>>> https://people.freebsd.org/~pfg/patches/codespell/ >>> >>> textproc/igor finds many mistakes, and works on text files, man pages, >>> DocBook, and HTML. Use of either of these tools is optional, though. >>> >>> Note: in sys/arm/at91/if_atereg.h, it missed "deines"->"defines". >> > > Yes, I haven't really reviewed them beyond the initial replacement. > The changes kept growing and growing and I had to stop. > >> Oh, and many of these are contractions, which should be avoided anyway. > > Well the main questions are ... > > 1) Should someone brave just go ahead and commit massively > such cleanups? It is tempting. > 2) Is there a clever review process to go through these? > Phabricator with documentation team, or assume common > sense? In comments, obvious errors don't need any review. I saw one change in there that changed "safe" to "safely", but the original might have been meant as "-safe", like "multiuser-safe". Those types of changes should be reviewed, and also changes that are not to comments, like the output in the last batch. Maybe the original printf output was meant to line up. > 3) There are many common issues: is "thru" something we should > accept in comments. How about dont vs don't ? The old "be generous in what you accept and strict in what you produce" saying can apply. The code is what we produce, and comments should be as good as we can make them. "Thru" is difficult to justify. "Dont" and "cant" could be from trying to avoid an apostrophe. Just spelling out the words instead of using the contraction solves the problem. We have found in other documentation that bad sections are often copied and pasted as templates. Fixing them avoids later, bigger fixes.