From owner-freebsd-doc@FreeBSD.ORG Sat Dec 7 07:09:24 2013 Return-Path: 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 8BF9EBC5; Sat, 7 Dec 2013 07:09:24 +0000 (UTC) Received: from anubis.delphij.net (anubis.delphij.net [IPv6:2001:470:1:117::25]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 656BF18F1; Sat, 7 Dec 2013 07:09:24 +0000 (UTC) Received: from delphij-macbook.local (unknown [IPv6:2001:470:83bf:0:ed89:fcd3:46d0:72b3]) (using TLSv1 with cipher ECDHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by anubis.delphij.net (Postfix) with ESMTPSA id B551D26969; Fri, 6 Dec 2013 23:09:23 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=delphij.net; s=anubis; t=1386400163; bh=Qq9ztL4tPQ7TyogkpoLPvs0iNq/sylIrAEAVcaVC+5Y=; h=Date:From:Reply-To:To:CC:Subject:References:In-Reply-To; b=Nk0Hb300cCL089mLYTZOvzg4C7aN7RBxgxwbStbtGN6nCuoKO92GIFpUz0eW9LiZt BHEbZttZITEu6/nxbElKsNNgMvQFQb+YoJPob1tkUxxwIokT1jnwV8X/faYQU9Hzc4 dQn3jlF2aM+iDexYdndRY4UyFvXjjFTT25Hk7A3Q= Message-ID: <52A2C9A0.4050800@delphij.net> Date: Fri, 06 Dec 2013 23:09:20 -0800 From: Xin Li Organization: The FreeBSD Project MIME-Version: 1.0 To: Eitan Adler , Xin LI Subject: Re: docs/184550: bc -q option not documented in man page References: <201312070107.rB717SAW015758@freefall.freebsd.org> <52A2C3C3.9010703@delphij.net> In-Reply-To: Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit Cc: "freebsd-doc@freebsd.org" , Xin LI , "Ronald F. Guilmette" X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list Reply-To: d@delphij.net List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 07 Dec 2013 07:09:24 -0000 -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA512 On 12/6/13, 10:48 PM, Eitan Adler wrote: > On Sat, Dec 7, 2013 at 1:44 AM, Xin Li > wrote: >> -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA512 >> >> On 12/6/13, 6:12 PM, Eitan Adler wrote: >>> On 12/6/13, delphij@freebsd.org wrote: >>>> Synopsis: bc -q option not documented in man page >>>> >>>> State-Changed-From-To: open->closed State-Changed-By: >>>> delphij State-Changed-When: Sat Dec 7 01:06:05 UTC 2013 >>>> State-Changed-Why: This is intentional. Won't fix. >>>> >>>> >>>> Responsible-Changed-From-To: freebsd-doc->delphij >>>> Responsible-Changed-By: delphij Responsible-Changed-When: Sat >>>> Dec 7 01:06:05 UTC 2013 Responsible-Changed-Why: Take. >>>> >>>> http://www.freebsd.org/cgi/query-pr.cgi?pr=184550 >>>> _______________________________________________ >>>> freebsd-doc@freebsd.org mailing list >>>> http://lists.freebsd.org/mailman/listinfo/freebsd-doc To >>>> unsubscribe, send any mail to >>>> "freebsd-doc-unsubscribe@freebsd.org" >>>> >>> >>> all options should be documented. An undocumented option is a >>> bug. If we don't want people using it we should document as >>> such. >> >> Well, no, it's not an undocumented option but a bug-for-bug >> compatibility shim. > > Eh? > >> However as Warren pointed out, it's a bug having it in synopsis >> and usage. > > It is not a bug. > >> This is fixed in r259058. > > This is a bug. > >> With our limited manpower, I think it's more important to improve >> our documentation in the direction that we describe our stuff >> better, like how to write a vt(4) driver, etc. > > I agree that we need better documentation for our own features; > however, this is not a dichotomy. > >> rather than documenting the bug-for-bug features which would just >> give the reader an impression like "I can write program according >> to GNU command line standard and expect the BSD people to >> diligently implement bug-for-bug compatibility". > > A similar discussion occurred when we implemented '==' for > test(1). If a program accepts some flag as input, or some text as > input, it must be documented. We may document it as a > non-portable, to be avoided feature, but it should not be left > alone. Fair enough, how about this? Index: bc.1 =================================================================== - --- bc.1 (revision 259059) +++ bc.1 (working copy) @@ -35,7 +35,7 @@ .\" .\" @(#)bc.1 6.8 (Berkeley) 8/8/91 .\" - -.Dd January 22, 2010 +.Dd December 6, 2013 .Dt BC 1 .Os .Sh NAME @@ -349,6 +349,14 @@ .Fl l option is specified on the command line. .El +.Sh COMPATIBILITY +The +.Fl q +and +.Fl Fl quiet +options are no-ops for compatibility with some other implementations of +.Nm +and their use is discouraged. .Sh SEE ALSO .Xr dc 1 .Pp When rendered they would show like this: COMPATIBILITY The -q and --quiet options are no-ops for compatibility with some other implementations of bc and their use is discouraged. Cheers, -----BEGIN PGP SIGNATURE----- iQIcBAEBCgAGBQJSosmgAAoJEJW2GBstM+nsHo4P/Aqx4cY1Lgx/G1Sar/dKgMX+ 1aUFQVCIViyf57ZG8Jm9JbXk3ygQ/DuszC46VD8G2qxXKTlreRtdPtIP7FpwV/Mx KtYWCpdCaqVTncwaxNGy7mx0Cbk9sQL7Qqqf8DCu5MrZOTak4wHB+GykEslOhjCp lKxiiiVYd0HMbGomBFX4gU5AW9hZdDvE3e1u7z73S3QTj3YKFYKoU1k38pUsuJoN oeaAk4t8LE5KuF2mdWYC3SZk+v9Rx/1jRtIqbbnVvgxGdxoQQu4iHVkuZDVYi/jN GckqetFmGDmErh8svvu/B8NrGipi4uv+58Vuno2XUc81kBkftekspluYbEIhN3cz s5NkRUW7Ly00hhS1+Nn1V9FhNEgjr6DOpofL2hLhbF4W4FjcZaeYEiZAtaeVtNEN seELzis5uTKx9RySSSHsI9u7oLncCXhDO9fhB7B8+qPF7oxf3ctZ0r9ienaBAVGm UD87rBPhd9nCEEs7WtoxXEyF6iKM/wrsSQqY8D7ZyBkUzrdm32i8E5gxU3pDfVrT hc8eBGLvfgO+tzU1awwk3XICb5srgWIwlSgzelpSul90uJD51e5fAElRwHWaeSCq e5prNIIFMJUbDCE9dFjGUoeDlUX2oIegts+8v8Fim/LckBm4Qu/hwoPkDFyLfNx4 hzXavTYfn5oGesQDOc2p =qeqd -----END PGP SIGNATURE-----