Hello,
On 09/16/2016 11:52 AM, Warren Block wrote:
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.
"[S]ome" being the operative word here. I don't disagres with your basic
premise, but the truth is, at the end of the day it's up to the user to
understand the consequences of his decisions. If a user doesn't know
what 'XYZ' is, then adding 'Include protocols for use with XYZ servers'
probably doesn't tell him or her that much. On the other hand, if a user
knows what 'XYZ' is, then 'Enable XYZ' is likely enough information with
which to make a decision.
So in this case there are likely to be two categories of users: those
who know what 'XYZ' is and those who do not. Those in the former have
the information either way. Those in the latter have three basic choices:
1) Educate themselves before possibly adding software to their system
that they do not fully understand, thereby moving into to the former
category.
2) Choose the default, on the (very possibly mistaken) assumption that
the porter "knows what's best." Unfortunately that assumption may be a
bad one, as the porter/maintainer is more likely to choose something
that satisfies "most users" and loads people with unnecessary
dependencies (thus defeating much of the benefit of building your own
ports), or worse, to choose options that work best for him or her.
3) Ask themselves Harry Callahan's famous question, "Do I feel lucky?"
and go away from the default.
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.
The program is called optcheck and can be found here:
http://www.wonkity.com/~wblock/tmp/optcheck/
The readme.txt explains a little more, and optcheck-output.txt is a full
run against the ports tree from a couple of weeks ago.
The tests are just some that I came up with quickly, and can certainly
be improved. More can be added, and they can make better suggestions.
Ultimately, the hope is that this functionality will be added to
portlint or somewhere else that would help prevent these types of
pointless descriptions.
For usage, run
optcheck -h
For a run against the full ports tree, use just
optcheck
To run against a category or single port directory, use -d:
optcheck -d /usr/ports/devel
optcheck -d /usr/ports/print/ghostscript9-base
--
Jim Ohlstein
_______________________________________________
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"
