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/10 06:44:05 UTC
svn commit: r527020 [5/20] - in /forrest/site: ./ docs_0_80/
docs_0_80/howto/ docs_0_80/howto/cvs-ssh/ docs_0_80/howto/multi/ dtdx/
plan/ pluginDocs/plugins_0_70/ pluginDocs/plugins_0_80/ procedures/
procedures/release/ skins/ tools/
Modified: forrest/site/docs_0_80/faq.pdf
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_80/faq.pdf?view=diff&rev=527020&r1=527019&r2=527020
==============================================================================
Binary files - no diff available.
Modified: forrest/site/docs_0_80/faq.xml
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_80/faq.xml?view=diff&rev=527020&r1=527019&r2=527020
==============================================================================
--- forrest/site/docs_0_80/faq.xml (original)
+++ forrest/site/docs_0_80/faq.xml Mon Apr 9 21:44:00 2007
@@ -15,54 +15,66 @@
limitations under the License.
--><document><header><title>Frequently Asked Questions</title></header><body><section id="Questions"><title>Questions</title><section id="getting_started"><title>1. Getting Started and Building Forrest</title><section id="faq"><title>1.1. How to use these FAQs? </title>
<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>
</section><section id="overview"><title>1.2. Where can I read an overview about how to work with Forrest? </title>
- <p> See the <link href="site:your-project">Using Forrest</link> guide. </p>
+ <p>
+ See the <link href="site:your-project">Using Forrest</link> guide.
+ </p>
</section><section id="docs"><title>1.3. Where is all of the documentation?</title>
<p>
- You have a local copy of the main documentation with your version of Forrest.
- Do 'cd site-author; forrest run' and visit http://localhost:8888/ in your browser.
- The most recent documentation is in SVN trunk which creates the forrest.apache.org website.
+ You have a local copy of the main documentation with your version of
+ Forrest. Do 'cd site-author; forrest run' and visit
+ http://localhost:8888/ in your browser. The most recent documentation
+ is in SVN trunk which creates the forrest.apache.org website.
</p>
<p>
- Each <link href="site:plugins/index">plugin</link> has its own documentation
- and working examples of its techniques.
+ Each <link href="site:plugins/index">plugin</link> has its own
+ documentation and working examples of its techniques.
</p>
<p>
- The example seed site has other documentation and working examples of various techniques.
- Do 'cd my-new-directory; forrest seed-sample; forrest run'.
- Every hour the forrestbot generates a static version of this documentation on our
- <link href="site:zone">testing zone</link>.
+ The example seed site has other documentation and working examples of
+ various techniques. Do 'cd my-new-directory; forrest seed-sample;
+ forrest run'. Every hour the forrestbot generates a static version of
+ this documentation on our <link href="site:zone">testing zone</link>.
</p>
</section><section id="requirements"><title>1.4. What are the system requirements for Forrest? </title>
- <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>
</section><section id="cvs"><title>1.5. The old xml-forrest CVS code repository seems to be stale. What happened? </title>
- <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>
</section><section id="svn"><title>1.6. How can I use SVN to keep up to date with the latest codebase? </title>
- <p> Follow these <link href="site:build">Building Forrest</link> notes. </p>
- <p> The <link href="site:your-project">Using Forrest</link> guide provides further
- step-by-step assistance in getting started with Forrest for your project. </p>
+ <p>
+ Follow these <link href="site:build">Building Forrest</link> notes.
+ </p>
+ <p>
+ The <link href="site:your-project">Using Forrest</link> guide provides
+ further step-by-step assistance in getting started with Forrest for
+ your project.
+ </p>
</section><section id="older-plugins"><title>1.7. How to use older versions of specific plugins? </title>
<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
<link href="site:plugins/index">documentation</link>.
</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>
<source xml:space="preserve">project.required.plugins=org.apache.forrest.plugin.input.PhotoGallery-0.1,...</source>
<p>
@@ -79,24 +91,20 @@
<source xml:space="preserve">project.required.plugins=org.apache.forrest.plugin.input.projectInfo-0.1,...</source>
</section><section id="single-document"><title>1.8. What is the best way to generate "standalone documents" using Forrest? </title>
<p>
- There is a trick that can cut down your turnaround time
- with building. In forrest.properties ...
+ There is a trick that can cut down your turnaround time with building.
+ In forrest.properties ...
</p>
-
<source xml:space="preserve">
# The URL to start crawling from
#project.start-uri=linkmap.html
</source>
-
<p>
- Uncomment that and set it to the specific page that
- you want. Forrest will build that single document, then of course
- it will keep crawling links from there. It might be
- confined to a sub-directory, but depending on links
- could end up generating the whole site. The main
+ Uncomment that and set it to the specific page that you want. Forrest
+ will build that single document, then of course it will keep crawling
+ links from there. It might be confined to a sub-directory, but
+ depending on links could end up generating the whole site. The main
thing is that your page of interest is built first.
</p>
-
<p>
It is probably easiest to make this change temporarily as a
command-line parameter, e.g.
@@ -104,104 +112,128 @@
<source xml:space="preserve">
forrest -Dproject.start-uri=live-sites.html
</source>
-
<p>
- You can terminate forrest with 'kill' or Ctrl-C after it
- has built your pages of interest.
+ You can terminate forrest with 'kill' or Ctrl-C after it has built
+ your pages of interest.
</p>
-
<p>
- Cocoon can be instructed via the
- <link href="#cli-xconf">Cocoon cli.xconf</link> file to not
- follow links (see its "follow-links" parameter). So this will
- build only the document that was specified. Be careful, if you
- also usually build PDF pages, then they will not be built.
+ Cocoon can be instructed via the <link href="#cli-xconf">Cocoon
+ cli.xconf</link> file to not follow links (see its "follow-links"
+ parameter). So this will build only the document that was specified.
+ Be careful, if you also usually build PDF pages, then they will not be
+ built.
</p>
-
<p>
- Cocoon can also be instructed to not process certain URIs
- if you need to temporarily exclude then.
+ Cocoon can also be instructed to not process certain URIs if you need
+ to temporarily exclude then.
</p>
<p>
- Another useful technique is to use 'wget' or Apache Ant's Get task
- to retrieve individual files, e.g.
- Do 'forrest run' and then 'wget http://localhost:8888/index.pdf'.
+ Another useful technique is to use 'wget' or Apache Ant's Get task to
+ retrieve individual files, e.g. Do 'forrest run' and then 'wget
+ http://localhost:8888/index.pdf'.
</p>
</section><section id="cygwin_mutex_error"><title>1.9. When running <code>./build.sh</code> in cygwin, I get an error: <code>cygpath.exe:
*** can't create title mutex, Win32 error 6</code>. </title>
- <p> This <link href="http://issues.apache.org/jira/secure/ViewIssue.jspa?key=FOR-10">appears
- to be a bug in cygwin</link>. Please use the .bat script instead. </p>
+ <p>
+ This
+ <link href="http://issues.apache.org/jira/secure/ViewIssue.jspa?key=FOR-10">appears
+ to be a bug in cygwin</link>. Please use the .bat script instead.
+ </p>
</section><section id="maxmemory"><title>1.10. How can I specify the amount of memory to be used by Java? </title>
- <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 <code>maxmemory</code> property in the <code>forrest.properties</code> 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 <code>maxmemory</code> property in the
+ <code>forrest.properties</code> file controls how much memory Cocoon
+ uses. Like many other properties you can copy them from the default
configuration at <code>main/fresh-site/forrest.properties</code>
</p>
- <p> Set the <code>ANT_OPTS</code> environment variable before you run forrest. The exact
- value you set it to is dependant on your JVM, but something like
- <code>ANT_OPTS=-Xmx500M</code> will probably work. </p>
+ <p>
+ Set the <code>ANT_OPTS</code> environment variable before you run
+ forrest. The exact value you set it to is dependant on your JVM, but
+ something like <code>ANT_OPTS=-Xmx500M</code> will probably work.
+ </p>
</section><section id="debug"><title>1.11. How can I start forrest in Java debug mode? </title>
- <p> The <code>forrest.jvmargs</code> property in the <code>forrest.properties</code> file
- can be used to start forrest in debug mode on a specific port.
- <code>forrest.jvmargs=-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n</code>
+ <p>
+ The <code>forrest.jvmargs</code> property in the
+ <code>forrest.properties</code> file can be used to start forrest in
+ debug mode on a specific port. <code>forrest.jvmargs=-Xdebug
+ -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n</code>
</p>
</section></section><section id="content_faqs"><title>2. Content Creation</title><section id="edit-content"><title>2.1. What tools can be used to edit the content?</title>
- <p>If you are using the Apache Forrest XML <link href="site:dtd-docs">document format</link>
- 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 <link href="site:catalog">configuration notes</link> for various editors. </p>
- <p>There are content management systems like <link href="ext:lenya">Apache Lenya</link>. </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
+ <link href="site:dtd-docs">document format</link> 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
+ <link href="site:catalog">configuration notes</link> for
+ various editors.
+ </p>
+ <p>
+ There are content management systems like
+ <link href="ext:lenya">Apache Lenya</link>.
+ </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>
</section><section id="site-xml"><title>2.2.
How to use the <code>site.xml</code> configuration file for menus and linking.
</title>
<p>
- The <code>site.xml</code> configuration file is used for two different purposes:
- defining the navigation menus, and as a method for defining references
- to be used when linking between documents.
- This file is fully explained in
- <link href="site:linking">Menus and Linking</link>. Here is a precis:
+ The <code>site.xml</code> configuration file is used for two different
+ purposes: defining the navigation menus, and as a method for defining
+ references to be used when linking between documents. This file is
+ fully explained in <link href="site:linking">Menus and Linking</link>.
+ Here is a precis:
</p>
<p>
The labels can be whatever text you want.
</p>
- <source xml:space="preserve"><faq label="FAQs" href="faq.html">
+ <source xml:space="preserve">
+<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></source>
+</faq>
+ </source>
<p>
That will create a menu like this with three links:
</p>
<source xml:space="preserve">FAQs
Technical
User</source>
-
<p>
These documents can be linked to from other documents, like this:
</p>
- <source xml:space="preserve"><a href="site:faq/tech"> link to the top of the Tech FAQs
-<a href="site:faq/tech/docbook"> link to the DocBook FAQ in the Tech FAQs</source>
-
+ <source xml:space="preserve">
+<a href="site:faq/tech"> link to the top of the Tech FAQs
+<a href="site:faq/tech/docbook"> link to the DocBook FAQ in the Tech FAQs
+ </source>
<p>
If that "docbook" entry was a unique name in your site.xml then you
can shorten that latter link:
</p>
- <source xml:space="preserve"><a href="site:docbook"> link to the DocBook FAQ in the Tech FAQs</source>
+ <source xml:space="preserve">
+<a href="site:docbook"> link to the DocBook FAQ in the Tech FAQs
+ </source>
</section><section id="examples"><title>2.3.
Where are examples of documents and site.xml and tabs.xml files?
</title>
<p>
- There are examples in the 'forrest seed site' and also the Forrest website documents
- are included with the distribution (<code>cd forrest/site-author;
- forrest run</code>).
+ There are examples in the 'forrest seed site' and also the Forrest
+ website documents are included with the distribution (<code>cd
+ forrest/site-author; forrest run</code>).
</p>
</section><section id="crawler"><title>2.4.
Help, one of my documents is not being rendered.
@@ -212,41 +244,55 @@
document and crawls the links to find other documents to process.
</p>
<p>
- There are essentially two ways to create links. Via a site.xml file to define the
- navigation and menu structure, or via direct relative linking. See the
- to previous FAQs.
+ There are essentially two ways to create links. Via a site.xml file to
+ define the navigation and menu structure, or via direct relative
+ linking. See the to previous FAQs.
</p>
<p>
- Normally the source material will be local. The Forrest crawler does not follow
- and process off-site links. The new locationmap (0.8+) enables content
- to be drawn from remote sources.
-
+ Normally the source material will be local. The Forrest crawler does
+ not follow and process off-site links. The new locationmap (0.8+)
+ enables content to be drawn from remote sources.
</p>
</section><section id="PDF-output"><title>2.5. How can I generate one pdf-file out of the whole site or selected pages of the site?</title>
- <p>Add the following entries to your site.xml file:</p>
+ <p>
+ Add the following entries to your site.xml file:
+ </p>
<source xml:space="preserve">
+
<about tab="home" label="About" href="">
...
<all_site label="Full HTML" href="wholesite.html"/>
<all_sitePDF label="Full PDF" href="wholesite.pdf"/>
...
- </about></source>
- <p> In this case the menu labeled "About" will have 2 new items: "Full PDF" and "Full HTML".
- (See also <link href="site:pdf-tab">How to create a PDF document for each
- tab</link>.) </p>
- <p> This assumes that you use the <link href="site:linking">site.xml</link> method for your
- site structure and navigation, rather than the old book.xml method. </p>
+ </about>
+ </source>
+ <p>
+ In this case the menu labeled "About" will have 2 new items: "Full
+ PDF" and "Full HTML". (See also <link href="site:pdf-tab">How to
+ create a PDF document for each tab</link>.)
+ </p>
+ <p>
+ This assumes that you use the
+ <link href="site:linking">site.xml</link> method for your site
+ structure and navigation, rather than the old book.xml method.
+ </p>
</section><section id="pageBreaks"><title>2.6. How do I insert page breaks into documents?</title>
- <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 <code>extra-css</code> element in your projects
- <code>skinconf.xml</code>
+ <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 <code>extra-css</code>
+ element in your projects <code>skinconf.xml</code>
</p>
<source xml:space="preserve">
.pageBreakBefore {
@@ -259,51 +305,78 @@
} </source>
</section><section id="clickable-email-address"><title>2.7. How can I generate html-pages to show a 'clickable' email-address (of the
author-element)?</title>
- <p>You would override <code>
- $FORREST_HOME/main/webapp/skins/common/xslt/html/document-to-html.xsl</code> and edit the
- "headers/authors" template. </p>
+ <p>
+ You would override <code>
+ $FORREST_HOME/main/webapp/skins/common/xslt/html/document-to-html.xsl</code>
+ and edit the "headers/authors" template.
+ </p>
</section><section id="link_raw"><title>2.8. How do I link to raw files such as config.txt and brochure.pdf? </title>
- <p>Handling of raw files was significantly changed in Forrest 0.7. See
- <link href="site:v0.70//upgrading_07/raw">Upgrading to Apache Forrest 0.7</link> for
- all the details.</p>
+ <p>
+ Handling of raw files was significantly changed in Forrest 0.7. See
+ <link href="site:v0.70//upgrading_07/raw">Upgrading to Apache Forrest
+ 0.7</link> for all the details.
+ </p>
</section><section id="pdf_images"><title>2.9. Images don't display in PDFs. How do I fix this?</title>
- <p> Forrest uses <link href="http://xml.apache.org/fop/">Apache FOP</link> 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 <link href="http://xml.apache.org/fop/graphics.html">FOP Graphics formats</link>
+ <p>
+ Forrest uses <link href="http://xml.apache.org/fop/">Apache FOP</link>
+ 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
+ <link href="http://xml.apache.org/fop/graphics.html">FOP
+ Graphics formats</link>
+ </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 <link href="http://java.sun.com/products/jimi/">http://java.sun.com/products/jimi/</link>
- </li>
+ <li>Download Jimi from <link href="http://java.sun.com/products/jimi/">http://java.sun.com/products/jimi/</link></li>
<li>Unpack the Jimi distribution and copy JimiProClasses.zip to
<code>$FORREST/lib/optional/jimi-1.0.jar</code>.</li>
</ol>
- <p>Alternatively you can use JAI (Java Advanced Imaging API at
- <code>http://java.sun.com/products/java-media/jai</code>). For more 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>
+ <p>
+ Alternatively you can use JAI (Java Advanced Imaging API at
+ <code>http://java.sun.com/products/java-media/jai</code>). For more
+ 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>
</section><section id="tab-index"><title>2.10. The tab link in my site incorrectly assumes that 'index.html' is present in the
linked-to directory. How do I fix this? </title>
- <p> In <code>tabs.xml</code>, 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 <code>manual/Introduction.html</code> then <code>tabs.xml</code> should
- contain: </p>
+ <p>
+ In <code>tabs.xml</code>, 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
+ <code>manual/Introduction.html</code> then <code>tabs.xml</code>
+ should contain:
+ </p>
<source xml:space="preserve">
- <tab label="User Manual" href="manual"/></source>
- <p> and add this rule to the sitemap: </p>
+
+ <tab label="User Manual" href="manual"/>
+ </source>
+ <p>
+ and add this rule to the sitemap:
+ </p>
<source xml:space="preserve">
+
<map:match pattern="manual">
<map:redirect-to uri="manual/Introduction.html"/>
- </map:match></source>
+ </map:match>
+ </source>
</section><section id="tab-site"><title>2.11. I need help with the interaction between tabs.xml and site.xml </title>
<p>
See the <link href="site:linking/tab-site">tips</link>.
</p>
</section><section id="defaultFileName"><title>2.12. How can I change the default file name that Forrest will look for when I request a
URL like <code>http://myserver</code> or <code>http://myserver/mydir/</code> ? </title>
- <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 '<link href="#cli-xconf">cli.xconf</link>' file for your project </li>
<li> Edit that file to replace 'index.html' in
@@ -311,83 +384,137 @@
with 'overview.html'. </li>
<li> Edit your project's <link href="site:project-sitemap">sitemap.xmap</link> file. </li>
<li> Add the following code just before the end of the pipelines-element:<source xml:space="preserve">
+
<map:pipeline>
<map:match type="regexp" pattern="^.+/$">
<map:redirect-to uri="overview.html"/>
</map:match>
</map:pipeline>
- </source></li>
+
+ </source></li>
</ol>
</section><section id="defaultStartPage"><title>2.13. How can I use a start-up-page other than index.html? </title>
- <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 <link href="site:project-sitemap">sitemap.xmap</link> file.</li>
<li>Add the following code just before the end of the pipelines-element:<source xml:space="preserve">
+
<map:pipeline>
<map:match pattern="">
<map:redirect-to uri="start.html" />
</map:match>
</map:pipeline>
- </source></li>
+
+ </source></li>
<li>Name the uri-attribute whatever you'd like your start page to be.</li>
<li>Don't forget to create that page and refer to it in your site.xml</li>
</ol>
</section><section id="label-entity"><title>2.14. How to use special characters in the labels of the site.xml file? </title>
- <p> Use the numeric values for character entities. For example, rather than using
- <code>&ouml;</code> use <code>&#246;</code>
+ <p>
+ Use the numeric values for character entities. For example, rather
+ than using <code>
+&ouml;
+ </code> use <code>
+&#246;
+ </code>
+ </p>
+ <p>
+ See the
+ <link href="http://www.w3.org/TR/xhtml-modularization/dtd_module_defs.html#a_xhtml_character_entities">XHTML
+ Character Entities</link> and see more discussion at
+ <link href="http://issues.apache.org/jira/browse/FOR-244">Issue
+ FOR-244</link>.
</p>
- <p> See the <link href="http://www.w3.org/TR/xhtml-modularization/dtd_module_defs.html#a_xhtml_character_entities">XHTML Character Entities</link> and see more discussion at <link href="http://issues.apache.org/jira/browse/FOR-244">Issue FOR-244</link>. </p>
</section><section id="encoding"><title>2.15. Does Forrest handle accents for non-English languages?</title>
- <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>
<li>diereses: ä ë ï ö ü</li>
<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>
- <source xml:space="preserve"><?xml version="1.0" encoding="UTF-8"?></source>
- <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
- <code>forrest seed</code> 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 <code>LANG</code> 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>
+ <source xml:space="preserve">
+<?xml version="1.0" encoding="UTF-8"?>
+ </source>
+ <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 <code>forrest seed</code> 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 <code>LANG</code> to
+ an appropriate value, for instance:
+ </p>
<source xml:space="preserve">[localhost]$ export LANG=en_US.UTF-8</source>
- <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 <code>encoding</code> 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>
- <source xml:space="preserve"><?xml version="1.0" encoding="ISO-8859-1"?></source>
- <p>Another option is to use "character entities" such as <code>&ouml;</code>
- (ö) or the numeric form <code>&#246;</code> (ö). </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: <link href="http://orixo.com/events/gt2004/bios.html#torsten">GT2004 presentation by Torsten
- Schlabach</link> and <link href="http://www.alanwood.net/unicode/">Alan Wood's Unicode
- resources</link>. </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 <code>encoding</code>
+ 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>
+ <source xml:space="preserve">
+<?xml version="1.0" encoding="ISO-8859-1"?>
+ </source>
+ <p>
+ Another option is to use "character entities" such as <code>
+&ouml;
+ </code> (ö) or the numeric form <code>
+&#246;
+ </code> (ö).
+ </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:
+ <link href="http://orixo.com/events/gt2004/bios.html#torsten">GT2004
+ presentation by Torsten Schlabach</link> and
+ <link href="http://www.alanwood.net/unicode/">Alan Wood's Unicode
+ resources</link>.
+ </p>
</section><section id="xml-entities"><title>2.16. How to use XML entities, for example string
replacement?</title>
<p>
- A set of symbols is available. See the demonstration
- in a fresh 'forrest seed' site (at samples/xml-entities.html).
- For example, use "<code>&myp-t;</code>" to represent the
- project name together with trademark symbol
- "My Project Name™".
- Avoid lengthy typing and potential spelling errors.
+ A set of symbols is available. See the demonstration in a fresh
+ 'forrest seed' site (at samples/xml-entities.html). For example, use
+ "<code>&myp-t;</code>" to represent the project name together with
+ trademark symbol "My Project Name™". Avoid lengthy typing and
+ potential spelling errors.
</p>
</section><section id="cleanSite"><title>2.17. How to make Forrest clean up the project build directories? </title>
<p>
@@ -396,25 +523,33 @@
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>
</section><section id="i18n"><title>2.18. How can I internationalise (i18n) my content?</title>
- <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, <link href="http://issues.apache.org/jira/browse/FOR-506">work is underway</link> to
- i18n skins</p>
-
- <p>All internationalistation of tokens in, for example, the skins and the menus, is carried out
- by the <link href="http://cocoon.apache.org/2.1/userdocs/i18nTransformer.html">Cocoon i18n
- Transformer</link>. 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,
+ <link href="http://issues.apache.org/jira/browse/FOR-506">work is
+ underway</link> to i18n skins
+ </p>
+ <p>
+ All internationalistation of tokens in, for example, the skins and the
+ menus, is carried out by the
+ <link href="http://cocoon.apache.org/2.1/userdocs/i18nTransformer.html">Cocoon
+ i18n Transformer</link>. You can see an example of how it works in the
+ above linked issue.
+ </p>
</section><section id="rawHTML"><title>2.19. How can I include HTML content that is not to be skinned by Forrest?</title>
- <p>To serve, for example a legacy HTML site, add something like the following
- to your project's sitemap and place the source content at the
- <code>src/documentation/content/xdocs/old_site/</code> directory.</p>
+ <p>
+ To serve, for example a legacy HTML site, add something like the
+ following to your project's sitemap and place the source content at
+ the <code>src/documentation/content/xdocs/old_site/</code> directory.
+ </p>
<source xml:space="preserve">
<map:match pattern="old_site/**.html">
<map:select type="exists">
@@ -429,14 +564,16 @@
</map:select>
</map:match>
</source>
-
- <p>Exactly what the match should be is dependant on your content
- structure. It is outside the scope of this FAQ to provide full details,
- but new users may like to refer to the
- <link href="site:sitemap-ref">Cocoon sitemap</link> docs.</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>
+ <p>
+ Exactly what the match should be is dependant on your content
+ structure. It is outside the scope of this FAQ to provide full
+ details, but new users may like to refer to the
+ <link href="site:sitemap-ref">Cocoon sitemap</link> docs.
+ </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>
<li>cd seed</li>
@@ -446,37 +583,36 @@
</ol>
</section><section id="javascript"><title>2.20. How to include additional Javascript and CSS files?</title>
<p>
- Place various resources (e.g. javascript, css) into the
- "project skins" directory. The default forrest.properties
- has this at src/documentation/skins/$skin-name/
- Javascript files would go in a "scripts" subdirectory.
- CSS files would go in a "css" subdirectory.
+ Place various resources (e.g. javascript, css) into the "project
+ skins" directory. The default forrest.properties has this at
+ src/documentation/skins/$skin-name/ Javascript files would go in a
+ "scripts" subdirectory. CSS files would go in a "css" subdirectory.
</p>
<p>
- Then refer to those from your source documents with
- URIs like /skin/blah.js and /skin/foo.css
+ Then refer to those from your source documents with URIs like
+ /skin/blah.js and /skin/foo.css
</p>
<p>
- See how this is handled in the core sitemap
- called forrest/main/webapp/resources.xmap
- Search for "javascript" then follow to the
- <map:resource name="skin-read"> section.
+ See how this is handled in the core sitemap called
+ forrest/main/webapp/resources.xmap Search for "javascript" then follow
+ to the <map:resource name="skin-read"> section.
</p>
</section><section id="linkmap"><title>2.21. How to show a Table Of Contents for the whole site?</title>
<p>
Every site has an automatically generated document at
- <code>/linkmap.html</code>
- which is produced from the site.xml navigation configuration.
- It uses the @label and absolutized @href and element name and @description attribute for
- each node.
+ <code>/linkmap.html</code> which is produced from the site.xml
+ navigation configuration. It uses the @label and absolutized @href and
+ element name and @description attribute for each node.
</p>
<p>
- For example, the Forrest project's <link href="site:linkmap">Site Linkmap Table of Contents</link>.
+ For example, the Forrest project's <link href="site:linkmap">Site
+ Linkmap Table of Contents</link>.
</p>
<p>
- The document is also useful when developing your documentation and linking
- to other docs. The element names (column #2) e.g.
- href="site:<strong>mail-lists</strong>" or href="site:<strong>howto/overview</strong>"
+ The document is also useful when developing your documentation and
+ linking to other docs. The element names (column #2) e.g.
+ href="site:<strong>mail-lists</strong>" or
+ href="site:<strong>howto/overview</strong>"
</p>
<p>
This is also the document that 'forrest site' uses to kick-start the
@@ -486,13 +622,14 @@
</section></section><section id="technical"><title>3. Technical</title><section id="java-code"><title>3.1. Where is the Java code?</title>
<p>
Because we are based on Apache Cocoon, a lot of the functionality is
- provided behind-the-scenes, i.e. we use Cocoon's sitemaps and sitemap components
- such as XSLT transformers. So there is not much need for Java code in Forrest.
+ provided behind-the-scenes, i.e. we use Cocoon's sitemaps and sitemap
+ components such as XSLT transformers. So there is not much need for
+ Java code in Forrest.
</p>
<p>
- For Forrest developers who want to explore or enhance that code, see the
- Apache Cocoon SVN trunk. From time-to-time we update Forrest's packaged
- version of Cocoon and so can include your contributions.
+ For Forrest developers who want to explore or enhance that code, see
+ the Apache Cocoon SVN trunk. From time-to-time we update Forrest's
+ packaged version of Cocoon and so can include your contributions.
</p>
<p>
That said, you will find some Java code in Forrest at main/java/...
@@ -502,95 +639,144 @@
</p>
</section><section id="populate-cache"><title>3.2. How to enhance the responsiveness of the cache?</title>
<p>
- Apache Cocoon has a sophisticated cache. When running Forrest in dynamic
- mode, the initial visitor will receive slower response. The very first
- page served will cause Cocoon to cache the pipelines. Later requests
- will re-use those cached components and add others to the cache.
- A good technique is to warm up the cache after the forrest webapp has
- been re-started. Requesting the front page alone will populate the
- cache with the common items used for other pages. Using a spider
- such as wget, will warm up everything.
+ Apache Cocoon has a sophisticated cache. When running Forrest in
+ dynamic mode, the initial visitor will receive slower response. The
+ very first page served will cause Cocoon to cache the pipelines. Later
+ requests will re-use those cached components and add others to the
+ cache. A good technique is to warm up the cache after the forrest
+ webapp has been re-started. Requesting the front page alone will
+ populate the cache with the common items used for other pages. Using a
+ spider such as wget, will warm up everything.
</p>
<p>
The Cocoon cache and sitemaps can be tuned. See
- <link href="http://cocoon.apache.org/2.1/performancetips.html">Cocoon Performance Tips</link>
- and
+ <link href="http://cocoon.apache.org/2.1/performancetips.html">Cocoon
+ Performance Tips</link> and
<link href="http://wiki.apache.org/cocoon/CocoonPerformance">CocoonPerformance</link>
- and the "Object Stores" section of main/webapp/WEB-INF/forrest-core.xconf
+ and the "Object Stores" section of
+ main/webapp/WEB-INF/forrest-core.xconf
</p>
- <p>Responsiveness can be further enhanced by utilising a transparent proxy server, e.g. Apache HTTP Server as a frontend. See <link href="http://wiki.apache.org/cocoon/ApacheModProxy">CocoonAndApacheModProxy</link>.
+ <p>
+ Responsiveness can be further enhanced by utilising a transparent
+ proxy server, e.g. Apache HTTP Server as a frontend. See
+ <link href="http://wiki.apache.org/cocoon/ApacheModProxy">CocoonAndApacheModProxy</link>.
</p>
</section><section id="proxy_config"><title>3.3. I'm behind a proxy and it's preventing Plugins from being downloaded, what should I
do?</title>
- <p>You can configure the proxy in the <code>forrest.properties</code> file. Set the
- <code>proxy.host</code> and <code>proxy.port</code> accordingly.</p>
- <p>You can also cross an authenticated proxy by setting the <code>proxy.user</code> and <code>proxy.password</code> accordingly.</p>
- <note label="Generalise the proxy configuration">You certainly need to cross your proxy for every Forrest projects you have.
- To avoid to edit every project <code>forrest.properties</code> files, you can do once in your <code>${user.home}/forrest.properties</code> !</note>
+ <p>
+ You can configure the proxy in the <code>forrest.properties</code>
+ file. Set the <code>proxy.host</code> and <code>proxy.port</code>
+ accordingly.
+ </p>
+ <p>
+ You can also cross an authenticated proxy by setting the
+ <code>proxy.user</code> and <code>proxy.password</code> accordingly.
+ </p>
+ <note label="Generalise the proxy configuration">
+ You certainly need to cross your proxy for every Forrest projects you
+ have. To avoid to edit every project <code>forrest.properties</code>
+ files, you can do once in your
+ <code>${user.home}/forrest.properties</code> !
+ </note>
</section><section id="CVS_revison_tags"><title>3.4. How can I generate html-pages to show the Revision tag of CVS or SVN?</title>
- <p>If you have:<code><version>$Revision: 1.30
+ <p>
+ If you have:<code><version>$Revision: 1.30
$</version></code>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 <link href="site:your-project"> Using Forrest</link> 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 <link href="site:your-project"> Using
+ Forrest</link> document.
+ </p>
<p>
- When using Subversion, remember to set the relevant svn:keywords properties.
+ This technique could also be used for a modification date with $Date:
+ 2004/01/15 08:52:47 $
+ </p>
+ <p>
+ When using Subversion, remember to set the relevant svn:keywords
+ properties.
</p>
</section><section id="cli-xconf"><title>3.5. How to control the processing of URIs by Cocoon, e.g. exclude certain URIs, include
other additional ones. </title>
- <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 <code>cli.xconf</code> and define patterns for URIs to
- exclude. There are also other powerful configuration features. </p>
- <p> This means creating a directory <code>src/documentation/conf</code> (or wherever
- <code>${forrest.conf-dir}</code> points) and copying
- <code>$FORREST_HOME/main/webapp/WEB-INF/cli.xconf</code> to it. Declare the location of
- this file in the forrest.properties configuration, e.g.
- <code>project.configfile=${project.home}/src/documentation/conf/cli.xconf</code>
+ <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 <code>cli.xconf</code> and define
+ patterns for URIs to exclude. There are also other powerful
+ configuration features.
+ </p>
+ <p>
+ This means creating a directory <code>src/documentation/conf</code>
+ (or wherever <code>${forrest.conf-dir}</code> points) and copying
+ <code>$FORREST_HOME/main/webapp/WEB-INF/cli.xconf</code> to it.
+ Declare the location of this file in the forrest.properties
+ configuration, e.g.
+ <code>project.configfile=${project.home}/src/documentation/conf/cli.xconf</code>
+ </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>
<source xml:space="preserve">
+
....
<!-- 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></source>
- <p>This is just an example, and you should modify it appropriately for your site.</p>
- <note> Wildcards may be used. These are a powerful feature of Cocoon's <link href="site:sitemap-ref">sitemap</link>. For example, <strong>foo/*</strong> would match
- <code>foo/bar</code>, but not <code>foo/bar/baz</code> — use
- <strong>foo/**</strong> to match that. </note>
+</cocoon>
+ </source>
+ <p>
+ This is just an example, and you should modify it appropriately for
+ your site.
+ </p>
+ <note>
+ Wildcards may be used. These are a powerful feature of Cocoon's
+ <link href="site:sitemap-ref">sitemap</link>. For example,
+ <strong>foo/*</strong> would match <code>foo/bar</code>, but not
+ <code>foo/bar/baz</code> — use <strong>foo/**</strong> to match
+ that.
+ </note>
</section><section id="ignoring_javadocs"><title>3.6. How do I stop Forrest breaking on links to external files that may not exist, like
javadocs? </title>
- <p> This can be done by overriding the <link href="#cli-xconf">
- <code>cli.xconf</code>
- </link> Cocoon config file, and defining patterns for URLs to exclude. </p>
+ <p>
+ This can be done by overriding the <link href="#cli-xconf">
+ <code>cli.xconf</code> </link> Cocoon config file, and defining
+ patterns for URLs to exclude.
+ </p>
</section><section id="claimed_patterns"><title>3.7. Some of my files are not being processed because they use common filenames. </title>
- <p> Certain patterns are claimed by the default sitemaps for special processing. These reserved words
- include: <code>site, changes, todo, faq, images, my-images, skinconf, community,
- howto</code>
- </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 (<link href="http://issues.apache.org/jira/browse/FOR-217">FOR-217</link>).
+ <p>
+ Certain patterns are claimed by the default sitemaps for special
+ processing. These reserved words include: <code>site, changes, todo,
+ faq, images, my-images, skinconf, community, howto</code>
+ </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
+ (<link href="http://issues.apache.org/jira/browse/FOR-217">FOR-217</link>).
</p>
</section><section id="build_msg_a"><title>3.8. What do the symbols and numbers mean when Forrest lists each document that it has
built? </title>
<p>
- Each time that Cocoon processes a link, it will report the status messages ...
+ Each time that Cocoon processes a link, it will report the status
+ messages ...
</p>
- <source xml:space="preserve">...
+ <source xml:space="preserve">
+...
* [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
-...</source>
+...
+ </source>
<ul>
<li>Column 1 is the page build status (*=okay X=brokenLink ^=pageSkipped).</li>
<li>Column 2 is the page count (pagesComplete/pagesRemaining). The latter will change because during processing one page, Cocoon will discover more.</li>
@@ -600,29 +786,39 @@
</ul>
</section><section id="headless_operation"><title>3.9. 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. </title>
- <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>
+ <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 xml:space="preserve">forrest -Dforrest.jvmargs=-Djava.awt.headless=true site</source>
- <p> See also <link href="http://cocoon.apache.org/2.1/faq/faq-configure-environment.html">Cocoon FAQ</link>. </p>
+ <p>
+ See also
+ <link href="http://cocoon.apache.org/2.1/faq/faq-configure-environment.html">Cocoon
+ FAQ</link>.
+ </p>
</section><section id="project-logo-svg"><title>3.10.
The project logo that is generated from SVG is truncating my project name.
</title>
<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
- <code><project-name></code> and
- <code><group-name></code> elements of the <code>skinconf.xml</code> 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
+ <code><project-name></code> and <code><group-name></code>
+ elements of the <code>skinconf.xml</code> 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
- <code>src/documentation/content/xdocs/images/project.svg</code> and adjust the "width"
- attribute of the <svg> element. For further details see
- <link href="http://www.w3.org/Graphics/SVG/">SVG</link> resources.
+ <code>src/documentation/content/xdocs/images/project.svg</code> and
+ adjust the "width" attribute of the <svg> element. For further
+ details see <link href="http://www.w3.org/Graphics/SVG/">SVG</link>
+ resources.
</p>
</section><section id="catalog"><title>3.11. How do i configure my favourite XML editor or parser to find the local Forrest
DTDs? </title>
- <p> Notes are provided for various tools at <link href="site:catalog">Using Catalog Entity
- Resolver for local DTDs</link>. </p>
+ <p>
+ Notes are provided for various tools at
+ <link href="site:catalog">Using Catalog Entity Resolver for local
+ DTDs</link>.
+ </p>
</section><section id="project-dtd"><title>3.12. How to configure the Catalog Entity Resolver to use my own local project DTDs?</title>
<p>
See <link href="site:your-project/new_dtd">Using Forrest</link> for
@@ -638,127 +834,178 @@
See <link href="site:validation/debug-catalog">XML validation</link>.
</p>
</section><section id="skin"><title>3.15. How to make the site look better and change its skin? </title>
- <p> There are <link href="site:skins">default skins</link> 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 <link href="site:your-project/skins">configuration</link> of the skins.
- Some projects may have special needs and can define their <link href="site:your-project/new-skin">own skin</link>. </p>
+ <p>
+ There are <link href="site:skins">default skins</link> 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
+ <link href="site:your-project/skins">configuration</link> of the
+ skins. Some projects may have special needs and can define their
+ <link href="site:your-project/new-skin">own skin</link>.
+ </p>
</section><section id="xsp"><title>3.16. How do I enable <acronym title="eXtensible Server Pages">XSP</acronym> processing?</title>
- <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 <link href="http://svn.apache.org/repos/asf/cocoon/trunk/lib/optional/">jdtcore-*.jar</link> from Cocoons SVN tree, 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 <link href="site:project-sitemap">project sitemap</link>
+ <li><p>
+ Add the following generator definition in the map:generators
+ section of your
+ <link href="site:project-sitemap">project
+ sitemap</link>
</p>
<source xml:space="preserve">
+
<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>
+ 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 xml:space="preserve">
+
<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>
+</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.apache.org/cocoon/AddingXSPToForrest">AddingXSPToForrest</link> Wiki page.</p>
+ <p>
+ See also the
+ <link href="http://wiki.apache.org/cocoon/AddingXSPToForrest">AddingXSPToForrest</link>
+ Wiki page.
+ </p>
</section><section id="breadcrumbs"><title>3.17. How do breadcrumbs work? Why don't they work locally?</title>
- <p>Breadcrumbs begin with up to three URLs specified in <code>skinconf.xml</code>. Here is
- what the Forrest site uses:</p>
+ <p>
+ Breadcrumbs begin with up to three URLs specified in
+ <code>skinconf.xml</code>. Here is what the Forrest site uses:
+ </p>
<source xml:space="preserve">
+
<trail>
<link1 name="apache" href="http://www.apache.org/"/>
<link2 name="xml.apache" href="http://xml.apache.org/"/>
<link3 name="" href=""/>
- </trail></source>
- <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 <code>skinconf.xml</code>. </p>
+ </trail>
+ </source>
+ <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 <code>skinconf.xml</code>.
+ </p>
</section><section id="run_port"><title>3.18. How do I make <code>forrest run</code> listen on a different port?</title>
<p>
<code>forrest run -Dforrest.jvmargs="-Djetty.port=80"</code>
</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 <code>forrest run</code>
+ <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 <code>forrest run</code>
</p>
</section><section id="debugging"><title>3.19. Can I run Forrest with Java debugging turned on?</title>
- <p>If you use an IDE like Eclipse and want to debug java code in Forrest
- you need to start Forrest with debugging mode turned on. To do this you need
- to add <code>-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,susp end=n</code>
- to the <code>forrest.jvmargs</code> property in the <code>forrest.properties</code>
- file. Don't forget to ensure the property is uncommented in that file.</p>
+ <p>
+ If you use an IDE like Eclipse and want to debug java code in Forrest
+ you need to start Forrest with debugging mode turned on. To do this
+ you need to add <code>-Xdebug
+ -Xrunjdwp:transport=dt_socket,address=8000,server=y,susp end=n</code>
+ to the <code>forrest.jvmargs</code> property in the
+ <code>forrest.properties</code> file. Don't forget to ensure the
+ property is uncommented in that file.
+ </p>
</section><section id="checksums"><title>3.20. How do I enable Cocoon's document checksum feature?</title>
<p>
- Why might you want to do this? There is really no effect
- on Cocoon processing, but a little time can be
- saved on filesystem writes, which will accumulate
- to a big savings for a site with thousands of files.
- </p>
- <p>
- Some tools depend on the "date-last-modified" timestamp of the generated files.
- For example, the Forrestbot will then deploy only the modified files.
- </p>
- <p>
- There was some discussion about this on the Forrest developer mailing
- list:
- <link href="http://marc.theaimsgroup.com/?l=forrest-dev&s=cocoon+checksum">Cocoon Checksum</link>
- Specifically note that this feature only stops Cocoon from writing to
- disk if the new file is the same as the existing file. Cocoon still spends
- the same amount of time generating the content as it would if checksums
- were not enabled.
- </p>
- <p>
- Locate the <code>checksums-uri</code> tag within cli.xconf and replace
- the contents with an absolute path and filename for the checksums file.
- Projects can supply their own (see FAQ:
- <link href="#cli-xconf">Cocoon cli.xconf</link>) or use the default
- installation-wide cli.xconf file.
+ Why might you want to do this? There is really no effect on Cocoon
+ processing, but a little time can be saved on filesystem writes, which
+ will accumulate to a big savings for a site with thousands of files.
+ </p>
+ <p>
+ Some tools depend on the "date-last-modified" timestamp of the
+ generated files. For example, the Forrestbot will then deploy only the
+ modified files.
+ </p>
+ <p>
+ There was some discussion about this on the Forrest developer mailing
+ list:
+ <link href="http://marc.theaimsgroup.com/?l=forrest-dev&s=cocoon+checksum">Cocoon
+ Checksum</link> Specifically note that this feature only stops Cocoon
+ from writing to disk if the new file is the same as the existing file.
+ Cocoon still spends the same amount of time generating the content as
+ it would if checksums were not enabled.
+ </p>
+ <p>
+ Locate the <code>checksums-uri</code> tag within cli.xconf and replace
+ the contents with an absolute path and filename for the checksums
+ file. Projects can supply their own (see FAQ:
+ <link href="#cli-xconf">Cocoon cli.xconf</link>) or use the default
+ installation-wide cli.xconf file.
</p>
</section></section><section id="old_faqs"><title>4. Older version: 0.6</title><section id="old_claimed_patterns"><title>4.1. Some of my files are not being processed because they use common filenames. </title>
- <p> Certain patterns are claimed by the default sitemaps for special processing. These
- include: <code>site, changes, todo, faq, images, my-images, skinconf, community,
- howto</code>
- </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 (<link href="http://issues.apache.org/jira/browse/FOR-217">FOR-217</link>).
+ <p>
+ Certain patterns are claimed by the default sitemaps for special
+ processing. These include: <code>site, changes, todo, faq, images,
+ my-images, skinconf, community, howto</code>
+ </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
+ (<link href="http://issues.apache.org/jira/browse/FOR-217">FOR-217</link>).
</p>
</section></section><section id="general"><title>5. General</title><section id="generating_menus"><title>5.1. What is the relationship between <code>site.xml</code> and <code>book.xml</code>? </title>
- <p> One <code>site.xml</code> file in your project root can replace all the book.xml files (one per
- directory) in your site. Internally, Forrest uses <code>site.xml</code> 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
- <code>site.xml</code>-generated menus aren't appropriate. See <link href="site:linking">Menus and
- Linking</link>. </p>
+ <p>
+ One <code>site.xml</code> file in your project root can replace all the book.xml files
+ (one per directory) in your site. Internally, Forrest uses <code>site.xml</code> 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 <code>site.xml</code>-generated menus aren't appropriate. See
+ <link href="site:linking">Menus and Linking</link>.
+ </p>
</section><section id="docbook"><title>5.2. How do I use DocBook as the XML documentation format? </title>
- <p> There are two ways. Forrest has a <code>simplifiedDocbook</code> 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 <link href="site:project-sitemap">project
- sitemap</link> as explained in <link href="site:your-project">Using Forrest</link> 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>
- <source xml:space="preserve"><?xml version="1.0"?>
+ <p>
+ There are two ways. Forrest has a <code>simplifiedDocbook</code>
+ 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
+ <link href="site:project-sitemap">project sitemap</link> as explained
+ in <link href="site:your-project">Using Forrest</link> 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>
+ <source xml:space="preserve">
+<?xml version="1.0"?>
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
<map:pipelines>
<map:pipeline>
@@ -770,27 +1017,31 @@
</map:match>
</map:pipeline>
</map:pipelines>
-</map:sitemap></source>
- <p>You need to define the xhtml serializer used in <map:serialize type="xhtml"/>
- in the components section of the sitemap. See the
- <link href="http://cocoon.apache.org/2.1/userdocs/serializers/xhtml-serializer.html">Cocoon
- docs</link> for the elements you need to add to define this component. You can see examples
- of other components being added in the <code>FORREST_HOME/main/webapp/sitemap.xmap</code> file.
- Alternatively use the "html" DocBook stylesheets and the default Cocoon serializer,
- i.e. <map:serialize type="html"/>
- </p>
- <p>
- The output of the above sitemap will be plain html not adorned with
- a Forrest theme and navigation. If instead you need the latter, then
- use the following technique instead. This transforms DocBook xml to
- html, then uses a Forrest core stylesheet to transform and serialize
- to the internal xml format, then the normal machinery takes over and
- does the output transformation. This use the Content Aware Pipelines
- (<link href="site:cap">SourceTypeAction</link>)
- to peek at the source xml. If it is DocBook-4.2
- then this sitemap match is triggered, if not then it falls through to the core of Forrest.
+</map:sitemap>
+ </source>
+ <p>
+ You need to define the xhtml serializer used in <map:serialize
+ type="xhtml"/> in the components section of the sitemap. See the
+ <link href="http://cocoon.apache.org/2.1/userdocs/serializers/xhtml-serializer.html">Cocoon
+ docs</link> for the elements you need to add to define this component.
+ You can see examples of other components being added in the
+ <code>FORREST_HOME/main/webapp/sitemap.xmap</code> file. Alternatively
+ use the "html" DocBook stylesheets and the default Cocoon serializer,
+ i.e. <map:serialize type="html"/>
+ </p>
+ <p>
+ The output of the above sitemap will be plain html not adorned with a
+ Forrest theme and navigation. If instead you need the latter, then use
+ the following technique instead. This transforms DocBook xml to html,
+ then uses a Forrest core stylesheet to transform and serialize to the
+ internal xml format, then the normal machinery takes over and does the
+ output transformation. This use the Content Aware Pipelines
+ (<link href="site:cap">SourceTypeAction</link>) to peek at the source
+ xml. If it is DocBook-4.2 then this sitemap match is triggered, if not
+ then it falls through to the core of Forrest.
</p>
- <source xml:space="preserve"><?xml version="1.0"?>
+ <source xml:space="preserve">
+<?xml version="1.0"?>
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
<map:components>
<map:actions>
@@ -825,59 +1076,88 @@
</map:match>
</map:pipeline>
</map:pipelines>
-</map:sitemap></source>
- <p> You can also use a mixture of the 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 <link href="site:your-project/new_dtd">Using Forrest</link> for
- configuration guidance. </p>
+</map:sitemap>
+ </source>
+ <p>
+ You can also use a mixture of the 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
+ <link href="site:your-project/new_dtd">Using Forrest</link> for
+ configuration guidance.
+ </p>
</section><section id="version"><title>5.3. How to report which version of Forrest is being used and the properties that are
set? </title>
- <p> Do <code>'forrest -projecthelp'</code> or <code>'./build.sh'</code> 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 <code>'forrest -v'</code> will provide verbose build
- messages. </p>
+ <p>
+ Do <code>'forrest -projecthelp'</code> or <code>'./build.sh'</code> 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
+ <code>'forrest -v'</code> will provide verbose build messages.
+ </p>
</section><section id="logs"><title>5.4. Where are the log files to find more infomation about errors? </title>
- <p> The logfiles are at <code>build/webapp/WEB-INF/logs/</code>
+ <p>
+ The logfiles are at <code>build/webapp/WEB-INF/logs/</code>
</p>
- <p> The log level can be raised with the <code>logkit.xconf</code> configuration. If you are
- using Forrest in the interactive webapp mode (which is generally easiest for debugging
- errors) then see the <code>main/webapp/WEB-INF/logkit.xconf</code> file. If you are
+ <p>
+ The log level can be raised with the <code>logkit.xconf</code>
+ configuration. If you are using Forrest in the interactive webapp mode
+ (which is generally easiest for debugging errors) then see the
+ <code>main/webapp/WEB-INF/logkit.xconf</code> file. If you are
generating a static site (with command-line 'forrest') then copy
- <code>$FORREST_HOME/main/webapp/WEB-INF/logkit.xconf</code> to your project at
- <code>src/documentation/conf/logkit.xconf</code> and modify it. See more
- information and efficiency tips with <link href="http://wiki.apache.org/cocoon/ExploringTheLogs">Cocoon logging</link>. </p>
- <p> Doing <code>'forrest -v'</code> will provide verbose build messages to the standard
- output. </p>
+ <code>$FORREST_HOME/main/webapp/WEB-INF/logkit.xconf</code> to your
+ project at <code>src/documentation/conf/logkit.xconf</code> and modify
+ it. See more information and efficiency tips with
+ <link href="http://wiki.apache.org/cocoon/ExploringTheLogs">Cocoon
+ logging</link>.
+ </p>
+ <p>
+ Doing <code>'forrest -v'</code> will provide verbose build messages to
+ the standard output.
+ </p>
</section><section id="how_can_I_help"><title>5.5. How to help? </title>
- <p> Join one of the Forrest project <link href="site:mail-lists">mailing lists</link> 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 <link href="site:mail-lists">mailing
+ lists</link> 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>
</section><section id="patch"><title>5.6. How to contribute a patch? </title>
- <p>Please send all contributions via our <link href="site:bugs">issue tracker</link>. Here
- are notes about <link href="site:contrib/patch">making patches</link>. </p>
- <p>More info about contributing can be found at the <link href="site:contrib">Contributing
- to Forrest</link> page. It is always a good idea to check the Forrest <link href="site:bugs">issue tracker</link> before diving in. </p>
+ <p>
+ Please send all contributions via our <link href="site:bugs">issue
+ tracker</link>. Here are notes about
+ <link href="site:contrib/patch">making patches</link>.
+ </p>
+ <p>
+ More info about contributing can be found at the
+ <link href="site:contrib">Contributing to Forrest</link> page. It is
+ always a good idea to check the Forrest
+ <link href="site:bugs">issue tracker</link> before diving
+ in.
+ </p>
</section><section id="jobs"><title>5.7. How can job positions be advertised? </title>
<p>
- Employers can send notices about employment opportunities.
- There is a special jobs<AT>apache.org mailing list.
- You can also send these notices to the project mailing lists,
- e.g. dev list at Forrest or Cocoon (add [jobs] to the subject line).
- You can also approach particular developers off-list. However only
- genuine jobs, not pleas for free support (see
- <link href="site:mail-lists">mailing lists</link>).
+ Employers can send notices about employment opportunities. There is a
+ special jobs<AT>apache.org mailing list. You can also send these
+ notices to the project mailing lists, e.g. dev list at Forrest or
+ Cocoon (add [jobs] to the subject line). You can also approach
+ particular developers off-list. However only genuine jobs, not pleas
+ for free support (see <link href="site:mail-lists">mailing
+ lists</link>).
</p>
<p>
Some enlightened employers enable their employees to contribute
material which was created during work time using work-related
resources. Please note the need to file a Corporate Contributor
License Agreement
- (<link href="http://www.apache.org/licenses/">CCLA</link>)
- with The Apache Software Foundation.
+ (<link href="http://www.apache.org/licenses/">CCLA</link>) with The
+ Apache Software Foundation.
</p>
</section></section></section></body></document>