Older versions

Return-Path: Delivered-To: apmail-xml-forrest-dev-archive@www.apache.org Received: (qmail 16277 invoked from network); 1 Sep 2003 12:41:40 -0000 Received: from daedalus.apache.org (HELO apache.org) (208.185.179.12) by minotaur-2.apache.org with SMTP; 1 Sep 2003 12:41:40 -0000 Received: (qmail 53460 invoked by uid 500); 1 Sep 2003 12:41:37 -0000 Delivered-To: apmail-xml-forrest-dev-archive@xml.apache.org Received: (qmail 53414 invoked by uid 500); 1 Sep 2003 12:41:37 -0000 Mailing-List: contact forrest-cvs-help@xml.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: list-post: Reply-To: forrest-dev@xml.apache.org Delivered-To: mailing list forrest-cvs@xml.apache.org Received: (qmail 53400 invoked from network); 1 Sep 2003 12:41:36 -0000 Received: from unknown (HELO minotaur.apache.org) (209.237.227.194) by daedalus.apache.org with SMTP; 1 Sep 2003 12:41:36 -0000 Received: (qmail 16232 invoked by uid 1352); 1 Sep 2003 12:41:37 -0000 Date: 1 Sep 2003 12:41:37 -0000 Message-ID: <20030901124137.16231.qmail@minotaur.apache.org> From: jefft@apache.org To: xml-forrest-cvs@apache.org Subject: cvs commit: xml-forrest/src/documentation/content/xdocs faq.xml X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N jefft 2003/09/01 05:41:37 Modified: src/documentation/content/xdocs faq.xml Log: - Move old FAQs to their own section - Update info on how to exclude URLs from CLI processing - Remove obsolete FAQs - Add "How to use XSP" FAQ Revision Changes Path 1.40 +112 -153 xml-forrest/src/documentation/content/xdocs/faq.xml Index: faq.xml =================================================================== RCS file: /home/cvs/xml-forrest/src/documentation/content/xdocs/faq.xml,v retrieving revision 1.39 retrieving revision 1.40 diff -u -r1.39 -r1.40 --- faq.xml 31 Aug 2003 05:59:50 -0000 1.39 +++ faq.xml 1 Sep 2003 12:41:37 -0000 1.40 @@ -53,82 +53,38 @@

- This can be done by overriding the filterlinks.xsl - stylesheet, and modifying it to filter out links that shouldn't be - traversed. + This can be done by overriding the cli.xconf config file, + and defining patterns for URLs to exclude.

- This means creating a directory - src/documentation/resources/stylesheets (or wherever - ${forrest.stylesheets-dir} points) and copying - $FORREST_HOME/context/resources/stylesheets/filterlinks.xsl - to it. Then edit filterlinks.xsl, and add extra conditions to the - xsl:if statement: + This means creating a directory src/documentation/conf + (or wherever ${forrest.conf-dir} points) and copying + $FORREST_HOME/WEB-INF/cli.xconf to it. Then edit + cli.xconf, and add any exclude sections you require at the end. The + default cli.xconf ignores links containing 'apidocs' or starting with + 'api/':

- <xsl:template match="@src|@href|@background"> - <xsl:if test="not(contains(.,'apidocs')) and not(starts-with(., 'api/'))"> - ... -

- This default XPath expression ignores links containing 'apidocs' or - starting with 'api/'. This is just an example, and you should modify - it appropriately for your site. -

- With the CVS version of Forrest, this is all that is required. - Forrest 0.4 needs one more change: a custom sitemap must be created - (copy $FORREST_HOME/context/sitemap.xmap to - src/documentation/sitemap.xmap, aka - ${project.sitemap}), and change line 394 from: -

- <map:transform src="library/xslt/filterlinks.xsl" /> -

to:

- <map:transform src="resources/stylesheets/filterlinks.xsl" /> -

- A bit of background may help explain all this. Cocoon generates a static - version of a website by 'crawling' through the pages—that is, - following links to determine what else to render. Starting with - index.html, Cocoon will: -

render a page, say index.html
-
- request the 'links view' of that page, e.g. - index.html?cocoon-view=links. -
-
- The concept of 'views' is explained in the - Cocoon documentation; briefly, Cocoon allows different - representations of a page, and these are called views. The links - view is a simple text listing of the page's embedded links. The - links view is specified in the Forrest sitemap with: -
- - - - ]]> - -
- The XSLT transformation just before the serializer gives us an - opportunity to filter out any links we don't want Cocoon to - process. As the link view is a separate pipeline, the normal page - output will be unaffected. -
-
- For each path mentioned in the link view, add it to a queue of pages - to render, and recursively render each in order. -

+ + ]]> + + ]]> +]]> +

This is just an example, and you should modify it appropriately for + your site.

+ + Wildcards may be used. Wildcards work as in Cocoon's sitemap. foo/* would match + foo/bar, but not foo/bar/baz — use foo/** to match that. + - How do i link to raw files such as config.txt and - brochure.pdf? + How do I link to raw files such as config.txt and brochure.pdf?

@@ -179,37 +135,95 @@

Rebuild Forrest

