From owner-freebsd-ports@freebsd.org Mon Sep 19 07:48:29 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 227A3BE07D9 for ; Mon, 19 Sep 2016 07:48:29 +0000 (UTC) (envelope-from 000.fbsd@quip.cz) Received: from mailman.ysv.freebsd.org (unknown [127.0.1.3]) by mx1.freebsd.org (Postfix) with ESMTP id 0EC08FA0 for ; Mon, 19 Sep 2016 07:48:29 +0000 (UTC) (envelope-from 000.fbsd@quip.cz) Received: by mailman.ysv.freebsd.org (Postfix) id 0E22DBE07D8; Mon, 19 Sep 2016 07:48:29 +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 0DD1FBE07D7 for ; Mon, 19 Sep 2016 07:48:29 +0000 (UTC) (envelope-from 000.fbsd@quip.cz) Received: from elsa.codelab.cz (elsa.codelab.cz [94.124.105.4]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id C72F8F9F for ; Mon, 19 Sep 2016 07:48:27 +0000 (UTC) (envelope-from 000.fbsd@quip.cz) Received: from elsa.codelab.cz (localhost [127.0.0.1]) by elsa.codelab.cz (Postfix) with ESMTP id 1832A28526; Mon, 19 Sep 2016 09:48:19 +0200 (CEST) Received: from illbsd.quip.test (ip-86-49-16-209.net.upcbroadband.cz [86.49.16.209]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by elsa.codelab.cz (Postfix) with ESMTPSA id 18A8628429; Mon, 19 Sep 2016 09:48:17 +0200 (CEST) Subject: Re: Checking port option descriptions To: Warren Block , ports@FreeBSD.org References: From: Miroslav Lachman <000.fbsd@quip.cz> Message-ID: <57DF9841.7000500@quip.cz> Date: Mon, 19 Sep 2016 09:48:17 +0200 User-Agent: Mozilla/5.0 (X11; FreeBSD amd64; rv:42.0) Gecko/20100101 Firefox/42.0 SeaMonkey/2.39 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit 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: Mon, 19 Sep 2016 07:48:29 -0000 Warren Block wrote on 09/16/2016 17:52: > 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. There are even more confusion. Some options are used by many ports but their real meaning / impact on each port is different. The next problem is options doing nothing to "this" port but just pull some other port as dependency because maintainer thinks it is useful for the end users to have installed it too - this should be avoided (IMHO). I don't have port names in hand but I know I saw this in the past. Miroslav Lachman