From owner-freebsd-ports@FreeBSD.ORG Sun Oct 7 13:52:39 2012 Return-Path: Delivered-To: freebsd-ports@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id 129FC106564A for ; Sun, 7 Oct 2012 13:52:39 +0000 (UTC) (envelope-from mva@FreeBSD.org) Received: from smtprelay02.ispgateway.de (smtprelay02.ispgateway.de [80.67.31.36]) by mx1.freebsd.org (Postfix) with ESMTP id 97EDE8FC12 for ; Sun, 7 Oct 2012 13:52:38 +0000 (UTC) Received: from [89.182.12.239] (helo=localhost) by smtprelay02.ispgateway.de with esmtpsa (TLSv1:AES128-SHA:128) (Exim 4.68) (envelope-from ) id 1TKrGm-0004FK-Tv; Sun, 07 Oct 2012 15:51:49 +0200 Date: Sun, 7 Oct 2012 15:55:51 +0200 From: Marcus von Appen To: Michael Gmelin , freebsd-ports@freebsd.org Message-ID: <20121007135551.GD2133@medusa.sysfault.org> Mail-Followup-To: Michael Gmelin , freebsd-ports@freebsd.org References: <20121007152428.11a6172e@bsd64.grem.de> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="TybLhxa8M7aNoW+V" Content-Disposition: inline In-Reply-To: <20121007152428.11a6172e@bsd64.grem.de> User-Agent: Mutt/1.5.21 (2010-09-15) X-Df-Sender: MTEyNTc0Mg== Cc: Subject: Re: General usefulness of option descriptions X-BeenThere: freebsd-ports@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: Marcus von Appen List-Id: Porting software to FreeBSD List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 07 Oct 2012 13:52:39 -0000 --TybLhxa8M7aNoW+V Content-Type: text/plain; charset=us-ascii Content-Disposition: inline On, Sun Oct 07, 2012, Michael Gmelin wrote: > Hi, > > This probably has been discussed before, but I think in many cases > using the default descriptions of OptionsNG is more harm than good. That's not entirely true. They can provide a fallback, if the port maintainer forgot to add a meaningful description. > I converted security/libpreludedb to OptionsNG yesterday and > left in most of the descriptions and therefore overrode them. I did > that for a good reason, since I believe that the description of the > option should be more than just repeating the option name. > Unfortunately the portmgr in charge disagreed and removed all > description overrides, figuring that I must have forgotten to remove > them. That's why I raise this topic on the list - I feel like we're > using a lot of information if we converting ports like this. > > In this specific example this means: > > Before: > PERL=off: Include Perl bindings > PYTHON=off: Include Python bindings > MYSQL=on: Use MySQL backend > PGSQL=off: Use PostgreSQL backend > SQLITE=off: Use SQLite backend > > Afterwards: > DOCS=on: Build and/or install documentation > MYSQL=on: MySQL database > PERL=off: Perl scripting language > PGSQL=off: PostgreSQL database > PYTHON=off: Python bindings > SQLITE=off: SQLite database > > This might not seem dramatic at a first glance, but something > bad just happened here. We moved from describing what the option > actually means to the user in the context of the port ("Include Perl > binding", "Use MySQL backend") to what it means to the ports tree > ("Perl scripting language", "MySQL database"). The purpose of using the > option in context of the port is not visible anymore and at this point > showing the user MYSQL PERL PGSQL PYTHON SQLITE as options without any > descriptions would provide just as much information. The descriptions are defaults, not mandatory. You always can provide your own PERL_DESC - bsd.options.desc.mk just assigns default values, if the port does not provide them already. Thus, if you need a context-specific description, which does not match with the default provided by bsd.options.desc.mk, you can provide your own. [...] > 3. Global option descriptions seem inconsistent as well (all kinds > exist like support/backend/bindings etc., probably depending on the > first port that used them) and to make matters worse, they're > actually changing, e.g. bsd.options.desc.mk from 2012/08/31 said: > MYSQL_DESC?= MySQL backend > While the one from 2012/10/07 says: > MYSQL_DESC?= MySQL database > So even if using the default was contextually correct at some point, > it could just be changed without the maintainer noticing it. This indeed is problematic and I stumble over this from time to time myself. Since bsd.options.desc.mk can be changed by every committer and is still fairly young, this is unavoidable, especially since there are no real rules yet. Guidelines for the naming might be good, such as: If X provides a audio codec, the description has to be "X audio codec support" If X provides a video codec, the description has to be "X video codec support" If X provides a database binding, the description has to be "X database support" ... Mabye we can flesh that out based on what we have in bsd.options.mk already and add it to the docs and comment section of the file. Cheers Marcus --TybLhxa8M7aNoW+V Content-Type: application/pgp-signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.19 (FreeBSD) iEYEARECAAYFAlBxiecACgkQi68/ErJnpkfYOACfdIaR1XrD3l+iDDt2b9EqrfI5 UlEAnRuep7XlGM+Ods++xCTfN8n0v5Sy =+xxY -----END PGP SIGNATURE----- --TybLhxa8M7aNoW+V--