Warren Block wrote on 09/16/2016 17:52:
Ports options ask the user to make a decision on whether to enable that
option. Option descriptions are critical for this, giving the user
information to help them make that decision.
Unfortunately, what is clear to the porter is often not clear to a user.
The Porter's Handbook says "Do not just repeat the name", but this still
happens, either exactly, or with a description that adds no information.
For example:
XYZ Enable XYZ
The description here adds no information. The name of the option itself
tells the reader that this is for enabling or disabling a feature. The
option asks them to make a decision, whether to enable that option or
not, or even just to leave it at the default, but does not give them any
help in making that decision. Let's improve that:
XYZ Include protocols for use with XYZ servers
This gives the reader some additional details.
Because so many of the option descriptions have predictable
no-added-information styles, it is possible to write a program that
detects these. In the process of doing that, I found some actual bugs in
descriptions that were not caught by other parts of the ports build or
portlint.
There are even more confusion. Some options are used by many ports but
their real meaning / impact on each port is different.
The next problem is options doing nothing to "this" port but just pull
some other port as dependency because maintainer thinks it is useful for
the end users to have installed it too - this should be avoided (IMHO).
I don't have port names in hand but I know I saw this in the past.
Miroslav Lachman
_______________________________________________
freebsd-ports@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-ports
To unsubscribe, send any mail to "freebsd-ports-unsubscr...@freebsd.org"
