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

[Eitan Adler]

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.