From owner-freebsd-ports@FreeBSD.ORG  Wed May 30 23:40:09 2012
Return-Path: <owner-freebsd-ports@FreeBSD.ORG>
Delivered-To: ports@freebsd.org
Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52])
	by hub.freebsd.org (Postfix) with ESMTP id 9DFE61065670;
	Wed, 30 May 2012 23:40:09 +0000 (UTC)
	(envelope-from wblock@wonkity.com)
Received: from wonkity.com (wonkity.com [67.158.26.137])
	by mx1.freebsd.org (Postfix) with ESMTP id 210808FC0C;
	Wed, 30 May 2012 23:40:09 +0000 (UTC)
Received: from wonkity.com (localhost [127.0.0.1])
	by wonkity.com (8.14.5/8.14.5) with ESMTP id q4UNe8ij077571;
	Wed, 30 May 2012 17:40:08 -0600 (MDT)
	(envelope-from wblock@wonkity.com)
Received: from localhost (wblock@localhost)
	by wonkity.com (8.14.5/8.14.5/Submit) with ESMTP id q4UNe8gU077568;
	Wed, 30 May 2012 17:40:08 -0600 (MDT)
	(envelope-from wblock@wonkity.com)
Date: Wed, 30 May 2012 17:40:08 -0600 (MDT)
From: Warren Block <wblock@wonkity.com>
To: Alberto Villa <avilla@freebsd.org>
In-Reply-To: <CAJp7RHY_xXBX+5nwAwDBR+k+f_Ho9+ROVCT-3z54hR0b6dFfbA@mail.gmail.com>
Message-ID: <alpine.BSF.2.00.1205301737150.77445@wonkity.com>
References: <20120530063334.GD9952@ithaqua.etoilebsd.net>
	<CAJp7RHY_xXBX+5nwAwDBR+k+f_Ho9+ROVCT-3z54hR0b6dFfbA@mail.gmail.com>
User-Agent: Alpine 2.00 (BSF 1167 2008-08-23)
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed
X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.2.7
	(wonkity.com [127.0.0.1]); Wed, 30 May 2012 17:40:08 -0600 (MDT)
Cc: ports@freebsd.org, Baptiste Daroussin <bapt@freebsd.org>
Subject: Re: Options name, descriptions and consistency
X-BeenThere: freebsd-ports@freebsd.org
X-Mailman-Version: 2.1.5
Precedence: list
List-Id: Porting software to FreeBSD <freebsd-ports.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-ports>,
	<mailto:freebsd-ports-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/freebsd-ports>
List-Post: <mailto:freebsd-ports@freebsd.org>
List-Help: <mailto:freebsd-ports-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-ports>,
	<mailto:freebsd-ports-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Wed, 30 May 2012 23:40:09 -0000

On Wed, 30 May 2012, Alberto Villa wrote:

> On Wed, May 30, 2012 at 8:33 AM, Baptiste Daroussin <bapt@freebsd.org> wrote:
>> On of the reasons of bsd.options.desc.mk is to be able to share common options
>> and descriptions, to have better consistency between ports and to have general
>> meaning descriptions that make more sense, has anyone can improve the
>> description of an option.
>
> While I really like what bsd.options.desc.mk is supposed to do, I
> would like to recommend to any committer/maintainer (and I will
> personally submit a patch for the soon-to-come documentation and for
> the file itself) to think before always relying on on default option
> descriptions.
>
> Sometimes just saying "Enable XXX support" doesn't mean anything to
> the user, and a more explanatory text would be far better, explaining
> maybe what feature one is about to enable instead of just what he is
> going to depend on.

Deja vu:

http://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/makefile-options.html#AEN2598

Look at the second tip.  That's brand new, added because users were 
complaining in the forums recently.  (And before, but recently got my 
attention.)

> So, please, do not hesitate to redefine option descriptions for your
> ports if you feel you can add more information for the port specific
> case.

Some of the entries in the KNOBS file could use better descriptions 
also.