From owner-freebsd-doc@FreeBSD.ORG  Sat Dec  7 05:59:24 2013
Return-Path: <owner-freebsd-doc@FreeBSD.ORG>
Delivered-To: freebsd-doc@freebsd.org
Received: from mx1.freebsd.org (mx1.freebsd.org
 [IPv6:2001:1900:2254:206a::19:1])
 (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits))
 (No client certificate requested)
 by hub.freebsd.org (Postfix) with ESMTPS id 21F18BA8;
 Sat,  7 Dec 2013 05:59:24 +0000 (UTC)
Received: from wonkity.com (wonkity.com [67.158.26.137])
 (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits))
 (No client certificate requested)
 by mx1.freebsd.org (Postfix) with ESMTPS id C77F91527;
 Sat,  7 Dec 2013 05:59:23 +0000 (UTC)
Received: from wonkity.com (localhost [127.0.0.1])
 by wonkity.com (8.14.7/8.14.7) with ESMTP id rB75xKpk058148;
 Fri, 6 Dec 2013 22:59:20 -0700 (MST)
 (envelope-from wblock@wonkity.com)
Received: from localhost (wblock@localhost)
 by wonkity.com (8.14.7/8.14.7/Submit) with ESMTP id rB75xKZi058145;
 Fri, 6 Dec 2013 22:59:20 -0700 (MST)
 (envelope-from wblock@wonkity.com)
Date: Fri, 6 Dec 2013 22:59:20 -0700 (MST)
From: Warren Block <wblock@wonkity.com>
To: Eitan Adler <lists@eitanadler.com>
Subject: Re: docs/184550: bc -q option not documented in man page
In-Reply-To: <CAF6rxgm7qqE5cd-ax7=LipUGJpSA19ZJeJ1+_ZqpCqCfMU_cPw@mail.gmail.com>
Message-ID: <alpine.BSF.2.00.1312062240090.58092@wonkity.com>
References: <201312070107.rB717SAW015758@freefall.freebsd.org>
 <CAF6rxgk50a0gL7_O3t=iFM-XGjnwam07ZNkOOgsWV=Tu7OKDXQ@mail.gmail.com>
 <20131207021835.GK20078@glenbarber.us>
 <CAF6rxgm7qqE5cd-ax7=LipUGJpSA19ZJeJ1+_ZqpCqCfMU_cPw@mail.gmail.com>
User-Agent: Alpine 2.00 (BSF 1167 2008-08-23)
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed
X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3
 (wonkity.com [127.0.0.1]); Fri, 06 Dec 2013 22:59:20 -0700 (MST)
Cc: Glen Barber <gjb@freebsd.org>,
 "freebsd-doc@freebsd.org" <freebsd-doc@freebsd.org>,
 Xin LI <delphij@freebsd.org>, "Ronald F. Guilmette" <rfg@tristatelogic.com>
X-BeenThere: freebsd-doc@freebsd.org
X-Mailman-Version: 2.1.17
Precedence: list
List-Id: Documentation project <freebsd-doc.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/options/freebsd-doc>,
 <mailto:freebsd-doc-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/freebsd-doc/>
List-Post: <mailto:freebsd-doc@freebsd.org>
List-Help: <mailto:freebsd-doc-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-doc>,
 <mailto:freebsd-doc-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Sat, 07 Dec 2013 05:59:24 -0000

On Fri, 6 Dec 2013, Eitan Adler wrote:

> On Fri, Dec 6, 2013 at 9:18 PM, Glen Barber <gjb@freebsd.org> wrote:
>> On Fri, Dec 06, 2013 at 09:12:30PM -0500, Eitan Adler wrote:
>>> all options should be documented.  An undocumented option is a bug.
>>> If we don't want people using it we should document as such.
>>>
>>
>> It is documented.
>>
>>                 case 'q':
>>                         /* compatibility option */
>>                         break;
>
> Source code is not documentation.  It it surprising to hear that,
> especially on this list.

This is a bit puzzling.  If -q is secret somehow, let's take it out of 
the synopsis.  If it's real, it should be in the synopsis and 
description.

   -q	No-op, does nil, nothing, nada.  Emphatically not for
 	compatibility with GNU bc, but coincidentally allows scripts
 	from icky other platforms where -q does something to run without error.
 	May occasionally print "gravy-sucking pig-dog" or contain traces
 	of soy, nuts, eggs, titanium, and riboflavin, all part of a
 	really interesting alibi.