General usefulness of option descriptions

[Michael Gmelin]

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