From owner-freebsd-ports@freebsd.org Fri Sep 16 15:52:44 2016 Return-Path: Delivered-To: freebsd-ports@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 8819BBDDE9F for ; Fri, 16 Sep 2016 15:52:44 +0000 (UTC) (envelope-from wblock@wonkity.com) Received: from mailman.ysv.freebsd.org (mailman.ysv.freebsd.org [IPv6:2001:1900:2254:206a::50:5]) by mx1.freebsd.org (Postfix) with ESMTP id 73EF098C for ; Fri, 16 Sep 2016 15:52:44 +0000 (UTC) (envelope-from wblock@wonkity.com) Received: by mailman.ysv.freebsd.org (Postfix) id 731CABDDE9E; Fri, 16 Sep 2016 15:52:44 +0000 (UTC) Delivered-To: ports@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 72C2BBDDE9D for ; Fri, 16 Sep 2016 15:52:44 +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 4138498A for ; Fri, 16 Sep 2016 15:52:44 +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 u8GFqhmx046942 (version=TLSv1.2 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO) for ; Fri, 16 Sep 2016 09:52:43 -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 u8GFqhF7046939 for ; Fri, 16 Sep 2016 09:52:43 -0600 (MDT) (envelope-from wblock@wonkity.com) Date: Fri, 16 Sep 2016 09:52:42 -0600 (MDT) From: Warren Block To: ports@FreeBSD.org Subject: Checking port option descriptions Message-ID: User-Agent: Alpine 2.20 (BSF 67 2015-01-07) MIME-Version: 1.0 Content-Type: text/plain; format=flowed; charset=US-ASCII X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3 (wonkity.com [127.0.0.1]); Fri, 16 Sep 2016 09:52:43 -0600 (MDT) X-BeenThere: freebsd-ports@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Porting software to FreeBSD List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 16 Sep 2016 15:52:44 -0000 Ports options ask the user to make a decision on whether to enable that option. Option descriptions are critical for this, giving the user information to help them make that decision. Unfortunately, what is clear to the porter is often not clear to a user. The Porter's Handbook says "Do not just repeat the name", but this still happens, either exactly, or with a description that adds no information. For example: XYZ Enable XYZ The description here adds no information. The name of the option itself tells the reader that this is for enabling or disabling a feature. The option asks them to make a decision, whether to enable that option or not, or even just to leave it at the default, but does not give them any help in making that decision. Let's improve that: XYZ Include protocols for use with XYZ servers This gives the reader some additional details. Because so many of the option descriptions have predictable no-added-information styles, it is possible to write a program that detects these. In the process of doing that, I found some actual bugs in descriptions that were not caught by other parts of the ports build or portlint. The program is called optcheck and can be found here: http://www.wonkity.com/~wblock/tmp/optcheck/ The readme.txt explains a little more, and optcheck-output.txt is a full run against the ports tree from a couple of weeks ago. The tests are just some that I came up with quickly, and can certainly be improved. More can be added, and they can make better suggestions. Ultimately, the hope is that this functionality will be added to portlint or somewhere else that would help prevent these types of pointless descriptions. For usage, run optcheck -h For a run against the full ports tree, use just optcheck To run against a category or single port directory, use -d: optcheck -d /usr/ports/devel optcheck -d /usr/ports/print/ghostscript9-base