MySQL Bugs: #37370: Muddled documentation section

Bug #37370	Muddled documentation section
Submitted:	12 Jun 2008 15:08	Modified:	18 Jun 2008 17:34
Reporter:	Matthias Urlichs	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S4 (Feature request)
Version:	5.0	OS:	Any
Assigned to:	Paul DuBois	CPU Architecture:	Any

Description:
This applies to § 19.4 of the MySQL 5.0 manual.

Given that the old versions are alpha code, first describing a buggy implementation and then documenting the current behavior as a set of deltas to *that* does not make any sense.

I want to understand this section and use it as a reference document for the CURRENT version of mysql. To do that, I essentially need to manually coalesce all these deltas into one coherent document.

THAT SHOULD BE YOUR JOB. Anything else is simply too error-prone. Among other reasons.

How to repeat:
Read the section and try to extract a set of guidelines to follow when writing stored procedures on 5.0.current.

Tear out hairs doing this, spend months to re-grow them, repeat.

Suggested fix:
Please describe the current version's behavior here, and move documenting the quirks of older versions elsewhere. Footnotes, sub-chapters, I don't care. Just don't do it in the main text.

Thank you for taking the time to write to us, but this is not a bug. Please double-check the documentation available at http://dev.mysql.com/doc/ and the instructions on
how to report a bug at http://bugs.mysql.com/how-to-report.php

This part of the documentation is more-or-less unuseable right now. This is a problem which should be fixed. Something that needs to be fixed is by definition buggy.

If you don't agree, please advise me where else to report this problem, and/or why there's a "documentation" section in the bug tracker in the first place.

Okay, marking this as a feature request. There's a lot of information about early 5.0 versions in that section that we might want to move to a subsection.

Matthias, the section says near the beginning:

"This section describes the development of binary logging in MySQL 5.0 with respect to stored routines (procedures and functions) and triggers. The discussion first summarizes the changes that have taken place in the logging implementation, and then states the current conditions that the implementation places on the use of stored routines. Finally, implementation details are given that provide information about when and why various changes were made."

Then the current implementation is identified shortly thereafter:

"As a consequence of the preceding changes, the following conditions currently apply to stored function creation when binary logging is enabled."

And the current implement section ends shortly after that:

"The rest of this section provides details on the development of stored routine logging."

Mmh. While you're right, that's somewhat non-obvious when you read that section; the mix of historic and current text really conveys something quite different.

Thank you for your bug report. This issue has been addressed in the documentation. The updated documentation will appear on our website shortly, and will be included in the next release of the relevant products.