Define TOC per page, generating TOC for the whole documentation [user-list forward]

[Armin Waibel <ar...@apache.org>]

Hi Ross,

much thanks for offer your help. Yes it's a production site
http://db.apache.org/ojb/index.html
thus we can't use the dev stuff in trunk.

I must admit that I never used Cocoon.
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

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

regards,
Armin

Ross Gardler wrote:
 > Armin Waibel wrote:
 >
 >> Hi,
 >>
 >> we using Forrest (great tool) version 0.7 and in skinconf.xml the TOC
 >> setting is
 >> <toc max-depth="4" min-sections="1" location="page"/>
 >> thus each document (all forrest .xml doc files + all automatically
 >> rendered .html files) will contain a TOC.
 >>
 >> 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>
 >
 >
 > Not in 0.7 out-of-the box. However, it would be relatively easy to
 > implment and we would be happy to help (via the dev list).
 >
 > It is also worth noting that we are working on a new skinning system
 > (currently moving from a prototype to a first implementation) that
 > enables this kind of granularity in page make-up. However, it is pure
 > dev stuff in trunk. If this is a production site and you don't want to
 > play with moving tartgets then adding this to the existing skins would
 > be a better approach for now.
 >
 >> 2. Is it possible to induce Forrest to generate an index of content
 >> for the whole web-site? I can't find such a topic in Forrest
 >> documentation. For bulky documentation it would be useful to provide
 >> such an IOC.
 >> E.g.
 >> <ioc max-depth="2" min-sections="1" target="guides/index.html">
 >>   <include name="guides/*" />
 >>   <exclude name="summary.html"/>
 >> </ioc>
 >
 >
 > Again, not out of the box, but relatively easy to add if you have the
 > inclination.
 >
 > See you on the dev list ;-)
 >
 > Ross
 >

Re: Define TOC per page, generating TOC for the whole documentation [user-list forward]

[Ross Gardler <rg...@apache.org>]

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