[EMAIL PROTECTED] wrote: > [EMAIL PROTECTED] wrote: > >>>>I think your whole experience is based on it. >> >> >> But shouldn't a significant feature like that be explained in the >> >> Python manuals? Why should I go dig up Sqlite FAQs to learn what >> >> should have been in the manuals? >> >>I don't know, but I will take a stab at a plausible explanation. First, >>sqlite support has only been in Python for a month or three. Its first >>official unveiling will be when 2.5 is released. > > > Although possibly too late for the final release, now would be a > good time to straighten out the documentation. > And you would be the best person to do it, since you're the one this has bitten in the tender parts.
> >>Second, it's common when >>wrapping functionality into Python to rely on the documentation for the >>thing being wrapped. The thinner the wrapper, the more you tend to rely on >>the underlying documentation. Also, the more functionally rich the thing >>you've wrapped, the more you rely on the underlying documentation. I >>wouldn't be at all surprised if the pysqlite author operated under that >>assumption. > > > Ok, that's certainly plausible. But it's not an excuse. The thinner the > documentation, the greater the emphasis should be made to point > the reader to a more adequate source. Simply listing the Sqlite home > page at the bottom of the page is hardly good enough. It should be > explicitly stated in bold letters that the reader should go read the > Sqlite FAQ because it radically differs from *real* databases and > provide a seperate link to it in the body of the documentation. > Whoa, there! This isn't commercial software we are talking about. While I appreciate the need to continually better Python's documentation, the "should" implies a moral imperative that the (volunteer) developers are unlikely to find compelling. > >>That the Python developers didn't pick up on the issue is not >>surprising. I'm not sure how many of them are (py)sqlite users, probably >>relatively few. > > > I would be surprised if they had never used ANY database. A little > thing like dynamic field typing will simply make it impossible to > migrate your Sqlite data to a *real* database. > > What I'll do is re-format my rant, suggest how *I* would do the > documentation, fix the errors I found in the examples and send it > off to the Python bug tracking as suggested in the manuals. > > How's that as a plan? That's the ticket. Great idea. Changes to the documentation can be suggested in plain ASCII, you don't have to grok the LaTeX markup. regards Steve -- Steve Holden +44 150 684 7255 +1 800 494 3119 Holden Web LLC/Ltd http://www.holdenweb.com Skype: holdenweb http://holdenweb.blogspot.com Recent Ramblings http://del.icio.us/steve.holden -- http://mail.python.org/mailman/listinfo/python-list
