ZF-9509: Additional TOC levels
I find it extremely difficult to navigate the longer parts of the documentation, especially those with many sections and sub-sections. Perfect examples are Zend_Validate and Zend_Filter. If you want to view a list of every filter available, you essentially have to scan the entire Zend_Filter documentation; there's no way to get that list, even though the source XML files are nicely nested with tags and child tags. The lack of deep TOC levels, plus ZF-9508 makes it very difficult to find deeply nested elements in the manual.
For example, try finding the filter that removes all non-number characters in the Zend_Validate docs. If you don't know that the validator is Zend_Validate_Digits, you're really SOL 'cause you're going to have to scan the entire document. Even if you do know the name, you have to scroll through alphabetically until you find the right section (and because of ZF-9508 it's even harder to find the right section).
So anyway, enough complaining. It seems to me like there are three (non mutually exclusive) solutions:
# Add a full TOC, going as deep as possible on the initial TOC pages. That way if you want to go somewhere specific, or want to scan the entire documentation for a component you have a place to go. # Add a full section TOC at the top of each page that provides links to each <sec#> element on that page. # Add the full TOC to the "Navigation" widget in the right-hand side bar of each page.
If it were me I would do all 3. If you're concerned that a full TOC would take up too much space, perhaps they could be collapsible and anything past level 3 would be collapsed. Or, #2 from that list could be removed as it is likely the one the most often get in the way.
If this is something ZF is willing to change, I'll happily work with whoever is in charge of the documentation formatting to implement as much as I'm able.