Date: Sun, 7 Oct 2012 15:24:28 +0200 From: Michael Gmelin <freebsd@grem.de> To: freebsd-ports@freebsd.org Subject: General usefulness of option descriptions Message-ID: <20121007152428.11a6172e@bsd64.grem.de>
next in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20121007152428.11a6172e>