Details
-
Type:
Docs: Improvement
-
Status:
Open
-
Priority:
Major
-
Resolution: Unresolved
-
Affects Version/s: None
-
Fix Version/s: None
-
Component/s: None
-
Labels:None
Description
In the current iteration of the ZF manual, section headings are all rendered as <h1> tags which makes certain sections very difficult to scan. For example, if you view:
http://framework.zend.com/manual/en/zend.validate.set.html
And try to scan through all the validators, you will essentially be presented with the following list:
- Standard Validation Classes
- Alnum
- Alpha
- Barcode
- Basic usage
- Optional checksum
- Writing custom adapters
- Between
- Callback
- Basic usage
- Usage with closures
- Usage with class-based callbacks
- Adding options
- CreditCard
- Basic usage
- Accepting defined credit cards
- Validation by using foreign APIs
- Ccnum
- Date
- ...
Immediately you should see a problem. There's no visual difference between Validation class titles and the titles of those classes' sub-sections (such as "Basic usage" etc).
Now, if you look at the XML source file, these are properly nested <sect1> <sect2> <sect3> elements with child <title> elements, but when rendered you lose the inherent meaning of that nesting.
In an ideal world these would be exported as <h1> <h2> <h3> tags, but I don't know how difficult that would be to implement. An easier solution (although less-than-ideal) would be to fix this through CSS.
There are a few CSS tweaks I would implement to fix this issue:
/* Indent Sub-Sections */
.section .section {
margin-left: 10px;
}
.section .section .section {
margin-left: 20px;
}
/* Change visual style of sub-headings */
#manual-container .section .section div.info h1 {
color: #016080;
border-color: #016080;
font-size: 1.3em;
}
#manual-container .section .section .section div.info h1 {
color: #206880;
border-color: #206880;
font-size: 1.1em;
}
These style changes will at least provide some visual hierarchy in heavily nested manual sections.
All section headers are still rendered as <h1> tags, however custom styling is applied to alter the font size depending on the nested level of the header. This does improve the readability of the page, but we really should be making use of the full range of <h1>-<h6> tags.