From owner-freebsd-ports@FreeBSD.ORG Tue Apr 29 01:28:47 2008 Return-Path: Delivered-To: ports@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 86A241065670 for ; Tue, 29 Apr 2008 01:28:47 +0000 (UTC) (envelope-from wxs@atarininja.org) Received: from syn.atarininja.org (syn.csh.rit.edu [129.21.60.158]) by mx1.freebsd.org (Postfix) with ESMTP id 5D47E8FC16 for ; Tue, 29 Apr 2008 01:28:47 +0000 (UTC) (envelope-from wxs@atarininja.org) Received: by syn.atarininja.org (Postfix, from userid 1001) id A28905C5D; Mon, 28 Apr 2008 21:32:01 -0400 (EDT) Date: Mon, 28 Apr 2008 21:32:01 -0400 From: Wesley Shields To: Scot Hetzel Message-ID: <20080429013201.GD84399@atarininja.org> References: <20080426020216.GM23691@atarininja.org> <790a9fff0804260211v514de80cq3379dee0aa97f0aa@mail.gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <790a9fff0804260211v514de80cq3379dee0aa97f0aa@mail.gmail.com> User-Agent: Mutt/1.5.17 (2007-11-01) Cc: ports@freebsd.org Subject: Re: long descriptions in OPTIONS X-BeenThere: freebsd-ports@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Porting software to FreeBSD List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 29 Apr 2008 01:28:47 -0000 On Sat, Apr 26, 2008 at 04:11:06AM -0500, Scot Hetzel wrote: > On 4/25/08, Wesley Shields wrote: > > Based upon an idea in an earlier thread on this list[1] I came up with > > two ways of adding an extended description to our existing OPTIONS > > framework. > > > > 1: Extend the OPTIONS to be 4 fields instead of the current 3 fields. > > The 4th field would be the long description - providing more detailed > > information about what this option does or supports. In order to > > distinguish between a port with 4 OPTIONS without the long description > > (12 fields) and a port with 3 OPTIONS with the long description (also 12 > > fields) the patch requires the port to turn on a knob (OPTIONS_DESC) > > when using the long field. The idea is that over time this will become > > the default and can eventually be removed. > > > > 2: Leave OPTIONS as is but support a DESC_FOO variable for each OPTION. > > This variable would be the long description field, and if it doesn't > > exist a default message indicating such would be displayed. > > > > Both of these methods are displayed to the user when '?' or F1 is > > pressed during the dialog screen. In the case of (1) the extra dialog > > is only shown if the port supports it. In the case of (2) the extra > > dialog is always available since we have a default message to display. > > I suppose a third way would be to use a default message when the knob is > > not set for (1), which would probably simplify things slightly. > > > > Couple of suggestions: > > - OPTION_DESC (choice 1) or DESC_FOO (choice 2) not defined, then use > field 2 as the long description along with "[NO EXTENDED DESCRIPTION > DEFINED]" appended. Done. Thanks! > - Remove "Contact the maintainer to fix this" from choice 2, as some > maintainers may resent being contacted by users to add extended > descriptions to their ports. I meant to take that out, sorry. :) > - Use OPTION_DESC_FOO instead of DESC_FOO (choice 2). Kind of a long variable name, but more descriptive. Done. > - add support for ${PORTSDIR}/MK/bsd.optiondescription.mk, This file > holds a list of standard extended option descriptions, for example: > > _STD_DESC_A4SIZE= "Sets the default paper size used by ${PORTNAME} - > A4 (210 mm ? 297 mm) or Letter (8? in ? 11 in, 215.9 mm ? 279.4 mm)" > > The following code, should accomplish the above for choice 2: > > LONGDESC=$$(cd ${.CURDIR} && ${MAKE} ${__softMAKEFLAGS} -V OPTION_DESC_$$1); \ > if [ "x$${LONGDESC}" = "x" ] ; then \ > LONGDESC=$$(cd ${.CURDIR} && ${MAKE} ${__softMAKEFLAGS} -V > _STD_DESC_$${1}); \ > if [ "x$${LONGDESC}" = "x" ]; then \ > LONGDESC="$$2 [NO EXTENDED DESCRIPTION DEFINED]" ; \ > fi ; \ > fi ; \ > ${ECHO_CMD} $$1: $${LONGDESC} | fmt >> $${TMPOPTIONDESCFILE}; \ > ${ECHO_CMD} >> $${TMPOPTIONDESCFILE}; \ While I'm not opposed to adding standard descriptions somewhere, I don't think it is really necessary at this point in time. I'm not familiar enough with enough options to say what should be in this file. It should be fairly easy to implement later on down the road though, once people are starting to see trends in common OPTIONS descriptions. Thank you for your input, I'll update the patch and send-pr it eventually. -- WXS