FAQ+TOC problem: force-toc option

• Key: FOR-559
• Type: New Feature
• Status: Closed
• Resolution: Fixed
• Priority: Minor
• Assignee: Ross Gardler
• Reporter: Jeremias Maerki
• Component/s: Skins (general issues)
• Affects Version/s: 0.6, 0.7, 0.8
• Fix Version/s: 0.8

Description

This is a hybrid patch/RFE/bugfix. Today, I've taken another stab at the problem Clay Leeds reported to you in May:
http://www.mail-archive.com/[e-mail]/msg00528.html

We have the problem in FOP that the TOC for the FAQ page isn't generated.

Comments

[Jeremias Maerki]

The proposed patch.

[David Crossley]

(Moved detail from Description to Comment.)

I've found out what the problem is and have a suggestion for improvement. Essentially, the problem goes away when I change the skinconf.xml from:

  <toc max-depth="2" min-sections="3" location="page"/>

to:

  <toc max-depth="2" min-sections="1" location="page"/>

The reason for the whole problem is actually totally simple. The faq2document.xsl stylesheet creates exactly one top-level section. Due to the various checks in the stylesheet the TOC is suppressed when min-sections is set to anything higher than 1. That's the work-around I'm currently working with in FOP, but I think this can be improved. Setting min-sections to 3 or 4 is a very nice feature, but sometimes (like in the FAQ example), this is not ideal, so I implemented a forcing mechanism, I will attach as a patch. Using the meta tag in the document header is probably not the best idea but this let me add this feature without the need for a change in the DTD. I'll leave it up to you guys, what to do with this. It's just a suggestion and I've only patched the pelt skin so far. If this is nuts, just close the bug. :-) Thanks!

[Ross Gardler]

What do Forrest devs think of this patch, I'm not sure about applying it because it appears to be a workaround not a solution.

What it does is add a meta-information value to a documents header:

<header>
      <title><xsl:value-of select="@title"/></title>
+ <meta name="forrest.force-toc">true</meta>
</header>

And then uses this to decide on whether or not to display a TOC:

- <xsl:if test="count(//tocitems/tocitem) >= $config/toc/@min-sections">
+ <xsl:if test="(count(//tocitems/tocitem) >= $config/toc/@min-sections) or (//tocitems/@force = 'true')">

I'm +0 on applying this on the grounds that it solves a users problem and that the core problem can be more completely resolved when the dispatcher is utilised.

[Tim Williams]

My vote is to leave it in JIRA as a workaround, change the Component to Dispatcher so that we remember to test Dispatcher for this issue.

I think there is no "issue" with respect to skins since forrest is doing exactly what we're telling it to do. It's an unfortunate limitation of skins that we can't do page-level skinning granularity. We do have that level of granularity with the Dispatcher's fallback mechanism though so it should be easily resolved there.

[Ross Gardler]

The community was split on whether to apply this or not. However, no compelling reason for not applying was given, the strongest argument against it is that it is a workaround and not a fix. However, since the problem will be fixed in Dispatcher and skins are likely to be deprecated it is unlikely that a Forrest dev will get around to fixing this.

I have therefore decided to apply the patch to make upgrading easier for the FOP project. This should remain an undocumented "feature" and its use should not be encouraged.