From owner-freebsd-ports@freebsd.org Fri Sep 16 19:11:56 2016 Return-Path: Delivered-To: freebsd-ports@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 45293BDDB3E for ; Fri, 16 Sep 2016 19:11:56 +0000 (UTC) (envelope-from jim@ohlste.in) Received: from mailman.ysv.freebsd.org (unknown [127.0.1.3]) by mx1.freebsd.org (Postfix) with ESMTP id 229DC1E7 for ; Fri, 16 Sep 2016 19:11:56 +0000 (UTC) (envelope-from jim@ohlste.in) Received: by mailman.ysv.freebsd.org (Postfix) id 1E2E1BDDB3D; Fri, 16 Sep 2016 19:11:56 +0000 (UTC) Delivered-To: ports@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 1DD5CBDDB3C for ; Fri, 16 Sep 2016 19:11:56 +0000 (UTC) (envelope-from jim@ohlste.in) Received: from mail-qt0-x233.google.com (mail-qt0-x233.google.com [IPv6:2607:f8b0:400d:c0d::233]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (Client CN "smtp.gmail.com", Issuer "Google Internet Authority G2" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id D41771E6 for ; Fri, 16 Sep 2016 19:11:55 +0000 (UTC) (envelope-from jim@ohlste.in) Received: by mail-qt0-x233.google.com with SMTP id l91so47251318qte.3 for ; Fri, 16 Sep 2016 12:11:55 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ohlste-in.20150623.gappssmtp.com; s=20150623; h=subject:to:references:from:message-id:date:user-agent:mime-version :in-reply-to:content-transfer-encoding; bh=Tof/AKI7M88Bn99ZqArt2yK7jtneSsw19d5jzNt8fjk=; b=1+Xror9ofr60kl4VekXdIg1Klxr112dCPeEKZyFkcJApFfHQ6seh5/xBmolgp9saKE WXFkaaUXvGtKO8X/vRKezItiXPsEbvzNubkTehCb06PWTLeooboOOTEM2/nZOKF/jsLp uNnuXfGlXHJD0+vUgevYFKus8OVHUAGkQ84QlH/PcQfRrO/6MbrYYOYj1BtWTFrZXyCR SQAKNRfvDshex8bXPyaQhSAk22vqgftiL85wMLwYb+4xGSdLISunvB6wepDDdg2NCnPn ksn2IuxDk53IdexWFYUtI0dZxTRCHrvmca3mnoFtD4Da9qi3RemzvFThMOLv5Nevhw0q EmhA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:subject:to:references:from:message-id:date :user-agent:mime-version:in-reply-to:content-transfer-encoding; bh=Tof/AKI7M88Bn99ZqArt2yK7jtneSsw19d5jzNt8fjk=; b=P8nIuDW/RelCM6DeMjc3mb1XOQgCJaV0aUczZRkIVjXthOQoJnjiTwXV3kZRiLcx1h 7D9lBqSkC0BxNMyMCKEUlQ6ojEYbbNQwu3TMpfwaFsSNySpdklxhxIN/h/HU3Nxy6CjG m+MHwwkhSQOJILsbWn4dgISp2N7Cyhyi+F+VgM7HNzPJJuSV48fpjFvBQUQJ0udv1Fd+ pod8VEkSZngBOT1xey8XHw6PgMHGjheLzangC4xKQDfD0gIoZi1pFS5IDSxDBPLt/EQk a4YBZU08If6cztEwxxqcfr4c/Zj8ERtHyWVUtFXPsXeinH5iWebBG8N2lU+PJir1eKmq kvDw== X-Gm-Message-State: AE9vXwPMPOxlR45zxNfav3TQ/jYuZzd7XC4IV+hrzkny2q/Y8Wi370yqv1yTkhs+ESduSg== X-Received: by 10.200.44.75 with SMTP id e11mr17660628qta.9.1474053114822; Fri, 16 Sep 2016 12:11:54 -0700 (PDT) Received: from [192.168.1.24] (pool-108-39-64-29.nrflva.fios.verizon.net. [108.39.64.29]) by smtp.gmail.com with ESMTPSA id z34sm5493113qta.29.2016.09.16.12.11.53 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 16 Sep 2016 12:11:53 -0700 (PDT) Subject: Re: Checking port option descriptions To: Warren Block , ports@FreeBSD.org References: From: Jim Ohlstein Message-ID: <3de26d31-e4e0-ddc4-27ae-03bab473849b@ohlste.in> Date: Fri, 16 Sep 2016 15:11:51 -0400 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.3.0 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=windows-1252; format=flowed Content-Transfer-Encoding: 7bit X-BeenThere: freebsd-ports@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Porting software to FreeBSD List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 16 Sep 2016 19:11:56 -0000 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