Date: Sun, 7 Oct 2012 15:55:51 +0200 From: Marcus von Appen <mva@FreeBSD.org> To: Michael Gmelin <freebsd@grem.de>, freebsd-ports@freebsd.org Subject: Re: General usefulness of option descriptions Message-ID: <20121007135551.GD2133@medusa.sysfault.org> In-Reply-To: <20121007152428.11a6172e@bsd64.grem.de> References: <20121007152428.11a6172e@bsd64.grem.de>
next in thread | previous in thread | raw e-mail | index | archive | help
--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--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20121007135551.GD2133>