On Jul 7, 2007, at 12:13 AM, Stan wrote: > >> >> This is where our users come in. Please *please* submit documentation >> changes and additions via STR. I am greateful even for single- >> sentence additions if that makes it clearer for the next user. > > Let me answer with a simple example. > > Here's the documentation for Fl_Widget::color > > Hmmm. The Fl_Input is red, the Fl_Choice has a red button, and > the Fl_Input_Choice is unaffected. Who knew? Is there any further > documentation for Fl_Input::color(), Fl_Choice::color(), or > Fl_Input_Choice::color()? Nope. So maybe setting the background > color of these widgets isn't supposed to change their appearance.
Um, OK, this is somewhat frustrating, not so much because the documentation seems to be off, but rather because some widgets do not behave the way they should. Fl_Input_Choice in particular suffers from issues in the ABI that we can't fix for 1.1 for binary compatibility. But I am again getting much too much into details of the implementation. > I can keep digging, I suppose, or I can do as Erco suggested, just > peek into the code to find out what's really going on, so that I > can get some productive work done. (With all the risk that doing > so implies). > > Should I submit an STR? What would it say? "The documentation > is much too sparse to be helpful?" "The law of least surprise > is violated?" Really, I wouldn't know where to start. It's a circle. Your productivity is broken when filing STRs, but if nobody files STRs, nothing will get fixed, and the next user will stumble over the same problem. The best thing to do is file an STR and follow these rules: If something simply does not work as expected, and you don't have time to investigate: File an STR, describe what you do, what you expect to see, and what you get instead. If you have a link to documentation describing the expected behaviour, post that too. If it is a user issue, misunderstanding, or similar, we will reply via the STR form and close the STR. If you then have a suggestion for better docs, please file a new STR with your suggestions. If we cann;t duplicate the issue, we will ask you to post some c++ code or a .fl file that shows the issue. We will compile and run your code and help you out. If it is a bug, we will try to give you a workaround first, then fix it eventually. Patches are very welcome here. If you have the tim to dig deeper in our code, we can skip most of the steps above, if you can point us to where exactly the problem lies. We can usually provide a fix or documentation update in a short time. So, for what you described above, you can pretty much post exactly that as a STR. Matthias ---- http://robowerk.com/ _______________________________________________ fltk mailing list [email protected] http://lists.easysw.com/mailman/listinfo/fltk
