forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: Define TOC per page, generating TOC for the whole documentation [user-list forward]
Date Fri, 18 Nov 2005 00:49:07 GMT
Armin Waibel wrote:
> much thanks for offer your help. 

I was not offering my personal help, but that of the community as a 
whole. Of course, since I'm the one who opened my mouth I'll do my best 
to answer your questions, and guide you along the way. However, like all 
open source, this is your itch, you'll have to do the actual scratching ;-)

> Yes it's a production site
> http://db.apache.org/ojb/index.html
> thus we can't use the dev stuff in trunk.

OK.

> I must admit that I never used Cocoon.

All that is needed is some "simple" XML/XSL skills (simple for me 
because I know XML/XSL), I hope I've not scared you off yet.

> You can find all Forrest sources in CVS OJB_1_0_RELEASE branch:
> http://cvs.apache.org/viewcvs.cgi/db-ojb/src/doc/forrest/?only_with_tag=OJB_1_0_RELEASE


OK

> Now my question is what does "relatively easy to implement" stand for?

Lets tackle one issue at a time:

>  >> 1. Is it possible to suppress TOC generation for single document files?
>  >> E.g.
>  >> <toc max-depth="4" min-sections="1" location="page">
>  >>   <include name="**/*" />
>  >>   <exclude name="index.html"/>
>  >>   <exclude name="news.html"/>
>  >> </toc>

I'll walk you through starting at a snail pace, so you can start to find 
your way around the Forrest files.

Your site uses the tigris skin so all the files for you skin (in 0.7) 
are in:

http://svn.apache.org/repos/asf/forrest/branches/forrest_07_branch/main/webapp/skins/tigris/

We are particuarly interested in the XSL that creates the HTML at this 
stage:

http://svn.apache.org/repos/asf/forrest/branches/forrest_07_branch/main/webapp/skins/tigris/xslt/html/

And even more specific, the one that creates the TOC, which I happen to 
know is in document2html:

http://svn.apache.org/repos/asf/forrest/branches/forrest_07_branch/main/webapp/skins/tigris/xslt/html/document2html.xsl

However, a quick search in that file for "TOC" doesn't reveal anything. 
The reason being that your skin uses the common files for TOC 
generation, so we need to look at:

http://svn.apache.org/repos/asf/forrest/branches/forrest_07_branch/main/webapp/skins/common/xslt/html/document2html.xsl

Searching through this file we find something that looks promising:

<xsl:apply-templates mode="toc"/>

Which eventually leads us to:

<xsl:template match="body" mode="toc">
     <tocitems>
       <xsl:apply-templates select="section" mode="toc">
         <xsl:with-param name="level" select="1"/>
       </xsl:apply-templates>
     </tocitems>
   </xsl:template>

and

<xsl:template match="section" mode="toc">
     <xsl:param name="level"/>

     <tocitem level="{$level}">
       <xsl:attribute name="href">#<xsl:call-template 
name="generate-id"/></xsl:attribute>
       <xsl:attribute name="title"><xsl:value-of 
select="title"/></xsl:attribute>
       <xsl:apply-templates mode="toc">
         <xsl:with-param name="level" select="$level+1"/>
       </xsl:apply-templates>
     </tocitem>
   </xsl:template>

This last template is what you need. A couple of things to note. We 
create a <tocitem...> for every section in the document, there is no 
filtering for the current parameters, such as depth. This is done later 
in site2html.xsl which is responsible for rendering the final page and 
placing the TOC where it belongs:

Checking through the tigris skin files doesn't turn up anything likely, 
so we end up again in the common files:

http://svn.apache.org/repos/asf/forrest/branches/forrest_07_branch/main/webapp/skins/common/xslt/html/site2xhtml.xsl

Searching for toc in here we find (boy this is easy when you already 
know what you are looking for ;-):

<xsl:template match="div[@id='skinconf-toc-page']">
     <xsl:if test="$config/toc">
       <xsl:if test="contains($minitoc-location,'page')">
         <xsl:if test="count(//tocitems/tocitem) >= 
$config/toc/@min-sections">
           <xsl:call-template name="minitoc">
             <xsl:with-param name="tocroot" select="//tocitems"/>
           </xsl:call-template>
         </xsl:if>
       </xsl:if>
     </xsl:if>
   </xsl:template>

This looks like the place the toc items are placed in the page (note the 
<xsl:if test="contains($minitoc-location,'page')"> part).

It also looks like it filters out items too deep to be displayed 
(<xsl:if test="count(//tocitems/tocitem) >= $config/toc/@min-sections">)

So this is a likely candidate for a location to filter out your excludes 
list.

One approach would be the way we filter our Message of the Day entries 
in the pelt skin:

<xsl:for-each select="$config/motd/motd-option">
   <xsl:if test="contains($path, @pattern)">
     <xsl:text> (</xsl:text>
     <xsl:value-of select="motd-title"/>
     <xsl:text>)</xsl:text>
   </xsl:if>
</xsl:for-each>

I hope this lot helps you get started, if not others are listening and 
willing to help.

Note there is another location that the TOC entries are processed in the 
skin2html.xsl file. You should add you filtering to the other location 
as well or refactor the code so we only have one copy - I'm not sure why 
we have two, there may be a technical differenec, I've not looked.

We look forward to your patch ;-)

Ross

Mime
View raw message