forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Turner <je...@apache.org>
Subject Re: Linking to javadoc output from a Forrest site
Date Tue, 08 Apr 2003 13:57:22 GMT
On Tue, Apr 08, 2003 at 02:43:02PM +0200, Vincent Hardy wrote:
> Hello,
> 
> First, thanks to the developers of Forrest, it is a really cool tool. I 
> have been using it for an internal project and I found the flexibility 
> excellent.
> 
> There is one issue I have not been able to resolve, probably because of 
> my limited knowledge of Cocoon.
> 
> I am trying to add links to generated javadoc and I can't seem to find 
> the right way to do it. I see in:
> 
> http://xml.apache.org/forrest/linking.html
> 
> that there is some plans to add java: schemes, but what I am trying to 
> do is fairly simple: I want to link to a resource which is not generated 
> by Forrest such as some plain pre-existing html file that should not be 
> touched up (i.e., not ehtml like in the example) or a pre-existing image 
> which is not in the xdocs/images directory but at a URI that can be 
> defined relative to the xdocs directory.

Pregenerated content can be put directly in src/documentation/content/.
If you have src/documentation/content/mypage.html, you can link to it
with <link href="mypage.html">.  If you run 'forrest seed', there is an
example of this:

jeff@expresso:/tmp/testproj$ ls src/documentation/content/
hello.pdf  test1.html  test2.html  xdocs

However, for auto-generated files like Javadoc, this isn't a very nice
solution.  Then it's best to simply link to a nonexistent directory (say,
'api/'), and tell Forrest not to traverse that directory when rendering.

How to accomplish the latter differs for Forrest 0.4 and CVS Forrest.
For Forrest 0.4, the process is rather hacky:

http://marc.theaimsgroup.com/?l=forrest-dev&m=104605498612122&w=2

For CVS Forrest, it's somewhat less hacky.  You need to create an XSLT
file, ${project.stylesheets-dir}/filterlinks.xsl, containing:

<xsl:stylesheet
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  version="1.0">

  <xsl:template match="@src|@href|@background">

    <!-- Add other URLs to filter out here -->
    <xsl:if test="not(contains(.,'api/'))">
      <xsl:copy>
        <xsl:apply-templates select="."/>
      </xsl:copy>
    </xsl:if>
  </xsl:template>

  <xsl:template match="@*|node()">
    <xsl:copy>
      <xsl:apply-templates select="@*|node()"/>
    </xsl:copy>
  </xsl:template>

</xsl:stylesheet>

Btw, ${project.stylesheets-dir} is usually defined as
content/xdocs/resources/stylesheets, but if you're using the Maven
layout, you should edit forrest.properties and ensure the property is
correct for wherever you've placed it (src/xdocs/stylesheets perhaps).

That will filter out (preventing Forrest from traversing) links
containing 'api/'.  So <link href="api/com/myco/myproj/index.html"> won't
be touched by Forrest.  You can then edit your main build.xml to copy
Javadocs to build/site/api/, so the final product (website + javadocs)
all works.

We really ought to provide a nice frontend to all this.  I'll write up a
FAQ entry now describing what's going on..


--Jeff

> 
> Btw, I am using the Maven layout as described in the Getting started guide.
> 
> Thanks in advance for your help,
> Regards,
> Vincent Hardy.
> 

Mime
View raw message