Date: Sun, 7 Oct 2012 15:59:43 +0200 From: Milan Obuch <freebsd-ports@dino.sk> To: Michael Gmelin <freebsd@grem.de> Cc: freebsd-ports@freebsd.org Subject: Re: General usefulness of option descriptions Message-ID: <20121007155943.5aa59324@zeta.dino.sk> 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
On Sun, 7 Oct 2012 15:24:28 +0200
Michael Gmelin <freebsd@grem.de> 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.
>
> 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.
>
Hi,
in my opinion, the best would be to indicate what will be gained using
an option. In some situation it is needed to try to install smallest
possible number of packages. In this situation it is important to know
what will be missed if an option is not selected and make informed
decision whether it will be enabled or not.
> 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.
>
I think this is bad, really. For me it is important to know what I gain
if I switch some option on, whether it is something to be missed in
some occasion. But I already wrote that above :)
There is another change, but easy to handle - options a sorted
alphabetically by default. One could use NO_OPTION_SORT=yes to set it
the other way.
> 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.
>
I support this one. Which information should be the decision to set or
unset some option based on if not on knowledge which features will be
gained/missed by doing so?
> 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?
>
See above :)
Regards,
Milan
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20121007155943.5aa59324>