From owner-freebsd-ports@FreeBSD.ORG Sun Oct 7 13:24:28 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 EC7BC10656C1 for ; Sun, 7 Oct 2012 13:24:27 +0000 (UTC) (envelope-from freebsd@grem.de) Received: from mail.grem.de (outcast.grem.de [213.239.217.27]) by mx1.freebsd.org (Postfix) with SMTP id 5C7DD8FC18 for ; Sun, 7 Oct 2012 13:24:26 +0000 (UTC) Received: (qmail 67198 invoked by uid 89); 7 Oct 2012 13:24:25 -0000 Received: from unknown (HELO bsd64.grem.de) (mg@grem.de@80.137.110.241) by mail.grem.de with ESMTPA; 7 Oct 2012 13:24:25 -0000 Date: Sun, 7 Oct 2012 15:24:28 +0200 From: Michael Gmelin To: freebsd-ports@freebsd.org Message-ID: <20121007152428.11a6172e@bsd64.grem.de> X-Mailer: Claws Mail 3.8.1 (GTK+ 2.24.6; amd64-portbld-freebsd9.0) Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Subject: General usefulness of option descriptions X-BeenThere: freebsd-ports@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list 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:24:28 -0000 Hi, This probably has been discussed before, but I think in many cases using the default descriptions of OptionsNG is more harm than good. 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. One could argue that if a different description is necessary, a different option name should be chosen. But this doesn't really work, since the meaning to the ports tree in fact *is* that a dependency to Perl or MySQL should be introduced, so using the global option names makes sense. If one wants to install all ports with their Perl or MySQL features enabled, just flipping that one switch should do it, regardless of the exact meaning in the context of the port. Conclusion: 1. Option names are for the ports tree structure, there should be as little as possible and global option names are to be preferred. The more generic the better, they express a software dependency between ports on the level of "give me support for xyz", but not the purpose of this dependency in context of the port. 2. Option descriptions are for the user of the port and should be as contextual as possible. In the end it makes a difference to the user what feature/functionality is actually accomplished by introducing/installing a dependency. There are always options where this is just fine and the meaning is clear (e.g. THREADS, OPTIMIZE_CFLAGS), but blindly removing this information from a port is harmful. 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. What are your thoughts on this? Cheers, Michael -- Michael Gmelin