docs/184550: bc -q option not documented in man page

[Xin Li]

-----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 <delphij at delphij.net>
> wrote:
>> -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA512
>> 
>> On 12/6/13, 6:12 PM, Eitan Adler wrote:
>>> On 12/6/13, delphij at freebsd.org <delphij at 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 at freebsd.org mailing list 
>>>> http://lists.freebsd.org/mailman/listinfo/freebsd-doc To 
>>>> unsubscribe, send any mail to 
>>>> "freebsd-doc-unsubscribe at 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-----