Alternative you can use JAI (Java Advanced Imaging API). For more - info, see FOP Graphics - Packages -

+ info, see FOP Graphics + Packages +

Due to Sun's licensing, we cannot redistribute Jimi or JAI with Forrest - + + - When building my project, I get an validation error:

Document root
  -          element "site", must match DOCTYPE root "null".

. + The tab link in my site incorrectly assumes that 'index.html' is present in + the linked-to directory. How do I fix this?

- You are probably trying to build the project with an old version of - Forrest (built before 2003-01-08) that is incorrectly trying to validate - the &s; file. If so, please update your Forrest - installation. + In tabs.xml, use @href instead of @dir, and omit the trailing + '/'. That will leave which file to serve up to the sitemap. For example, if + the 'User Manual' tab should link to manual/Introduction.html, + tabs.xml should contain: +

+ + ]]> +

+ and add this rule to the sitemap:

+ + + + ]]> + + + + + + When generating PNG images from SVG, I get an error: Can't connect to X11 window server using ':0.0' as the value of the DISPLAY variable. + +

- Alternatively, you may be building with an up-to-date Forrest, but have - overridden forrest.validate.xdocs.excludes in - forrest.properties. With the introduction of - &s;, the above property must have &s; - listed to prevent an attempt at DTD-based validation. + If you are using JDK 1.4.0 or newer, you can enable headless + operation by running Forrest with the forrest.jvmarg + parameter set to -Djava.awt.headless=true, like this:

+ forrest -Dforrest.jvmargs=-Djava.awt.headless=true site + + How do I enable XSP processing? + +

First consider whether your needs would be better met by Cocoon itself, rather than Forrest. Forrest was + designed primarily with static sites in mind, and is not a general-purpose Cocoon distribution.

That said, there are valid reasons for wanting programmatically generated content, so here is how to enable + XSP:

Download jdtcore-2.1.0.jar, + and copy it to the $FORREST_HOME/WEB-INF/lib directory (or lib/core/ directory in the source + distribution).
Override sitemap.xmap in your local project (copy $FORREST_HOME/context/sitemap.xmap to + src/documentation/conf/), and add the following generator definition in the map:generators section:
+ + <map:generator name="serverpages" pool-grow="2" + pool-max="32" pool-min="4" src="org.apache.cocoon.generation.ServerPagesGenerator"/> + +
Decide how you want to use XSP. For single files, you could just define a *.xml matcher:
+ + + ... + +]]> +
You may instead wish to override forrest.xmap to define a general mapping for XSPs.
+

See also the AddingXSPToForrest Wiki page.

+ + + + + + + Older versions When invoking Forrest 0.4 from the forrest.antproxy.xml, the build fails because @@ -252,44 +266,25 @@ ]]> - - + - The tab link in my site incorrectly assumes that 'index.html' is present in - the linked-to directory. How do I fix this? + When building my project, I get an validation error:

Document root
  +          element "site", must match DOCTYPE root "null".

- In tabs.xml, use @href instead of @dir, and omit the trailing - '/'. That will leave which file to serve up to the sitemap. For example, if - the 'User Manual' tab should link to manual/Introduction.html, - tabs.xml should contain: + You are probably trying to build the project with an old version of + Forrest (built before 2003-01-08) that is incorrectly trying to validate + the &s; file. If so, please update your Forrest + installation.

- - ]]>

- and add this rule to the sitemap: + Alternatively, you may be building with an up-to-date Forrest, but have + overridden forrest.validate.xdocs.excludes in + forrest.properties. With the introduction of + &s;, the above property must have &s; + listed to prevent an attempt at DTD-based validation.

- - - - ]]> - - - - - - When generating PNG images from SVG, I get an error: Can't connect to X11 window server using ':0.0' as the value of the DISPLAY variable. - - -

- If you are using JDK 1.4.0 or newer, you can enable headless - operation by running Forrest with the forrest.jvmarg - parameter set to -Djava.awt.headless=true, like this: -

- forrest -Dforrest.jvmargs=-Djava.awt.headless=true site @@ -315,31 +310,9 @@ - - What's with this awful site.xml format? - -

- The site.xml format was designed for - humans, not computers. The goals were for &s; to be exceedingly - simple, compact, easy to type and easy to read. The reuse of element - names as ids means that &s; has very few wasted characters. This odd - merging of content and markup has a few - disadvantages (DTD validation is out), but nothing that outweighs the - readability advantage. -

- That said, pretty much any XML format may be used, simply by tweaking - the XPath template in the sitemap. In the future, &s; may be replaced - with some more standardized format, perhaps RDF or XTM (topic maps). - Volunteers for implementing alternative formats are welcome. -

- - - - How do i use DocBook as the xml documentation format? + How do I use DocBook as the xml documentation format?

@@ -372,20 +345,6 @@ You can also use a mixture of the two methods, some handled automatically by Forrest and some directly using DocBook stylesheets. You can also have a mixture of "document-v*" DTD and DocBook. -

- - - - - - Why am I a little confused by the Forrest documentation? - - -

- Sorry, we are working on that for the next release. Forrest development has - been very fast recently. Some of the documentation refers to old methods. - Your best bet is to start with the - Using Forrest document.