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
Category:	Server: Docs	Severity:	S4 (Feature request)
Version:	5.0	OS:	Any
Assigned to:	Paul DuBois	Target Version:
Triage:	D4 (Minor)

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.