Re: docs/184550: bc -q option not documented in man page
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-unsubscr...@freebsd.org
Re: docs/184550: bc -q option not documented in man page
On 12/6/13, delp...@freebsd.org delp...@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-unsubscr...@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. -- Eitan Adler ___ freebsd-doc@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-doc To unsubscribe, send any mail to freebsd-doc-unsubscr...@freebsd.org
Re: docs/184550: bc -q option not documented in man page
On Fri, Dec 6, 2013 at 8:18 PM, Glen Barber g...@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 comments IMO don't qualify for docs. It should be documented in the man page. There are plenty of other examples cite option X is there for compatibility/historical purposes. Most users aren't going to review the source code for docs. -- Adam ___ freebsd-doc@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-doc To unsubscribe, send any mail to freebsd-doc-unsubscr...@freebsd.org
Re: docs/184550: bc -q option not documented in man page
On Fri, Dec 06, 2013 at 08:41:29PM -0600, Adam Vande More wrote: On Fri, Dec 6, 2013 at 8:18 PM, Glen Barber g...@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 comments IMO don't qualify for docs. It should be documented in the man page. There are plenty of other examples cite option X is there for compatibility/historical purposes. Most users aren't going to review the source code for docs. Since it does nothing, it absolutely applies, IMHO. Glen pgpZJTB4ZS5Ap.pgp Description: PGP signature
Re: docs/184550: bc -q option not documented in man page
On Fri, Dec 6, 2013 at 8:42 PM, Glen Barber g...@freebsd.org wrote: On Fri, Dec 06, 2013 at 08:41:29PM -0600, Adam Vande More wrote: On Fri, Dec 6, 2013 at 8:18 PM, Glen Barber g...@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 comments IMO don't qualify for docs. It should be documented in the man page. There are plenty of other examples cite option X is there for compatibility/historical purposes. Most users aren't going to review the source code for docs. Since it does nothing, it absolutely applies, IMHO. You're right, it is trivial. However it's still technically a bug. Maybe there is no good reason for q's existence. -- Adam ___ freebsd-doc@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-doc To unsubscribe, send any mail to freebsd-doc-unsubscr...@freebsd.org
Re: docs/184550: bc -q option not documented in man page
On Fri, Dec 6, 2013 at 9:18 PM, Glen Barber g...@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. -- Eitan Adler ___ freebsd-doc@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-doc To unsubscribe, send any mail to freebsd-doc-unsubscr...@freebsd.org
Re: docs/184550: bc -q option not documented in man page
-BEGIN PGP SIGNED MESSAGE- Hash: SHA512 On 12/6/13, 6:12 PM, Eitan Adler wrote: On 12/6/13, delp...@freebsd.org delp...@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-unsubscr...@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. However as Warren pointed out, it's a bug having it in synopsis and usage. This is fixed in r259058. 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. 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. Cheers, -BEGIN PGP SIGNATURE- iQIcBAEBCgAGBQJSosPDAAoJEJW2GBstM+nsTaEP/A6wFR3SoTDULnwsOosbpeWb 3EtYgecKijVUFjCHJBWxAApeW2EE5mUGdQsjiF7aXz/LsRyDgYt+EGlUZ8yPyd39 +sBfB3L9VxZESjIYbjyjZ9rUsiFE6yAyw74RC3+A9zg2Dj1BNBoLFHv/MVLbpmBP NArWFS28qaY57VGgnsZG4IU1k5cdhN74vI3wa+xMbXHXainlynbV8/ZMnaaX7/yT 9OZO57JgILqEw2v+4fOMbclMraFbVj8EMW6x+nT/6In7ikej9aIRjS2cjmzZ+Zyz DIAurwb8C4IZyugdg1GrYsLe785cE4dYFcZ3k8s7hZJlcuS/OUaGo/qJ1QngThfh qjsgxCrZzf+LEQTgx95FvGTuaQ+C88NsotJC0KWoMSFDcir8K+z47LLtrYH9W96z +yAVKRgVPILtSHoGo6ETGOxN2dIaqj0kF8yG9Vt93IUN11gazTeY2TKvk+4JostA rkxMeN7DPnB6osDP3cuJ5FljVMtc7Z9WI0SkbvcCoJB585VFDpT9CrehbtKdcyLK OT+zkrTWHLW7GF1ivYnrfcnWjGe5yEi/ri/PsYefuCjs4Ud1EsQmQwWXrQUE07tw vN/WfU4BccqSPFmMn/Gl2NjgIqXm/l+qiB2K6krph3KqYZdZqYPRxjQkBLHVO73B wdYolMzVMaqAq1GzUfUG =h8jo -END PGP SIGNATURE- ___ freebsd-doc@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-doc To unsubscribe, send any mail to freebsd-doc-unsubscr...@freebsd.org
Re: docs/184550: bc -q option not documented in man page
On Sat, Dec 7, 2013 at 1:44 AM, Xin Li delp...@delphij.net wrote: -BEGIN PGP SIGNED MESSAGE- Hash: SHA512 On 12/6/13, 6:12 PM, Eitan Adler wrote: On 12/6/13, delp...@freebsd.org delp...@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-unsubscr...@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. ___ freebsd-doc@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-doc To unsubscribe, send any mail to freebsd-doc-unsubscr...@freebsd.org
Re: docs/184550: bc -q option not documented in man page
-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 delp...@delphij.net wrote: -BEGIN PGP SIGNED MESSAGE- Hash: SHA512 On 12/6/13, 6:12 PM, Eitan Adler wrote: On 12/6/13, delp...@freebsd.org delp...@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-unsubscr...@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.16.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- ___ freebsd-doc@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-doc To unsubscribe, send any mail to freebsd-doc-unsubscr...@freebsd.org
Re: docs/184550: bc -q option not documented in man page
On Sat, Dec 7, 2013 at 2:09 AM, Xin Li delp...@delphij.net wrote: -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 delp...@delphij.net wrote: -BEGIN PGP SIGNED MESSAGE- Hash: SHA512 On 12/6/13, 6:12 PM, Eitan Adler wrote: On 12/6/13, delp...@freebsd.org delp...@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-unsubscr...@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? Works for me. Thank you very much! -- Eitan Adler ___ freebsd-doc@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-doc To unsubscribe, send any mail to freebsd-doc-unsubscr...@freebsd.org
Re: docs/184550: bc -q option not documented in man page
-BEGIN PGP SIGNED MESSAGE- Hash: SHA512 On 12/6/13, 11:11 PM, Eitan Adler wrote: On Sat, Dec 7, 2013 at 2:09 AM, Xin Li delp...@delphij.net wrote: -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 delp...@delphij.net wrote: -BEGIN PGP SIGNED MESSAGE- Hash: SHA512 On 12/6/13, 6:12 PM, Eitan Adler wrote: On 12/6/13, delp...@freebsd.org delp...@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-unsubscr...@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? Works for me. Thank you very much! Ok, committed as 259060 and thanks for your patience. Cheers, -BEGIN PGP SIGNATURE- iQIbBAEBCgAGBQJSosqEAAoJEJW2GBstM+nsneIP+ND+hIQUUFP6ndKvJqvBvqst gOLdX/hLA98Z8htPv4CIY/gz5UCVdatP8gtDRXgu/RE6QV3ZEMJz1pGLd16ZN+y5 SsCckwYNIibzt4zj3X1Yx+yKIf9FI80r6X2fGAh6LlyISI86QNCeFs5BU6ycXyMp FOhDDrJ0byoelly1kjAZiECuEwr+WcxtR7aSn4So7HT0/efzl16oSyb+lmyDdx+8 un88cFlArtpbn0MuQ390LE6LEEbQh8pvOh5dzR1yNgdn+bNkjnIUYrxc8sb7PAJ4 VZ+06KEojLThiVcvVdKJpm6MHEJZ6fJOeOevXm1kjpchbzTVAaFBpX/emkP7XR2t Nfj5MxmmMEFpjWMmYslAq9VZgQwDKxP6CR2Y8Cv7FVICCse1FAnmd5TSVxK4zM5H W5bzFBfLQTVX8P5PV2Bjc4Jz5SHeIQgfLcE2eLwNXe5MASC6eBLToK93BDCdGYxH 8GY2aIlJfVUbbLG0BY3pYGGGa0i77Fh00+qGQb/rguteYrCqCF1908a62M56GiOR rW6KqLSSu7Uv9lIKavp9ngLNwI4D7qAXz2J3U0lUclZ10lbsAA6EvFDAdi9hQ/Py XafPAvdRg+IkdYZLp0Ll0NZJzOJsRp/mTIkUalzfOEYsy0DGC/G9qHIbDOZmsZHo DzIiN1lXnjXdEXZgeUw= =/eYz -END PGP SIGNATURE- ___ freebsd-doc@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-doc To unsubscribe, send any mail to freebsd-doc-unsubscr...@freebsd.org
