You are viewing a plain text version of this content. The canonical link for it is here.
Posted to site-svn@forrest.apache.org by cr...@apache.org on 2007/04/18 10:36:26 UTC
svn commit: r529915 [5/20] - in /forrest/site: ./ docs_0_70/
docs_0_70/howto/ docs_0_70/howto/cvs-ssh/ docs_0_70/howto/multi/ docs_0_80/
docs_0_80/howto/ docs_0_80/howto/cvs-ssh/ docs_0_80/howto/multi/ dtdx/
plan/ pluginDocs/ pluginDocs/plugins_0_70/ p...
Modified: forrest/site/docs_0_70/faq.html
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_70/faq.html?view=diff&rev=529915&r1=529914&r2=529915
==============================================================================
--- forrest/site/docs_0_70/faq.html (original)
+++ forrest/site/docs_0_70/faq.html Wed Apr 18 01:36:14 2007
@@ -3,7 +3,7 @@
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta content="Apache Forrest" name="Generator">
-<meta name="Forrest-version" content="0.8-dev">
+<meta name="Forrest-version" content="0.9-dev">
<meta name="Forrest-skin-name" content="pelt">
<title>Frequently Asked Questions (v0.7)</title>
<link type="text/css" href="../skin/basic.css" rel="stylesheet">
@@ -87,7 +87,7 @@
|start Subtabs
+-->
<div id="level2tabs">
-<a class="selected" href="../docs_0_70/index.html">0.70 (current)</a><a class="unselected" href="../docs_0_80/index.html">0.80-dev (under development)</a><a class="unselected" href="../docs_0_60/index.html">0.60 (past)</a>
+<a class="unselected" href="../docs_0_80/index.html">0.80 (current)</a><a class="unselected" href="../docs_0_90/index.html">0.90-dev (under development)</a><a class="selected" href="../docs_0_70/index.html">0.70 (past)</a>
</div>
<!--+
|end Endtabs
@@ -100,7 +100,7 @@
|breadtrail
+-->
<div class="breadtrail">
-
+
</div>
<!--+
@@ -283,7 +283,7 @@
</div>
<div id="credit">
<hr>
- This is documentation for current version v0.7
+ This is documentation for past version v0.7
(<a href="http://forrest.apache.org/versions/">More</a>)</div>
<div id="roundbottom">
<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
@@ -312,7 +312,7 @@
</div>
<h1>Frequently Asked Questions</h1>
<div id="motd-area">
- This is documentation for current version v0.7
+ This is documentation for past version v0.7
(<a href="http://forrest.apache.org/versions/">More</a>)</div>
<div id="minitoc-area">
<ul class="minitoc">
@@ -515,8 +515,8 @@
</div>
<div style="margin-left: 15px">
<p>
- There is no particular order to these FAQs. Use your browser's
- "Find in this page" facility to search for keywords.
+ There is no particular order to these FAQs. Use your browser's "Find
+ in this page" facility to search for keywords.
</p>
</div>
<a name="N10018"></a><a name="overview"></a>
@@ -525,7 +525,10 @@
<a href="#overview-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p> See the <a href="../docs_0_70/your-project.html">Using Forrest</a> guide. </p>
+<p>
+ See the <a href="../docs_0_70/your-project.html">Using Forrest</a>
+ guide.
+ </p>
</div>
<a name="N10024"></a><a name="requirements"></a>
<h4 class="faq">1.3. What are the system requirements for Forrest? </h4>
@@ -533,14 +536,16 @@
<a href="#requirements-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p> Forrest includes everything necessary to build and run, except of course for Java. In
- addition to all the Cocoon JARs, Forrest includes and uses its own version of Apache Ant.
+<p>
+ Forrest includes everything necessary to build and run, except of
+ course for Java. In addition to all the Cocoon JARs, Forrest includes
+ and uses its own version of Apache Ant.
</p>
<p>
Java 1.4 (or newer) is required. If you are only going to use Forrest
- as-is then you need only the Java Runtime Environment (JRE).
- If you intend to enhance and rebuild Forrest (or use the Forrest sources
- with Subversion or use a source snapshot) then you need the full JDK.
+ as-is then you need only the Java Runtime Environment (JRE). If you
+ intend to enhance and rebuild Forrest (or use the Forrest sources with
+ Subversion or use a source snapshot) then you need the full JDK.
</p>
</div>
<a name="N1002F"></a><a name="cvs"></a>
@@ -549,8 +554,10 @@
<a href="#cvs-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p> Forrest switched from a CVS code repository to SVN (Subversion) code repository. The old
- CVS repository is closed and not kept current. </p>
+<p>
+ Forrest switched from a CVS code repository to SVN (Subversion) code
+ repository. The old CVS repository is closed and not kept current.
+ </p>
</div>
<a name="N10037"></a><a name="svn"></a>
<h4 class="faq">1.5. How can I use SVN to keep up to date with the latest codebase? </h4>
@@ -558,9 +565,15 @@
<a href="#svn-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p> Follow these <a href="../docs_0_70/build.html">Building Forrest</a> notes. </p>
-<p> The <a href="../docs_0_70/your-project.html">Using Forrest</a> guide provides further
- step-by-step assistance in getting started with Forrest for your project. </p>
+<p>
+ Follow these <a href="../docs_0_70/build.html">Building Forrest</a>
+ notes.
+ </p>
+<p>
+ The <a href="../docs_0_70/your-project.html">Using Forrest</a> guide
+ provides further step-by-step assistance in getting started with
+ Forrest for your project.
+ </p>
</div>
<a name="N1004A"></a><a name="older-plugins"></a>
<h4 class="faq">1.6. How to use older versions of specific plugins? </h4>
@@ -569,14 +582,14 @@
</div>
<div style="margin-left: 15px">
<p>
- Sometimes one does not want to use the most recent functionality
- of a plugin and instead need to use an older version.
- Information about changes to each plugin can be found in its
+ Sometimes one does not want to use the most recent functionality of a
+ plugin and instead need to use an older version. Information about
+ changes to each plugin can be found in its
<a href="../pluginDocs/plugins_0_70/index.html">documentation</a>.
</p>
<p>
- In the forrest.properties file, specify the version of the plugin
- that you require, e.g.
+ In the forrest.properties file, specify the version of the plugin that
+ you require, e.g.
</p>
<pre class="code">project.required.plugins=org.apache.forrest.plugin.input.PhotoGallery-0.1,...</pre>
<p>
@@ -598,9 +611,14 @@
<a href="#single-document-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p> forrest site -Dproject.start-uri=myfile.pdf </p>
-<p> The <a href="../docs_0_70/your-project.html">Using Forrest</a> guide provides further
- step-by-step assistance in getting started with Forrest for your project. </p>
+<p>
+ forrest site -Dproject.start-uri=myfile.pdf
+ </p>
+<p>
+ The <a href="../docs_0_70/your-project.html">Using Forrest</a> guide
+ provides further step-by-step assistance in getting started with
+ Forrest for your project.
+ </p>
</div>
<a name="N1007A"></a><a name="cygwin_mutex_error"></a>
<h4 class="faq">1.8. When running ./build.sh in cygwin, I get an error: cygpath.exe:
@@ -609,8 +627,11 @@
<a href="#cygwin_mutex_error-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p> This <a href="http://issues.apache.org/jira/secure/ViewIssue.jspa?key=FOR-10">appears
- to be a bug in cygwin</a>. Please use the .bat script instead. </p>
+<p>
+ This
+ <a href="http://issues.apache.org/jira/secure/ViewIssue.jspa?key=FOR-10">appears
+ to be a bug in cygwin</a>. Please use the .bat script instead.
+ </p>
</div>
<a name="N1008C"></a><a name="maxmemory"></a>
<h4 class="faq">1.9. How can I specify the amount of memory to be used by Java? </h4>
@@ -618,17 +639,24 @@
<a href="#maxmemory-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p> There are two ways to control this. If you get an OutOfMemoryError when Cocoon is
- generating pages, see the first paragraph. If you get an OutOfMemoryError when outside of
- Cocoon (e.g., copying raw files), see the second paragraph. </p>
-<p> The <span class="codefrag">maxmemory</span> property in the <span class="codefrag">forrest.properties</span> file controls
- how much memory Cocoon uses. Like many other properties you can copy them from the default
+<p>
+ There are two ways to control this. If you get an OutOfMemoryError
+ when Cocoon is generating pages, see the first paragraph. If you get
+ an OutOfMemoryError when outside of Cocoon (e.g., copying raw files),
+ see the second paragraph.
+ </p>
+<p>
+ The <span class="codefrag">maxmemory</span> property in the
+ <span class="codefrag">forrest.properties</span> file controls how much memory Cocoon
+ uses. Like many other properties you can copy them from the default
configuration at <span class="codefrag">src/core/fresh-site/forrest.properties</span>
</p>
-<p> Set the <span class="codefrag">ANT_OPTS</span> environment variable before you run forrest. The exact
- value you set it to is dependant on your JVM, but something like
- <span class="codefrag">ANT_OPTS=-Xmx500M</span> will probably work. </p>
+<p>
+ Set the <span class="codefrag">ANT_OPTS</span> environment variable before you run
+ forrest. The exact value you set it to is dependant on your JVM, but
+ something like <span class="codefrag">ANT_OPTS=-Xmx500M</span> will probably work.
+ </p>
</div>
<a name="N100A9"></a><a name="content_faqs"></a>
<h3 class="underlined_5">2. Content Creation</h3>
@@ -638,15 +666,26 @@
<a href="#edit-content-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p>If you are using the Apache Forrest xml <a href="../docs_0_70/../dtdx/dtd-docs.html">document format</a>
- or DocBook or other xml document types, then you can use any text editor or even a
- dedicated xml editor. You must ensure valid xml. See our <a href="../docs_0_70/catalog.html">configuration notes</a> for various editors. </p>
-<p>There are content management systems like <a href="http://lenya.apache.org/">Apache Lenya</a>. </p>
-<p>Remember that Forrest can also use other source formats, such as OpenOffice.org docs or
- JSPWiki. Use the appropriate editor for those document types and ensure that the document
- stucture is consistent. Forrest can also use "html" as the source format, in which case
- you can use text editors or "html editors" such as the one provided with the Mozilla web
- browser. </p>
+<p>
+ If you are using the Apache Forrest xml
+ <a href="../docs_0_70/../dtdx/dtd-docs.html">document format</a> or DocBook or
+ other xml document types, then you can use any text editor or even a
+ dedicated xml editor. You must ensure valid xml. See our
+ <a href="../docs_0_70/catalog.html">configuration
+ notes</a> for various editors.
+ </p>
+<p>
+ There are content management systems like
+ <a href="http://lenya.apache.org/">Apache Lenya</a>.
+ </p>
+<p>
+ Remember that Forrest can also use other source formats, such as
+ OpenOffice.org docs or JSPWiki. Use the appropriate editor for those
+ document types and ensure that the document stucture is consistent.
+ Forrest can also use "html" as the source format, in which case you
+ can use text editors or "html editors" such as the one provided with
+ the Mozilla web browser.
+ </p>
</div>
<a name="N100C7"></a><a name="site-xml"></a>
<h4 class="faq">2.2.
@@ -657,22 +696,24 @@
</div>
<div style="margin-left: 15px">
<p>
- The <span class="codefrag">site.xml</span> configuration file is used for two different purposes:
- defining the left-hand navigation menus, and as a method for defining references
- to be used when linking between documents.
- This file is fully explained in
- <a href="../docs_0_70/linking.html">Menus and Linking</a>. Here is a precis:
+ The <span class="codefrag">site.xml</span> configuration file is used for two different
+ purposes: defining the left-hand navigation menus, and as a method for
+ defining references to be used when linking between documents. This
+ file is fully explained in <a href="../docs_0_70/linking.html">Menus and
+ Linking</a>. Here is a precis:
</p>
<p>
The labels can be whatever text you want.
</p>
-<pre class="code"><faq label="FAQs" href="faq.html">
+<pre class="code">
+<faq label="FAQs" href="faq.html">
<tech label="Technical" href="faq-tech.html">
<docbook href="#docbook"/>
<ignoring_javadocs href="#ignoring_javadocs"/>
</tech>
<user label="User" href="faq-user.html">
-</faq></pre>
+</faq>
+ </pre>
<p>
That will create a menu like this with three links:
</p>
@@ -682,13 +723,17 @@
<p>
These documents can be linked to from other documents, like this:
</p>
-<pre class="code"><a href="site:v0.70//faq/tech"> link to the top of the Tech FAQs
-<a href="site:v0.70//faq/tech/docbook"> link to the DocBook FAQ in the Tech FAQs</pre>
+<pre class="code">
+<a href="site:v0.70//faq/tech"> link to the top of the Tech FAQs
+<a href="site:v0.70//faq/tech/docbook"> link to the DocBook FAQ in the Tech FAQs
+ </pre>
<p>
If that "docbook" entry was a unique name in your site.xml then you
can shorten that latter link:
</p>
-<pre class="code"><a href="site:v0.70//docbook"> link to the DocBook FAQ in the Tech FAQs</pre>
+<pre class="code">
+<a href="site:v0.70//docbook"> link to the DocBook FAQ in the Tech FAQs
+ </pre>
</div>
<a name="N100F5"></a><a name="examples"></a>
<h4 class="faq">2.3.
@@ -699,8 +744,9 @@
</div>
<div style="margin-left: 15px">
<p>
- There are examples in the 'forrest seed site' and also the Forrest website documents
- are included with the distribution (cd forrest/site-author; forrest run).
+ There are examples in the 'forrest seed site' and also the Forrest
+ website documents are included with the distribution (cd
+ forrest/site-author; forrest run).
</p>
</div>
<a name="N100FD"></a><a name="PDF-output"></a>
@@ -709,19 +755,29 @@
<a href="#PDF-output-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p>Add the following entries to your site.xml file:</p>
+<p>
+ Add the following entries to your site.xml file:
+ </p>
<pre class="code">
+
<about tab="home" label="About" href="">
...
<all_site label="Full HTML" href="wholesite.html"/>
<all_sitePDF label="Full PDF" href="wholesite.pdf"/>
...
- </about></pre>
-<p> In this case the menu labeled "About" will have 2 new items: "Full PDF" and "Full HTML".
- (See also <a href="../docs_0_70/howto/howto-pdf-tab.html">How to create a PDF document for each
- tab</a>.) </p>
-<p> This assumes that you use the <a href="../docs_0_70/linking.html">site.xml</a> method for your
- site structure and navigation, rather than the old book.xml method. </p>
+ </about>
+ </pre>
+<p>
+ In this case the menu labeled "About" will have 2 new items: "Full
+ PDF" and "Full HTML". (See also
+ <a href="../docs_0_70/howto/howto-pdf-tab.html">How to create a PDF document
+ for each tab</a>.)
+ </p>
+<p>
+ This assumes that you use the
+ <a href="../docs_0_70/linking.html">site.xml</a> method for your site
+ structure and navigation, rather than the old book.xml method.
+ </p>
</div>
<a name="N10117"></a><a name="pageBreaks"></a>
<h4 class="faq">2.5. How do I insert page breaks into documents?</h4>
@@ -729,16 +785,22 @@
<a href="#pageBreaks-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p>Page breaks do not make a great deal of sense in HTML documents intended for display on a
- screen. However, PDF documents are intended for printing and therefore page breaks can be
- important.</p>
-<p>To insert a page break in a PDF document simply add <em>pageBreakBefore</em> and/or
- <em>pageBreakAfter</em> to the class attribute of the block you wish to force a
- page break on. All the common block grouping elements support this class, for example,
- note, warning, p and so on.</p>
-<p>If you want these classes to be processed in your HTML documents as well you should add
- the following to the <span class="codefrag">extra-css</span> element in your projects
- <span class="codefrag">skinconf.xml</span>
+<p>
+ Page breaks do not make a great deal of sense in HTML documents
+ intended for display on a screen. However, PDF documents are intended
+ for printing and therefore page breaks can be important.
+ </p>
+<p>
+ To insert a page break in a PDF document simply add
+ <em>pageBreakBefore</em> and/or <em>pageBreakAfter</em> to the class
+ attribute of the block you wish to force a page break on. All the
+ common block grouping elements support this class, for example, note,
+ warning, p and so on.
+ </p>
+<p>
+ If you want these classes to be processed in your HTML documents as
+ well you should add the following to the <span class="codefrag">extra-css</span>
+ element in your projects <span class="codefrag">skinconf.xml</span>
</p>
<pre class="code"> .pageBreakBefore { margin-bottom: 0; page-break-before: always; } .pageBreakAfter {
@@ -751,9 +813,11 @@
<a href="#clickable-email-address-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p>You would override <span class="codefrag">
- $FORREST_HOME/main/webapp/skins/common/xslt/html/document2html.xsl</span> and edit the
- "headers/authors" template. </p>
+<p>
+ You would override <span class="codefrag">
+ $FORREST_HOME/main/webapp/skins/common/xslt/html/document2html.xsl</span>
+ and edit the "headers/authors" template.
+ </p>
</div>
<a name="N10140"></a><a name="link_raw"></a>
<h4 class="faq">2.7. How do I link to raw files such as config.txt and brochure.pdf? </h4>
@@ -761,9 +825,11 @@
<a href="#link_raw-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p>Handling of raw files was significantly changed in Forrest 0.7. See
- <a href="../docs_0_70/upgrading_07.html#raw">Upgrading to Apache Forrest 0.7</a> for
- all the details.</p>
+<p>
+ Handling of raw files was significantly changed in Forrest 0.7. See
+ <a href="../docs_0_70/upgrading_07.html#raw">Upgrading to Apache Forrest
+ 0.7</a> for all the details.
+ </p>
</div>
<a name="N1014C"></a><a name="pdf_images"></a>
<h4 class="faq">2.8. Images don't display in PDFs. How do I fix this?</h4>
@@ -771,52 +837,72 @@
<a href="#pdf_images-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p> Forrest uses <a href="http://xml.apache.org/fop/">Apache FOP</a> for rendering
- PDFs. FOP cannot handle all image types natively, and requires third-party jars to be
- added. FOP natively handles BMP, GIF, JPG, TIFF and EPS (with a few limitations). FOP can
- also handle SVG (via Batik!and PNG (see below). For details, see <a href="http://xml.apache.org/fop/graphics.html">FOP Graphics formats</a>
+<p>
+ Forrest uses <a href="http://xml.apache.org/fop/">Apache FOP</a>
+ for rendering PDFs. FOP cannot handle all image types natively, and
+ requires third-party jars to be added. FOP natively handles BMP, GIF,
+ JPG, TIFF and EPS (with a few limitations). FOP can also handle SVG
+ (via Batik!and PNG (see below). For details, see
+ <a href="http://xml.apache.org/fop/graphics.html">FOP
+ Graphics formats</a>
</p>
-<p>To get PNGs working in PDFs with Jimi:</p>
+<p>
+ To get PNGs working in PDFs with Jimi:
+ </p>
<ol>
<li>Download Jimi from <a href="http://java.sun.com/products/jimi/">http://java.sun.com/products/jimi/</a>
-
</li>
<li>Unpack the Jimi distribution and copy JimiProClasses.zip to
<span class="codefrag">$FORREST/lib/optional/jimi-1.0.jar</span>.</li>
</ol>
-<p>Alternatively you can use JAI (Java Advanced Imaging API at
- http://java.sun.com/products/java-media/jai). For more info, see <a href="http://xml.apache.org/fop/graphics.html#packages">FOP Graphics Packages</a>
+<p>
+ Alternatively you can use JAI (Java Advanced Imaging API at
+ http://java.sun.com/products/java-media/jai). For more info, see
+ <a href="http://xml.apache.org/fop/graphics.html#packages">FOP
+ Graphics Packages</a>
</p>
<div class="note">
<div class="label">Note</div>
-<div class="content">Due to Sun's licensing, we cannot redistribute Jimi or JAI with Forrest.</div>
+<div class="content">
+ Due to Sun's licensing, we cannot redistribute Jimi or JAI with
+ Forrest.
+ </div>
</div>
</div>
-<a name="N10179"></a><a name="tab-index"></a>
+<a name="N10178"></a><a name="tab-index"></a>
<h4 class="faq">2.9. The tab link in my site incorrectly assumes that 'index.html' is present in the
linked-to directory. How do I fix this? </h4>
<div align="right">
<a href="#tab-index-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p> In <span class="codefrag">tabs.xml</span>, use @href instead of @dir, and omit the trailing '/'. Which
- file to serve is then a concern of the sitemap. For example, if the "User Manual" tab
- should link to <span class="codefrag">manual/Introduction.html</span> then <span class="codefrag">tabs.xml</span> should
- contain: </p>
+<p>
+ In <span class="codefrag">tabs.xml</span>, use @href instead of @dir, and omit the
+ trailing '/'. Which file to serve is then a concern of the sitemap.
+ For example, if the "User Manual" tab should link to
+ <span class="codefrag">manual/Introduction.html</span> then <span class="codefrag">tabs.xml</span>
+ should contain:
+ </p>
<pre class="code">
- <tab label="User Manual" href="manual"/></pre>
-<p> and add this rule to the sitemap: </p>
+
+ <tab label="User Manual" href="manual"/>
+ </pre>
+<p>
+ and add this rule to the sitemap:
+ </p>
<pre class="code">
+
<map:match pattern="manual">
<map:redirect-to uri="manual/Introduction.html"/>
- </map:match></pre>
+ </map:match>
+ </pre>
</div>
-<a name="N10195"></a><a name="tab-site"></a>
+<a name="N10194"></a><a name="tab-site"></a>
<h4 class="faq">2.10. I need help with the interaction between tabs.xml and site.xml </h4>
<div align="right">
<a href="#tab-site-menu">^</a>
@@ -826,15 +912,17 @@
See the <a href="../docs_0_70/linking.html#tab-site">tips</a>.
</p>
</div>
-<a name="N101A1"></a><a name="defaultFileName"></a>
+<a name="N101A0"></a><a name="defaultFileName"></a>
<h4 class="faq">2.11. How can I change the default file name that Forrest will look for when I request a
URL like http://myserver or http://myserver/mydir/ ? </h4>
<div align="right">
<a href="#defaultFileName-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p>To change the default file name from 'index.html' (default) to 'overview.html' you need to
- make the following changes:</p>
+<p>
+ To change the default file name from 'index.html' (default) to
+ 'overview.html' you need to make the following changes:
+ </p>
<ol>
<li> Create a '<a href="#cli-xconf">cli.xconf</a>' file for your project </li>
@@ -846,39 +934,51 @@
<li> Edit your project's <a href="../docs_0_70/project-sitemap.html">sitemap.xmap</a> file. </li>
<li> Add the following code just before the end of the pipelines-element:<pre class="code">
+
<map:pipeline>
<map:match type="regexp" pattern="^.+/$">
<map:redirect-to uri="overview.html"/>
</map:match>
</map:pipeline>
- </pre>
+
+ </pre>
</li>
</ol>
</div>
-<a name="N101C9"></a><a name="defaultStartPage"></a>
+<a name="N101C8"></a><a name="defaultStartPage"></a>
<h4 class="faq">2.12. How can I use a start-up-page other than index.html? </h4>
<div align="right">
<a href="#defaultStartPage-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p>Forrest by default assumes that the first page (home page) of your site is named
- index.html. Which is good because most web servers are configured to look for index.html
- when you call a url like http://myserver</p>
-<p>Like most settings in Forrest however this can be changed, for example when you want your
- start-up-page for a CD-based documentation project to be named 'start.html'. </p>
-<p>To change the start page of a site:</p>
+<p>
+ Forrest by default assumes that the first page (home page) of your
+ site is named index.html. Which is good because most web servers are
+ configured to look for index.html when you call a url like
+ http://myserver
+ </p>
+<p>
+ Like most settings in Forrest however this can be changed, for example
+ when you want your start-up-page for a CD-based documentation project
+ to be named 'start.html'.
+ </p>
+<p>
+ To change the start page of a site:
+ </p>
<ol>
<li>Edit your project's <a href="../docs_0_70/project-sitemap.html">sitemap.xmap</a> file.</li>
<li>Add the following code just before the end of the pipelines-element:<pre class="code">
+
<map:pipeline>
<map:match pattern="">
<map:redirect-to uri="start.html" />
</map:match>
</map:pipeline>
- </pre>
+
+ </pre>
</li>
<li>Name the uri-attribute whatever you'd like your start page to be.</li>
@@ -887,25 +987,38 @@
</ol>
</div>
-<a name="N101ED"></a><a name="label-entity"></a>
+<a name="N101EC"></a><a name="label-entity"></a>
<h4 class="faq">2.13. How to use special characters in the labels of the site.xml file? </h4>
<div align="right">
<a href="#label-entity-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p> Use the numeric values for character entities. For example, rather than using
- <span class="codefrag">&ouml;</span> use <span class="codefrag">&#246;</span>
+<p>
+ Use the numeric values for character entities. For example, rather
+ than using <span class="codefrag">
+&ouml;
+ </span> use <span class="codefrag">
+&#246;
+ </span>
</p>
-<p> See the <a href="http://www.w3.org/TR/xhtml-modularization/dtd_module_defs.html#a_xhtml_character_entities">XHTML Character Entities</a> and see more discussion at <a href="http://issues.apache.org/jira/browse/FOR-244">Issue FOR-244</a>. </p>
+<p>
+ See the
+ <a href="http://www.w3.org/TR/xhtml-modularization/dtd_module_defs.html#a_xhtml_character_entities">XHTML
+ Character Entities</a> and see more discussion at
+ <a href="http://issues.apache.org/jira/browse/FOR-244">Issue
+ FOR-244</a>.
+ </p>
</div>
-<a name="N10206"></a><a name="encoding"></a>
+<a name="N10205"></a><a name="encoding"></a>
<h4 class="faq">2.14. Does Forrest handle accents for non-English languages?</h4>
<div align="right">
<a href="#encoding-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p>Yes, Forrest can process text in any language, so you can include:</p>
+<p>
+ Yes, Forrest can process text in any language, so you can include:
+ </p>
<ul>
<li>accents: á é í ó ú</li>
@@ -915,38 +1028,68 @@
<li>tildes: ã ñ Ä© õ Å©</li>
</ul>
-<p>This is because sources for Forrest docs are xml documents, which can include any of
- these, provided the encoding declared by the xml doc matches the actual encoding used in
- the file. For example if you declare the default encoding:</p>
-<pre class="code"><?xml version="1.0" encoding="UTF-8"?></pre>
-<p>but the file content is actually using ISO-8859-1 then you will receive validation
- errors, especially if you include some non-ASCII characters.</p>
-<p> This situation is commonly encountered when you edit the templates created by
- <span class="codefrag">forrest seed</span> with your favorite (probably localized) editor without paying
- attention to the encoding, or when you create a new file and simply copy the headers from
- another file. </p>
-<p>Although UTF-8 is an encoding well-suited for most languages, it is not usually the
- default in popular editors or systems. In UNIX-like systems, most popular editors can
- handle different encodings to write the file in disk. With some editors the encoding of
- the file is preserved, while with others the default is used regardless of the original
- encoding. In most cases the encoding used to write files can be controlled by setting the
- environment variable <span class="codefrag">LANG</span> to an appropriate value, for instance: </p>
+<p>
+ This is because sources for Forrest docs are xml documents, which can
+ include any of these, provided the encoding declared by the xml doc
+ matches the actual encoding used in the file. For example if you
+ declare the default encoding:
+ </p>
+<pre class="code">
+<?xml version="1.0" encoding="UTF-8"?>
+ </pre>
+<p>
+ but the file content is actually using ISO-8859-1 then you will
+ receive validation errors, especially if you include some non-ASCII
+ characters.
+ </p>
+<p>
+ This situation is commonly encountered when you edit the templates
+ created by <span class="codefrag">forrest seed</span> with your favorite (probably
+ localized) editor without paying attention to the encoding, or when
+ you create a new file and simply copy the headers from another file.
+ </p>
+<p>
+ Although UTF-8 is an encoding well-suited for most languages, it is
+ not usually the default in popular editors or systems. In UNIX-like
+ systems, most popular editors can handle different encodings to write
+ the file in disk. With some editors the encoding of the file is
+ preserved, while with others the default is used regardless of the
+ original encoding. In most cases the encoding used to write files can
+ be controlled by setting the environment variable <span class="codefrag">LANG</span> to
+ an appropriate value, for instance:
+ </p>
<pre class="code">[localhost]$ export LANG=en_US.UTF-8</pre>
-<p>Of course the <em>appropriate</em> way to set the encoding depends on the editor/OS, but
- ultimately relys on the user preferences. So you can use the encoding you prefer, as long
- as the <span class="codefrag">encoding</span> attribute of the xml declaration matches the actual encoding
- of the file. This means that if you are not willing to abandon ISO-8859-1 you can always
- use the following declaration instead:</p>
-<pre class="code"><?xml version="1.0" encoding="ISO-8859-1"?></pre>
-<p>Another option is to use "character entities" such as <span class="codefrag">&ouml;</span>
- (ö) or the numeric form <span class="codefrag">&#246;</span> (ö). </p>
-<p>Another related issue is that your webserver needs to send http headers with the matching
- charset definitions to the html page. </p>
-<p>Here are some references which explain further: <a href="http://orixo.com/events/gt2004/bios.html#torsten">GT2004 presentation by Torsten
- Schlabach</a> and <a href="http://www.alanwood.net/unicode/">Alan Wood's Unicode
- resources</a>. </p>
+<p>
+ Of course the <em>appropriate</em> way to set the encoding depends on
+ the editor/OS, but ultimately relys on the user preferences. So you
+ can use the encoding you prefer, as long as the <span class="codefrag">encoding</span>
+ attribute of the xml declaration matches the actual encoding of the
+ file. This means that if you are not willing to abandon ISO-8859-1 you
+ can always use the following declaration instead:
+ </p>
+<pre class="code">
+<?xml version="1.0" encoding="ISO-8859-1"?>
+ </pre>
+<p>
+ Another option is to use "character entities" such as <span class="codefrag">
+&ouml;
+ </span> (ö) or the numeric form <span class="codefrag">
+&#246;
+ </span> (ö).
+ </p>
+<p>
+ Another related issue is that your webserver needs to send http
+ headers with the matching charset definitions to the html page.
+ </p>
+<p>
+ Here are some references which explain further:
+ <a href="http://orixo.com/events/gt2004/bios.html#torsten">GT2004
+ presentation by Torsten Schlabach</a> and
+ <a href="http://www.alanwood.net/unicode/">Alan Wood's Unicode
+ resources</a>.
+ </p>
</div>
-<a name="N10258"></a><a name="cleanSite"></a>
+<a name="N10257"></a><a name="cleanSite"></a>
<h4 class="faq">2.15. How to make Forrest clean up the project build directories? </h4>
<div align="right">
<a href="#cleanSite-menu">^</a>
@@ -958,35 +1101,44 @@
successive runs of forrest.
</p>
<p>
- Doing 'forrest clean-site' will remove the contents of the project's
- generated documents directory. Doing 'forrest clean-work' will remove the
- project's work directories (usually build/tmp and build/webapp which
- include the Cocoon cache and the Cocoon logs).
- Doing 'forrest clean' will remove both sections.
+ Doing 'forrest clean-site' will remove the contents of the project's
+ generated documents directory. Doing 'forrest clean-work' will remove
+ the project's work directories (usually build/tmp and build/webapp
+ which include the Cocoon cache and the Cocoon logs). Doing 'forrest
+ clean' will remove both sections.
</p>
</div>
-<a name="N10263"></a><a name="i18n"></a>
+<a name="N10262"></a><a name="i18n"></a>
<h4 class="faq">2.16. How can I internationalise (i18n) my content?</h4>
<div align="right">
<a href="#i18n-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p>The i18n features of Forrest are still under development (as of 0.7) however there are
- some features available. For example, navigation menus can be i18n'd (see fresh-site for an
- example). Currently, <a href="http://issues.apache.org/jira/browse/FOR-506">work is underway</a> to
- i18n skins</p>
-<p>All internationalistation of tokens in, for example, the skins and the menus, is carried out
- by the <a href="http://cocoon.apache.org/2.1/userdocs/transformers/i18n-transformer.html">Cocoon i18n
- Transformer</a>. You can see an example of how it works in the above linked issue.</p>
+<p>
+ The i18n features of Forrest are still under development (as of 0.7)
+ however there are some features available. For example, navigation
+ menus can be i18n'd (see fresh-site for an example). Currently,
+ <a href="http://issues.apache.org/jira/browse/FOR-506">work is
+ underway</a> to i18n skins
+ </p>
+<p>
+ All internationalistation of tokens in, for example, the skins and the
+ menus, is carried out by the
+ <a href="http://cocoon.apache.org/2.1/userdocs/transformers/i18n-transformer.html">Cocoon
+ i18n Transformer</a>. You can see an example of how it works in the
+ above linked issue.
+ </p>
</div>
-<a name="N10276"></a><a name="rawTML"></a>
+<a name="N10275"></a><a name="rawTML"></a>
<h4 class="faq">2.17. How can I include HTML content that is not to be skinned by Forrest?</h4>
<div align="right">
<a href="#rawTML-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p>To server, for example, a legacy HTML site add something like the following
- to your projects sitemap:</p>
+<p>
+ To server, for example, a legacy HTML site add something like the
+ following to your projects sitemap:
+ </p>
<pre class="code">
<map:match pattern="old_site/**.html">
<map:select type="exists">
@@ -1000,8 +1152,10 @@
</map:when>
</map:match>
</pre>
-<p>There is a more detailed discussion of this topic in the samples
- of a freshly seeded site. To see this documentation do the following:</p>
+<p>
+ There is a more detailed discussion of this topic in the samples of a
+ freshly seeded site. To see this documentation do the following:
+ </p>
<ol>
<li>mkdir seed</li>
@@ -1018,98 +1172,135 @@
</ol>
</div>
-<a name="N10299"></a><a name="technical"></a>
+<a name="N10298"></a><a name="technical"></a>
<h3 class="underlined_5">3. Technical</h3>
-<a name="N1029D"></a><a name="proxy_config"></a>
+<a name="N1029C"></a><a name="proxy_config"></a>
<h4 class="faq">3.1. I'm behind a proxy and it's preventing Plugins from being downloaded, what should I
do?</h4>
<div align="right">
<a href="#proxy_config-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p>You can configure the proxy in the <span class="codefrag">forrest.properties</span> file. Set the
- <span class="codefrag">proxy.host</span> and <span class="codefrag">proxy.port</span> accordingly.</p>
-<p>You can also cross an authenticated proxy by setting the <span class="codefrag">proxy.user</span> and <span class="codefrag">proxy.password</span> accordingly.</p>
+<p>
+ You can configure the proxy in the <span class="codefrag">forrest.properties</span>
+ file. Set the <span class="codefrag">proxy.host</span> and <span class="codefrag">proxy.port</span>
+ accordingly.
+ </p>
+<p>
+ You can also cross an authenticated proxy by setting the
+ <span class="codefrag">proxy.user</span> and <span class="codefrag">proxy.password</span> accordingly.
+ </p>
</div>
-<a name="N102B7"></a><a name="CVS_revison_tags"></a>
+<a name="N102B6"></a><a name="CVS_revison_tags"></a>
<h4 class="faq">3.2. How can I generate html-pages to show the revision tag of cvs?</h4>
<div align="right">
<a href="#CVS_revison_tags-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p>If you have:<span class="codefrag"><version>$Revision: 1.30
+<p>
+ If you have:<span class="codefrag"><version>$Revision: 1.30
$</version></span>The '1.30' will be extracted and
- displayed at the bottom of the page as "version 1.30". See for example the
- bottom of the <a href="../docs_0_70/your-project.html"> Using Forrest</a> document.</p>
-<p>This technique could also be used for a modification date with $Date: 2004/01/15 08:52:47
- $</p>
+ displayed at the bottom of the page as "version 1.30". See for
+ example the bottom of the <a href="../docs_0_70/your-project.html"> Using
+ Forrest</a> document.
+ </p>
+<p>
+ This technique could also be used for a modification date with $Date:
+ 2004/01/15 08:52:47 $
+ </p>
</div>
-<a name="N102C9"></a><a name="cli-xconf"></a>
+<a name="N102C8"></a><a name="cli-xconf"></a>
<h4 class="faq">3.3. How to control the processing of URIs by Cocoon, e.g. exclude certain URIs, include
other additional ones. </h4>
<div align="right">
<a href="#cli-xconf-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p> Forrest uses a configuration file to control the processing done by the Apache Cocoon
- command-line called cli.xconf </p>
-<p> Your project can supply its own <span class="codefrag">cli.xconf</span> and define patterns for URIs to
- exclude. There are also other powerful configuration features. </p>
-<p> This means creating a directory <span class="codefrag">src/documentation/conf</span> (or wherever
- <span class="codefrag">${forrest.conf-dir}</span> points) and copying
- <span class="codefrag">$FORREST_HOME/main/webapp/WEB-INF/cli.xconf</span> to it. Declare the location of
- this file in the forrest.properties configuration, e.g.
- <span class="codefrag">project.configfile=${project.home}/src/documentation/conf/cli.xconf</span>
+<p>
+ Forrest uses a configuration file to control the processing done by
+ the Apache Cocoon command-line called cli.xconf
+ </p>
+<p>
+ Your project can supply its own <span class="codefrag">cli.xconf</span> and define
+ patterns for URIs to exclude. There are also other powerful
+ configuration features.
+ </p>
+<p>
+ This means creating a directory <span class="codefrag">src/documentation/conf</span>
+ (or wherever <span class="codefrag">${forrest.conf-dir}</span> points) and copying
+ <span class="codefrag">$FORREST_HOME/main/webapp/WEB-INF/cli.xconf</span> to it.
+ Declare the location of this file in the forrest.properties
+ configuration, e.g.
+ <span class="codefrag">project.configfile=${project.home}/src/documentation/conf/cli.xconf</span>
</p>
-<p> Then edit cli.xconf, and add any exclude sections that you require. The default
- cli.xconf ignores directory links and links containing 'apidocs' or starting with 'api/': </p>
+<p>
+ Then edit cli.xconf, and add any exclude sections that you require.
+ The default cli.xconf ignores directory links and links containing
+ 'apidocs' or starting with 'api/':
+ </p>
<pre class="code">
+
....
<!-- Includes and excludes can be used to limit which URLs are rendered -->
<strong>
+
<exclude pattern="**/"/>
<exclude pattern="**apidocs**"/>
<exclude pattern="api/**"/>
</strong>
+
<uri src="favicon.ico"/>
-</cocoon></pre>
-<p>This is just an example, and you should modify it appropriately for your site.</p>
+</cocoon>
+ </pre>
+<p>
+ This is just an example, and you should modify it appropriately for
+ your site.
+ </p>
<div class="note">
<div class="label">Note</div>
-<div class="content"> Wildcards may be used. These are a powerful feature of Cocoon's <a href="../docs_0_70/sitemap-ref.html">sitemap</a>. For example, <strong>foo/*</strong> would match
- <span class="codefrag">foo/bar</span>, but not <span class="codefrag">foo/bar/baz</span> — use
- <strong>foo/**</strong> to match that. </div>
+<div class="content">
+ Wildcards may be used. These are a powerful feature of Cocoon's
+ <a href="../docs_0_70/sitemap-ref.html">sitemap</a>. For
+ example, <strong>foo/*</strong> would match <span class="codefrag">foo/bar</span>, but
+ not <span class="codefrag">foo/bar/baz</span> — use <strong>foo/**</strong> to
+ match that.
+ </div>
</div>
</div>
-<a name="N10306"></a><a name="ignoring_javadocs"></a>
+<a name="N10305"></a><a name="ignoring_javadocs"></a>
<h4 class="faq">3.4. How do I stop Forrest breaking on links to external files that may not exist, like
javadocs? </h4>
<div align="right">
<a href="#ignoring_javadocs-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p> This can be done by overriding the <a href="#cli-xconf">
- <span class="codefrag">cli.xconf</span>
- </a> Cocoon config file, and defining patterns for URLs to exclude. </p>
+<p>
+ This can be done by overriding the <a href="#cli-xconf">
+ <span class="codefrag">cli.xconf</span> </a> Cocoon config file, and defining
+ patterns for URLs to exclude.
+ </p>
</div>
-<a name="N10315"></a><a name="claimed_patterns"></a>
+<a name="N10314"></a><a name="claimed_patterns"></a>
<h4 class="faq">3.5. Some of my files are not being processed because they use common filenames. </h4>
<div align="right">
<a href="#claimed_patterns-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p> Certain patterns are claimed by the default sitemaps for special processing. These
- include: <span class="codefrag">site, changes, todo, faq, images, my-images, skinconf, community,
- howto</span>
+<p>
+ Certain patterns are claimed by the default sitemaps for special
+ processing. These include: <span class="codefrag">site, changes, todo, faq, images,
+ my-images, skinconf, community, howto</span>
</p>
-<p> Sometimes there are workarounds, e.g. faq.html or faq-interview.html would fail, but
- interview-faq.html would be fine. In future versions of Forrest we will attempt to deal
- with this issue (<a href="http://issues.apache.org/jira/browse/FOR-217">FOR-217</a>).
+<p>
+ Sometimes there are workarounds, e.g. faq.html or faq-interview.html
+ would fail, but interview-faq.html would be fine. In future versions
+ of Forrest we will attempt to deal with this issue
+ (<a href="http://issues.apache.org/jira/browse/FOR-217">FOR-217</a>).
</p>
</div>
-<a name="N10327"></a><a name="build_msg_a"></a>
+<a name="N10326"></a><a name="build_msg_a"></a>
<h4 class="faq">3.6. What do the symbols and numbers mean when Forrest lists each document that it has
built? </h4>
<div align="right">
@@ -1118,13 +1309,15 @@
<div style="margin-left: 15px">
<p>
-<pre class="code">...
+<pre class="code">
+...
* [212/166] [0/0] 1.16s 62.4Kb docs_0_60/your-project.pdf
X [0] /docs_0_80/upgrading_08.html BROKEN: No pipeline matched...
* [213/164] [0/0] 0.391s 29.2Kb docs_0_70/howto/howto-buildPlugin.pdf
^ apidocs/index.html
* [214/170] [7/66] 1.476s 45.5Kb docs_0_60/sitemap-ref.html
-...</pre>
+...
+ </pre>
<ul>
@@ -1142,20 +1335,26 @@
</p>
</div>
-<a name="N10343"></a><a name="headless_operation"></a>
+<a name="N10342"></a><a name="headless_operation"></a>
<h4 class="faq">3.7. 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. </h4>
<div align="right">
<a href="#headless_operation-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p> If you are using JDK 1.4.0 or newer, you can enable <em>headless</em> operation by
- running Forrest with the <span class="codefrag">forrest.jvmarg</span> parameter set to
- <span class="codefrag">-Djava.awt.headless=true</span>, like this: </p>
+<p>
+ If you are using JDK 1.4.0 or newer, you can enable <em>headless</em>
+ operation by running Forrest with the <span class="codefrag">forrest.jvmarg</span>
+ parameter set to <span class="codefrag">-Djava.awt.headless=true</span>, like this:
+ </p>
<pre class="code">forrest -Dforrest.jvmargs=-Djava.awt.headless=true site</pre>
-<p> See also <a href="http://cocoon.apache.org/2.1/faq/faq-configure-environment.html">Cocoon FAQ</a>. </p>
+<p>
+ See also
+ <a href="http://cocoon.apache.org/2.1/faq/faq-configure-environment.html">Cocoon
+ FAQ</a>.
+ </p>
</div>
-<a name="N1035F"></a><a name="project-logo-svg"></a>
+<a name="N1035E"></a><a name="project-logo-svg"></a>
<h4 class="faq">3.8.
The project logo that is generated from SVG is truncating my project name.
</h4>
@@ -1164,107 +1363,142 @@
</div>
<div style="margin-left: 15px">
<p>
- In a 'forrest seed site' the project and the group logo are generated from a
- Scalable Vector Graphics (SVG) file, using the text from the
- <span class="codefrag"><project-name></span> and
- <span class="codefrag"><group-name></span> elements of the <span class="codefrag">skinconf.xml</span> file.
- If you have a long project-name then you may need to adjust the width of the image.
+ In a 'forrest seed site' the project and the group logo are generated
+ from a Scalable Vector Graphics (SVG) file, using the text from the
+ <span class="codefrag"><project-name></span> and <span class="codefrag"><group-name></span>
+ elements of the <span class="codefrag">skinconf.xml</span> file. If you have a long
+ project-name then you may need to adjust the width of the image.
Perhaps you want to change the colours too. Edit the file at
- <span class="codefrag">src/documentation/content/xdocs/images/project.svg</span> and adjust the "width"
- attribute of the <svg> element. For further details see
- <a href="http://www.w3.org/Graphics/SVG/">SVG</a> resources.
+ <span class="codefrag">src/documentation/content/xdocs/images/project.svg</span> and
+ adjust the "width" attribute of the <svg> element. For further
+ details see <a href="http://www.w3.org/Graphics/SVG/">SVG</a>
+ resources.
</p>
</div>
-<a name="N10377"></a><a name="catalog"></a>
+<a name="N10376"></a><a name="catalog"></a>
<h4 class="faq">3.9. How do i configure my favourite XML editor or parser to find the local Forrest
DTDs? </h4>
<div align="right">
<a href="#catalog-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p> Notes are provided for various tools at <a href="../docs_0_70/catalog.html">Using Catalog Entity
- Resolver for local DTDs</a>. </p>
+<p>
+ Notes are provided for various tools at
+ <a href="../docs_0_70/catalog.html">Using Catalog Entity Resolver for
+ local DTDs</a>.
+ </p>
</div>
-<a name="N10383"></a><a name="skin"></a>
+<a name="N10382"></a><a name="skin"></a>
<h4 class="faq">3.10. How to make the site look better and change its skin? </h4>
<div align="right">
<a href="#skin-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p> There are <a href="../docs_0_70/skins.html">default skins</a> provided, which are configurable
- and so should meet the needs of most projects. The aim is to provide many capabilities so
- that extra skins are not needed. </p>
-<p> See notes about <a href="../docs_0_70/your-project.html#skins">configuration</a> of the skins.
- Some projects may have special needs and can define their <a href="../docs_0_70/your-project.html#new_skin">own skin</a>. </p>
+<p>
+ There are <a href="../docs_0_70/skins.html">default skins</a>
+ provided, which are configurable and so should meet the needs of most
+ projects. The aim is to provide many capabilities so that extra skins
+ are not needed.
+ </p>
+<p>
+ See notes about
+ <a href="../docs_0_70/your-project.html#skins">configuration</a> of
+ the skins. Some projects may have special needs and can define their
+ <a href="../docs_0_70/your-project.html#new_skin">own
+ skin</a>.
+ </p>
</div>
-<a name="N1039A"></a><a name="xsp"></a>
+<a name="N10399"></a><a name="xsp"></a>
<h4 class="faq">3.11. How do I enable XSP processing?</h4>
<div align="right">
<a href="#xsp-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p>First consider whether your needs would be better met by Cocoon itself, rather than
- Forrest. </p>
-<p>That said, there are valid reasons for wanting programmatically generated content, so
- here is how to enable XSP:</p>
+<p>
+ First consider whether your needs would be better met by Cocoon
+ itself, rather than Forrest.
+ </p>
+<p>
+ That said, there are valid reasons for wanting programmatically
+ generated content, so here is how to enable XSP:
+ </p>
<ol>
<li>Download <a 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</a>, and copy it to the $FORREST_HOME/main/webapp/WEB-INF/lib
directory (or lib/core/ directory in the source distribution).</li>
<li>
-
-<p> Add the following generator definition in the map:generators section of your <a href="../docs_0_70/project-sitemap.html">project sitemap</a>
+<p>
+ Add the following generator definition in the map:generators
+ section of your
+ <a href="../docs_0_70/project-sitemap.html">project
+ sitemap</a>
</p>
<pre class="code">
+
<map:generator name="serverpages"
pool-grow="2" pool-max="32" pool-min="4"
- src="org.apache.cocoon.generation.ServerPagesGenerator"/></pre>
-
+ src="org.apache.cocoon.generation.ServerPagesGenerator"/>
+ </pre>
</li>
<li>
-
-<p>Decide how you want to use XSP. For single files, you could just define a *.xml
- matcher:</p>
+<p>
+ Decide how you want to use XSP. For single files, you could just
+ define a *.xml matcher:
+ </p>
<pre class="code">
+
<map:match pattern="dynamic.xml">
<map:generate src="content/xdocs/dynamic.xsp" type="serverpages"/>
...
<map:serialize type="xml"/>
-</map:match></pre>
+</map:match>
+ </pre>
-<p>You may instead wish to override forrest.xmap to define a general mapping for
- XSPs.</p>
-
+<p>
+ You may instead wish to override forrest.xmap to define a general
+ mapping for XSPs.
+ </p>
</li>
</ol>
-<p>See also the <a href="http://wiki.apache.org/cocoon/AddingXSPToForrest">AddingXSPToForrest</a> Wiki page.</p>
+<p>
+ See also the
+ <a href="http://wiki.apache.org/cocoon/AddingXSPToForrest">AddingXSPToForrest</a>
+ Wiki page.
+ </p>
</div>
-<a name="N103D5"></a><a name="breadcrumbs"></a>
+<a name="N103D0"></a><a name="breadcrumbs"></a>
<h4 class="faq">3.12. How do breadcrumbs work? Why don't they work locally?</h4>
<div align="right">
<a href="#breadcrumbs-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p>Breadcrumbs begin with up to three URLs specified in <span class="codefrag">skinconf.xml</span>. Here is
- what the Forrest site uses:</p>
+<p>
+ Breadcrumbs begin with up to three URLs specified in
+ <span class="codefrag">skinconf.xml</span>. Here is what the Forrest site uses:
+ </p>
<pre class="code">
+
<trail>
<link1 name="apache" href="http://www.apache.org/"/>
<link2 name="xml.apache" href="http://xml.apache.org/"/>
<link3 name="" href=""/>
- </trail></pre>
-<p>If any links are blank, they are not used. After these first links, JavaScript looks at
- the URL for the current page and makes a link for each directory after the domain. If you
- are viewing the site locally, there is no domain and so there will be no extra
- breadcrumbs, only the ones that are specified in <span class="codefrag">skinconf.xml</span>. </p>
+ </trail>
+ </pre>
+<p>
+ If any links are blank, they are not used. After these first links,
+ JavaScript looks at the URL for the current page and makes a link for
+ each directory after the domain. If you are viewing the site locally,
+ there is no domain and so there will be no extra breadcrumbs, only the
+ ones that are specified in <span class="codefrag">skinconf.xml</span>.
+ </p>
</div>
-<a name="N103EA"></a><a name="run_port"></a>
+<a name="N103E5"></a><a name="run_port"></a>
<h4 class="faq">3.13. How do I make forrest run listen on a different port?</h4>
<div align="right">
<a href="#run_port-menu">^</a>
@@ -1275,66 +1509,83 @@
<span class="codefrag">forrest run -Dforrest.jvmargs="-Djetty.port=80"</span>
</p>
-<p>Or copy Forrest's main/webapp/jettyconf.xml file to your project's src/documentation
- directory and set the port number in that file. Then do <span class="codefrag">forrest run</span>
+<p>
+ Or copy Forrest's main/webapp/jettyconf.xml file to your project's
+ src/documentation directory and set the port number in that file. Then
+ do <span class="codefrag">forrest run</span>
</p>
</div>
-<a name="N103FE"></a><a name="old_faqs"></a>
+<a name="N103F9"></a><a name="old_faqs"></a>
<h3 class="underlined_5">4. Older version: 0.6</h3>
-<a name="N10402"></a><a name="old_claimed_patterns"></a>
+<a name="N103FD"></a><a name="old_claimed_patterns"></a>
<h4 class="faq">4.1. Some of my files are not being processed because they use common filenames. </h4>
<div align="right">
<a href="#old_claimed_patterns-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p> Certain patterns are claimed by the default sitemaps for special processing. These
- include: <span class="codefrag">site, changes, todo, faq, images, my-images, skinconf, community,
- howto</span>
+<p>
+ Certain patterns are claimed by the default sitemaps for special
+ processing. These include: <span class="codefrag">site, changes, todo, faq, images,
+ my-images, skinconf, community, howto</span>
</p>
-<p> Sometimes there are workarounds, e.g. faq.html or faq-interview.html would fail, but
- interview-faq.html would be fine. In future versions of Forrest we will attempt to deal
- with this issue (<a href="http://issues.apache.org/jira/browse/FOR-217">FOR-217</a>).
+<p>
+ Sometimes there are workarounds, e.g. faq.html or faq-interview.html
+ would fail, but interview-faq.html would be fine. In future versions
+ of Forrest we will attempt to deal with this issue
+ (<a href="http://issues.apache.org/jira/browse/FOR-217">FOR-217</a>).
</p>
</div>
-<a name="N10414"></a><a name="general"></a>
+<a name="N1040F"></a><a name="general"></a>
<h3 class="underlined_5">5. General</h3>
-<a name="N10418"></a><a name="generating_menus"></a>
+<a name="N10413"></a><a name="generating_menus"></a>
<h4 class="faq">5.1. What is the relationship between site.xml and book.xml? </h4>
<div align="right">
<a href="#generating_menus-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p> One <span class="codefrag">site.xml</span> file in your project root can replace all the book.xml files (one per
- directory) in your site. Internally, Forrest uses <span class="codefrag">site.xml</span> to dynamically generate book.xml
- files. However, Forrest first checks for the existence of a book.xml file, so
- backwards-compatibility is preserved. If a directory has a book.xml file, the book.xml
- will be used to generate the menu. This supplement is useful in situations where
- <span class="codefrag">site.xml</span>-generated menus aren't appropriate. See <a href="../docs_0_70/linking.html">Menus and
- Linking</a>. </p>
+<p>
+ One <span class="codefrag">site.xml</span> file in your project root can replace all the book.xml files
+ (one per directory) in your site. Internally, Forrest uses <span class="codefrag">site.xml</span> to
+ dynamically generate book.xml files. However, Forrest first checks for
+ the existence of a book.xml file, so backwards-compatibility is
+ preserved. If a directory has a book.xml file, the book.xml will be
+ used to generate the menu. This supplement is useful in situations
+ where <span class="codefrag">site.xml</span>-generated menus aren't appropriate. See
+ <a href="../docs_0_70/linking.html">Menus and Linking</a>.
+ </p>
</div>
-<a name="N10433"></a><a name="docbook"></a>
+<a name="N1042E"></a><a name="docbook"></a>
<h4 class="faq">5.2. How do I use DocBook as the xml documentation format? </h4>
<div align="right">
<a href="#docbook-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p> There are two ways. Forrest has a <span class="codefrag">simplifiedDocbook</span> plugin which can
- transform the DocBook format into the Forrest "xdocs" format on-the-fly and then render
- that as normal Forrest documents. Be aware that the stylesheet that does this
- transformation is deliberately very limited and does not attempt to deal with all DocBook
- elements. </p>
-<p> The other way is to use the full DocBook stylesheets directly. The DocBook DTDs are
- shipped with Forrest and automatically handled. However, you will need to have the DocBook
- stylesheets on your system (they are too massive to ship with Forrest) and configure
- Forrest accordingly. You will need to create a <a href="../docs_0_70/project-sitemap.html">project
- sitemap</a> as explained in <a href="../docs_0_70/your-project.html">Using Forrest</a> and
- add matches to handle your DocBook documents. Here is an example. Note that you need to
- change it to suit your situation. The match must be very specific so that only the DocBook
- documents are matched. The rest of the documents will be handled by Forrest core. Powerful
- regex capabilities are available. </p>
-<pre class="code"><?xml version="1.0"?>
+<p>
+ There are two ways. Forrest has a <span class="codefrag">simplifiedDocbook</span>
+ plugin which can transform the DocBook format into the Forrest "xdocs"
+ format on-the-fly and then render that as normal Forrest documents. Be
+ aware that the stylesheet that does this transformation is
+ deliberately very limited and does not attempt to deal with all
+ DocBook elements.
+ </p>
+<p>
+ The other way is to use the full DocBook stylesheets directly. The
+ DocBook DTDs are shipped with Forrest and automatically handled.
+ However, you will need to have the DocBook stylesheets on your system
+ (they are too massive to ship with Forrest) and configure Forrest
+ accordingly. You will need to create a
+ <a href="../docs_0_70/project-sitemap.html">project sitemap</a> as
+ explained in <a href="../docs_0_70/your-project.html">Using
+ Forrest</a> and add matches to handle your DocBook documents. Here
+ is an example. Note that you need to change it to suit your situation.
+ The match must be very specific so that only the DocBook documents are
+ matched. The rest of the documents will be handled by Forrest core.
+ Powerful regex capabilities are available.
+ </p>
+<pre class="code">
+<?xml version="1.0"?>
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
<map:pipelines>
<map:pipeline>
@@ -1346,73 +1597,106 @@
</map:match>
</map:pipeline>
</map:pipelines>
-</map:sitemap></pre>
-<p>You need to define the xhtml serializer used in <map:serialize type="xhtml"/>
- in the components section of the sitemap. See the
- <a href="http://cocoon.apache.org/2.1/userdocs/serializers/xhtml-serializer.html">Cocoon
- docs</a> for the elements you need to add to define this component. You can see examples
- of other components being added in the <span class="codefrag">FORREST_HOME/main/webapp/sitemap.xmap</span> file.</p>
-<p> 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 source files as
- "document-v*" DTD and DocBook. </p>
-<p> Ensure that the document type declaration in your xml instance is well specified. Use a
- public identifier. The DTD will then be properly resolved by Forrest. If you need to use
- different DTDs, then see <a href="../docs_0_70/your-project.html#new_dtd">Using Forrest</a> for
- configuration guidance. </p>
+</map:sitemap>
+ </pre>
+<p>
+ You need to define the xhtml serializer used in <map:serialize
+ type="xhtml"/> in the components section of the sitemap. See the
+ <a href="http://cocoon.apache.org/2.1/userdocs/serializers/xhtml-serializer.html">Cocoon
+ docs</a> for the elements you need to add to define this component.
+ You can see examples of other components being added in the
+ <span class="codefrag">FORREST_HOME/main/webapp/sitemap.xmap</span> file.
+ </p>
+<p>
+ 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 source files as "document-v*" DTD and
+ DocBook.
+ </p>
+<p>
+ Ensure that the document type declaration in your xml instance is well
+ specified. Use a public identifier. The DTD will then be properly
+ resolved by Forrest. If you need to use different DTDs, then see
+ <a href="../docs_0_70/your-project.html#new_dtd">Using Forrest</a> for
+ configuration guidance.
+ </p>
</div>
-<a name="N10461"></a><a name="version"></a>
+<a name="N1045C"></a><a name="version"></a>
<h4 class="faq">5.3. How to report which version of Forrest is being used and the properties that are
set? </h4>
<div align="right">
<a href="#version-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p> Do <span class="codefrag">'forrest -projecthelp'</span> or <span class="codefrag">'./build.sh'</span> to find the version
- number. </p>
-<p> To list the properties, add "forrest.echo=true" to your forrest.properties file and
- watch the build messages. Doing <span class="codefrag">'forrest -v'</span> will provide verbose build
- messages. </p>
+<p>
+ Do <span class="codefrag">'forrest -projecthelp'</span> or <span class="codefrag">'./build.sh'</span> to
+ find the version number.
+ </p>
+<p>
+ To list the properties, add "forrest.echo=true" to your
+ forrest.properties file and watch the build messages. Doing
+ <span class="codefrag">'forrest -v'</span> will provide verbose build messages.
+ </p>
</div>
-<a name="N10475"></a><a name="logs"></a>
+<a name="N10470"></a><a name="logs"></a>
<h4 class="faq">5.4. Where are the log files to find more infomation about errors? </h4>
<div align="right">
<a href="#logs-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p> The logfiles are at <span class="codefrag">build/webapp/WEB-INF/logs/</span>
+<p>
+ The logfiles are at <span class="codefrag">build/webapp/WEB-INF/logs/</span>
</p>
-<p> The log level can be raised with the <span class="codefrag">logkit.xconf</span> configuration. If you are
- using Forrest in the interactive webapp mode (which is generally easiest for debugging
- errors) then see the <span class="codefrag">build/webapp/WEB-INF/logkit.xconf</span> file. If you are
+<p>
+ The log level can be raised with the <span class="codefrag">logkit.xconf</span>
+ configuration. If you are using Forrest in the interactive webapp mode
+ (which is generally easiest for debugging errors) then see the
+ <span class="codefrag">build/webapp/WEB-INF/logkit.xconf</span> file. If you are
generating a static site (with command-line 'forrest') then copy
- <span class="codefrag">$FORREST_HOME/main/webapp/WEB-INF/logkit.xconf</span> to your project at
- <span class="codefrag">src/documentation/content/conf/logkit.xconf</span> and modify it. See more
- information and efficiency tips with <a href="http://wiki.apache.org/cocoon/ExploringTheLogs">Cocoon logging</a>. </p>
-<p> Doing <span class="codefrag">'forrest -v'</span> will provide verbose build messages to the standard
- output. </p>
+ <span class="codefrag">$FORREST_HOME/main/webapp/WEB-INF/logkit.xconf</span> to your
+ project at <span class="codefrag">src/documentation/content/conf/logkit.xconf</span>
+ and modify it. See more information and efficiency tips with
+ <a href="http://wiki.apache.org/cocoon/ExploringTheLogs">Cocoon
+ logging</a>.
+ </p>
+<p>
+ Doing <span class="codefrag">'forrest -v'</span> will provide verbose build messages to
+ the standard output.
+ </p>
</div>
-<a name="N10499"></a><a name="how_can_I_help"></a>
+<a name="N10494"></a><a name="how_can_I_help"></a>
<h4 class="faq">5.5. How to help? </h4>
<div align="right">
<a href="#how_can_I_help-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p> Join one of the Forrest project <a href="../mail-lists.html">mailing lists</a> and
- tell us what you would like to see improved. We regard all feedback as valuable,
- particularly from newcomers—often, close proximity blinds software developers to
- faults that are obvious to everyone else. Don't be shy! </p>
+<p>
+ Join one of the Forrest project <a href="../mail-lists.html">mailing
+ lists</a> and tell us what you would like to see improved. We
+ regard all feedback as valuable, particularly from
+ newcomers—often, close proximity blinds software developers to
+ faults that are obvious to everyone else. Don't be shy!
+ </p>
</div>
-<a name="N104A5"></a><a name="patch"></a>
+<a name="N104A0"></a><a name="patch"></a>
<h4 class="faq">5.6. How to contribute a patch? </h4>
<div align="right">
<a href="#patch-menu">^</a>
</div>
<div style="margin-left: 15px">
-<p>Please send all contributions via our <a href="../issues.html">issue tracker</a>. Here
- are notes about <a href="../contrib.html#patch">making patches</a>. </p>
-<p>More info about contributing can be found at the <a href="../contrib.html">Contributing
- to Forrest</a> page. It is always a good idea to check the Forrest <a href="../issues.html">issue tracker</a> before diving in. </p>
+<p>
+ Please send all contributions via our <a href="../issues.html">issue
+ tracker</a>. Here are notes about
+ <a href="../contrib.html#patch">making patches</a>.
+ </p>
+<p>
+ More info about contributing can be found at the
+ <a href="../contrib.html">Contributing to Forrest</a> page. It is
+ always a good idea to check the Forrest
+ <a href="../issues.html">issue tracker</a> before diving
+ in.
+ </p>
</div>
</div>
</div>
Modified: forrest/site/docs_0_70/faq.pdf
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_70/faq.pdf?view=diff&rev=529915&r1=529914&r2=529915
==============================================================================
Binary files - no diff available.