You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by je...@apache.org on 2003/09/01 14:41:37 UTC
cvs commit: xml-forrest/src/documentation/content/xdocs faq.xml
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 @@
</question>
<answer>
<p>
- This can be done by overriding the <code>filterlinks.xsl</code>
- stylesheet, and modifying it to filter out links that shouldn't be
- traversed.
+ This can be done by overriding the <code>cli.xconf</code> config file,
+ and defining patterns for URLs to exclude.
</p>
<p>
- This means creating a directory
- <code>src/documentation/resources/stylesheets</code> (or wherever
- <code>${forrest.stylesheets-dir}</code> points) and copying
- <code>$FORREST_HOME/context/resources/stylesheets/filterlinks.xsl</code>
- to it. Then edit filterlinks.xsl, and add extra conditions to the
- <code>xsl:if</code> statement:
+ This means creating a directory <code>src/documentation/conf</code>
+ (or wherever <code>${forrest.conf-dir}</code> points) and copying
+ <code>$FORREST_HOME/WEB-INF/cli.xconf</code> 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/':
</p>
- <source
- ><xsl:template match="@src|@href|@background">
- <xsl:if test="not(contains(.,'apidocs')) and not(starts-with(., 'api/'))">
- ...</source>
- <p>
- 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.
- </p>
- <p>
- 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 <code>$FORREST_HOME/context/sitemap.xmap</code> to
- <code>src/documentation/sitemap.xmap</code>, aka
- <code>${project.sitemap}</code>), and change line 394 from:
- </p>
- <source><map:transform src="library/xslt/filterlinks.xsl" /></source>
- <p>to:</p>
- <source><map:transform src="resources/stylesheets/filterlinks.xsl" /></source>
- <p>
- 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
- <code>index.html</code>, Cocoon will:
- </p>
- <ol>
- <li>render a page, say <code>index.html</code></li>
- <li>
- <p>
- request the 'links view' of that page, e.g.
- <code>index.html?cocoon-view=links</code>.
- </p>
- <p>
- The concept of 'views' is explained in <link href="ext:views">the
- Cocoon documentation</link>; 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:
- </p>
- <source><![CDATA[
- <map:view name="links" from-position="last">
- <map:transform
- src="resources/stylesheets/filterlinks.xsl"/>
- <map:serialize type="links"/>
- </map:view>]]>
- </source>
- <p>
- 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.
- </p>
- </li>
- <li>
- For each path mentioned in the link view, add it to a queue of pages
- to render, and recursively render each in order.
- </li>
- </ol>
+ <source><![CDATA[
+ ....
+ <!-- Includes and excludes can be used to limit which URLs are rendered -->
+ ]]><strong><![CDATA[
+ <exclude pattern="**apidocs**"/>
+ <exclude pattern="api/**"/>
+ ]]></strong><![CDATA[
+
+ <uri src="favicon.ico"/>
+</cocoon>]]></source>
+ <p>This is just an example, and you should modify it appropriately for
+ your site.</p>
+ <note>
+ Wildcards may be used. Wildcards work as in Cocoon's sitemap. <strong>foo/*</strong> would match
+ <code>foo/bar</code>, but not <code>foo/bar/baz</code> — use <strong>foo/**</strong> to match that.
+ </note>
</answer>
</faq>
<faq id="link_raw">
- <question>How do i link to raw files such as config.txt and
- brochure.pdf?
+ <question>How do I link to raw files such as config.txt and brochure.pdf?
</question>
<answer>
<p>
@@ -179,37 +135,95 @@
<li>Rebuild Forrest</li>
</ol>
<p>Alternative you can use JAI (Java Advanced Imaging API). For more
- info, see <link
- href="http://xml.apache.org/fop/graphics.html#packages">FOP Graphics
- Packages</link>
- </p>
+ info, see <link
+ href="http://xml.apache.org/fop/graphics.html#packages">FOP Graphics
+ Packages</link>
+ </p>
<note>Due to Sun's licensing, we cannot redistribute Jimi or JAI with
Forrest</note>
</answer>
</faq>
- <faq id="validation_error:doctype_root_null">
+
+ <faq id="index.html">
<question>
- When building my project, I get an validation error: <code>Document root
- element "site", must match DOCTYPE root "null".</code>.
+ The tab link in my site incorrectly assumes that 'index.html' is present in
+ the linked-to directory. How do I fix this?
</question>
<answer>
<p>
- 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 <code>tabs.xml</code>, 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 <code>manual/Introduction.html</code>,
+ <code>tabs.xml</code> should contain:
+ </p>
+ <source><![CDATA[
+ <tab label="User Manual" href="manual"/>
+ ]]></source>
+ <p>
+ and add this rule to the sitemap:
</p>
+ <source><![CDATA[
+ <map:match pattern="manual">
+ <map:redirect-to uri="manual/Introduction.html"/>
+ </map:match>
+ ]]></source>
+ </answer>
+ </faq>
+
+ <faq id="headless_operation">
+ <question>
+ 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.
+ </question>
+ <answer>
<p>
- Alternatively, you may be building with an up-to-date Forrest, but have
- overridden <code>forrest.validate.xdocs.excludes</code> in
- <code>forrest.properties</code>. 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 <em>headless</em>
+ operation by running Forrest with the <code>forrest.jvmarg</code>
+ parameter set to <code>-Djava.awt.headless=true</code>, like this:
</p>
+ <source>forrest -Dforrest.jvmargs=-Djava.awt.headless=true site</source>
</answer>
</faq>
+ <faq id="xsp">
+ <question>How do I enable <acronym title="eXtensible Server Pages">XSP</acronym> processing?</question>
+ <answer>
+ <p>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.</p>
+ <p>That said, there are valid reasons for wanting programmatically generated content, so here is how to enable
+ XSP:</p>
+ <ol>
+ <li>Download <link
+ href="http://cvs.apache.org/viewcvs.cgi/*checkout*/cocoon-2.1/lib/optional/jdtcore-2.1.0.jar?rev=1.1&content-type=application/java">jdtcore-2.1.0.jar</link>,
+ and copy it to the $FORREST_HOME/WEB-INF/lib directory (or lib/core/ directory in the source
+ distribution).</li>
+ <li><p>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:</p>
+ <source>
+ <map:generator name="serverpages" pool-grow="2"
+ pool-max="32" pool-min="4" src="org.apache.cocoon.generation.ServerPagesGenerator"/>
+ </source>
+ </li>
+ <li><p>Decide how you want to use XSP. For single files, you could just define a *.xml matcher:</p>
+ <source><![CDATA[
+<map:match pattern="dynamic.xml">
+ <map:generate src="content/xdocs/dynamic.xsp" type="serverpages"/>
+ ...
+ <map:serialize type="xml"/>
+</map:match>]]></source>
+ <p>You may instead wish to override forrest.xmap to define a general mapping for XSPs.</p>
+ </li>
+
+ </ol>
+ <p>See also the <link
+ href="http://wiki.cocoondev.org/Wiki.jsp?page=AddingXSPToForrest">AddingXSPToForrest</link> Wiki page.</p>
+ </answer>
+ </faq>
+
+ </part>
+
+ <part id="old_faqs">
+ <title>Older versions</title>
<faq id="unresolved_project.home">
<question>When invoking Forrest 0.4 from the
<code>forrest.antproxy.xml</code>, the build fails because
@@ -252,44 +266,25 @@
]]></source>
</answer>
</faq>
-
- <faq id="index.html">
+ <faq id="validation_error:doctype_root_null">
<question>
- 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: <code>Document root
+ element "site", must match DOCTYPE root "null".</code>.
</question>
<answer>
<p>
- In <code>tabs.xml</code>, 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 <code>manual/Introduction.html</code>,
- <code>tabs.xml</code> 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.
</p>
- <source><![CDATA[
- <tab label="User Manual" href="manual"/>
- ]]></source>
<p>
- and add this rule to the sitemap:
+ Alternatively, you may be building with an up-to-date Forrest, but have
+ overridden <code>forrest.validate.xdocs.excludes</code> in
+ <code>forrest.properties</code>. With the introduction of
+ &s;, the above property must have &s;
+ listed to prevent an attempt at DTD-based validation.
</p>
- <source><![CDATA[
- <map:match pattern="manual">
- <map:redirect-to uri="manual/Introduction.html"/>
- </map:match>
- ]]></source>
- </answer>
- </faq>
-
- <faq id="headless_operation">
- <question>
- 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.
- </question>
- <answer>
- <p>
- If you are using JDK 1.4.0 or newer, you can enable <em>headless</em>
- operation by running Forrest with the <code>forrest.jvmarg</code>
- parameter set to <code>-Djava.awt.headless=true</code>, like this:
- </p>
- <source>forrest -Dforrest.jvmargs=-Djava.awt.headless=true site</source>
</answer>
</faq>
@@ -315,31 +310,9 @@
</answer>
</faq>
- <faq id="site_xml_format">
- <question>What's with this awful site.xml format?</question>
- <answer>
- <p>
- The <link href="site:linking">site.xml</link> 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 <em>content</em> and <em>markup</em> has a few
- disadvantages (DTD validation is out), but nothing that outweighs the
- readability advantage.
- </p>
- <p>
- 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 <link
- href="http://www.topicmaps.org/xtm/1.0/">XTM (topic maps)</link>.
- Volunteers for implementing alternative formats are welcome.
- </p>
- </answer>
- </faq>
-
<faq id="docbook">
<question>
- How do i use DocBook as the xml documentation format?
+ How do I use DocBook as the xml documentation format?
</question>
<answer>
<p>
@@ -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.
- </p>
- </answer>
- </faq>
-
- <faq id="obsolete_docs">
- <question>
- Why am I a little confused by the Forrest documentation?
- </question>
- <answer>
- <p>
- 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
- <link href="site:your-project">Using Forrest</link> document.
</p>
</answer>
</faq>