ZF-9508: Section headings are all rendered as <h1> tags

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/…

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 elements with child 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.

Comments

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.

I'm not sure this will be possible to accomplish. PhD uses Docbook5, which does not have a concept of specific section nesting depth tags (such as sect2, sect3, etc.) like Docbook4 had. As such, my understanding is that the XSLT does not keep track of the nesting level when parsing, which means the renderer cannot know either.

If somebody wants to dig into the PhD source and figure out how to make it happen, I'd welcome a patch -- the docbook build tools are all in the build-tools repo.

Fixed on Github (#73)

Example: http://framework.zend.com/manual/1.12/…