Issues

ZF-9508: Section headings are all rendered as

tags

Issue Type: Docs: Improvement Created: 2010-03-22T10:30:47.000+0000 Last Updated: 2013-02-07T13:47:06.000+0000 Status: Resolved Fix version(s): Reporter: Chris Morrell (inxilpro) Assignee: Frank Brückner (frosch) Tags: Related issues: - ZF-9509

Attachments:

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:

<pre class="highlight">
/* 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

Posted by Adam Lundrigan (adamlundrigan) on 2011-11-17T02:54:12.000+0000

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.

Posted by Matthew Weier O'Phinney (matthew) on 2011-11-17T03:07:11.000+0000

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.

Posted by Frank Brückner (frosch) on 2013-02-07T13:47:06.000+0000

Fixed on Github (#73)

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

Have you found an issue?

See the Overview section for more details.

Copyright

© 2006-2016 by Zend, a Rogue Wave Company. Made with by awesome contributors.

This website is built using zend-expressive and it runs on PHP 7.

Contacts