Bug #66801 MySQL protocol internal docs is split in too many nodes
Submitted: 13 Sep 2012 11:11 Modified: 13 Sep 2012 16:42
Reporter: Axel Schwenke Email Updates:
Status: Closed Impact on me:
None 
Category:MySQL Server: Documentation Severity:S3 (Non-critical)
Version: OS:Any
Assigned to: Jan Kneschke CPU Architecture:Any

[13 Sep 2012 11:11] Axel Schwenke 
Description:
The new documentation of the MySQL client/server protocol in the "MySQL internals manual" is broken into too many and hence too small nodes (node = HTML page). This renders this part of the manual nearly unreadable and unusable for any practical purpose.

How to repeat:
Look at: http://dev.mysql.com/doc/internals/en/binlog-file.html

That's just a single sentence. 15 words, 83 characters on a page of 14KB (plus images)

Suggested fix:
Split the protocol documentation into larger nodes. I.e. since there are 13 subchapters below "Chapter 15. MySQL Client/Server Protocol" you could use 13 nodes, one for 15.1 through 15.13 respectively.
[13 Sep 2012 11:25] MySQL Verification Team 
Thank you for the bug report.
[13 Sep 2012 13:02] Stefan Hinz 
Jan: Axel is right, the HTML section pages are way too small for some of the sections in the Client/Server Protocol chapter.

I think we basically have two options:

1) Rework the (automatically generated) Client/Server Protocol chapter so that we end up with less subsections. We could replace some of the <section>s (third-level and below) with <bridgehead>s which are not split out, but also don't appear in the TOC. This involves quite a bit of manual work, though.

2) I could set the chunking depth to 2. This would split out pages per chapter, and per first-level section. While this could result in some very long pages (in other chapters of the Internals manual), it would be my preferred solution, because I think other chapters suffer from too little information per page as well.

Objections against option #2? If not, I'll enable it asap.
[13 Sep 2012 16:42] Stefan Hinz 
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.

I've set the chunking level to 1 (= split out HTML on first-level section) which should address the issue.

Stefan