blob: 40dcbc727947a2b672a5af41497ea56d321cd217 [file] [log] [blame]
<?xml version="1.0" encoding="ISO-8859-1"?><!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
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.
</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>
</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.
</p>
<p>
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>.
</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>
<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.
</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>
</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>
</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
<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.
</p>
<source xml:space="preserve">project.required.plugins=org.apache.forrest.plugin.input.PhotoGallery-0.1,...</source>
<p>
Users of Forrest-0.7 will need to do this for the projectInfo plugin
if you get the following error ...
</p>
<source xml:space="preserve">Could not find component for role:
[org.apache.cocoon.components.modules.input.InputModule/lm]
(Key='org.apache.cocoon.components.modules.input.InputModule/</source>
<p>
... then sorry, we mistakenly added new "locationmap" functionality
(due in version 0.8). So do this ...
</p>
<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 ...
</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
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.
</p>
<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.
</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.
</p>
<p>
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'.
</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>
</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
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>
</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>
</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>
</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:
</p>
<p>
The labels can be whatever text you want.
</p>
<source xml:space="preserve">
&lt;faq label="FAQs" href="faq.html"&gt;
&lt;tech label="Technical" href="faq-tech.html"&gt;
&lt;docbook href="#docbook"/&gt;
&lt;ignoring_javadocs href="#ignoring_javadocs"/&gt;
&lt;/tech&gt;
&lt;user label="User" href="faq-user.html"&gt;
&lt;/faq&gt;
</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">
&lt;a href="site:faq/tech"&gt; link to the top of the Tech FAQs
&lt;a href="site:faq/tech/docbook"&gt; 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">
&lt;a href="site:docbook"&gt; 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>).
</p>
</section><section id="crawler"><title>2.4.
Help, one of my documents is not being rendered.
</title>
<p>
Did you make a link to it? Forrest does not find documents by scanning
the filesystem to find the source documents. Rather it starts at one
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.
</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.
</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>
<source xml:space="preserve">
&lt;about tab="home" label="About" href=""&gt;
...
&lt;all_site label="Full HTML" href="wholesite.html"/&gt;
&lt;all_sitePDF label="Full PDF" href="wholesite.pdf"/&gt;
...
&lt;/about&gt;
</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>
<source xml:space="preserve">
.pageBreakBefore {
margin-bottom: 0;
page-break-before: always;
}
.pageBreakAfter {
margin-bottom: 0;
page-break-after: always;
} </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>
</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>
</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>
<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>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>
</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>
<source xml:space="preserve">
&lt;tab label="User Manual" href="manual"/&gt;
</source>
<p>
and add this rule to the sitemap:
</p>
<source xml:space="preserve">
&lt;map:match pattern="manual"&gt;
&lt;map:redirect-to uri="manual/Introduction.html"/&gt;
&lt;/map:match&gt;
</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>
<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
&lt;default-filename&gt;index.html&lt;/default-filename&gt;
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">
&lt;map:pipeline&gt;
&lt;map:match type="regexp" pattern="^.+/$"&gt;
&lt;map:redirect-to uri="overview.html"/&gt;
&lt;/map:match&gt;
&lt;/map:pipeline&gt;
</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>
<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">
&lt;map:pipeline&gt;
&lt;map:match pattern=""&gt;
&lt;map:redirect-to uri="start.html" /&gt;
&lt;/map:match&gt;
&lt;/map:pipeline&gt;
</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>
&amp;ouml;
</code> use <code>
&amp;#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>
</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>
<ul>
<li>accents: á é í ó ú</li>
<li>diereses: ä ë ï ö ü</li>
<li>tildes: ã ñ &#297; õ &#361;</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">
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
</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">
&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
</source>
<p>
Another option is to use "character entities" such as <code>
&amp;ouml;
</code> (ö) or the numeric form <code>
&amp;#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>&amp;myp-t;</code>" to represent the project name together with
trademark symbol "My Project Name&#8482;". 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>
By default Forrest does not clean its build directories in the project
workspaces. This enables Cocoon to use its disk cache to speed up
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.
</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>
</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>
<source xml:space="preserve">
&lt;map:match pattern="old_site/**.html"&gt;
&lt;map:select type="exists"&gt;
&lt;map:when test="{properties:content}{0}"&gt;
&lt;map:read src="{properties:content}/{0}" mime-type="text/html"/&gt;
&lt;!--
Use this instead if you want JTidy to clean up your HTML
&lt;map:generate type="html" src="{properties:content}/{0}" /&gt;
&lt;map:serialize type="html"/&gt;
--&gt;
&lt;/map:when&gt;
&lt;/map:select&gt;
&lt;/map:match&gt;
</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>
<ol>
<li>mkdir seed</li>
<li>cd seed</li>
<li>forrest seed-sample</li>
<li>forrest</li>
<li><code>http://localhost:8888/samples/linking.html#no-decoration</code></li>
</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.
</p>
<p>
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 &lt;map:resource name="skin-read"&gt; 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.
</p>
<p>
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>"
</p>
<p>
This is also the document that 'forrest site' uses to kick-start the
Cocoon crawler which then follows links to build each page. See the
project.start-uri in the forrest.properties file.
</p>
</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.
</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.
</p>
<p>
That said, you will find some Java code in Forrest at main/java/...
for Cocoon components that have been developed at Forrest, e.g.
Locationmap and Dispatcher. There is also Java code for some plugins
with specialised purpose, e.g. PhotoGallery.
</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.
</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://wiki.apache.org/cocoon/CocoonPerformance">CocoonPerformance</link>
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>
</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>
</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>&lt;version&gt;$Revision: 1.30
$&lt;/version&gt;</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>
<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>
<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">
....
&lt;!-- Includes and excludes can be used to limit which URLs are rendered --&gt;
<strong>
&lt;exclude pattern="**/"/&gt;
&lt;exclude pattern="**apidocs**"/&gt;
&lt;exclude pattern="api/**"/&gt;
</strong>
&lt;uri src="favicon.ico"/&gt;
&lt;/cocoon&gt;
</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> &#8212; 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>
</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>
</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 ...
</p>
<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>
<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>
<li>Column 3 is the number of links that were gathered from that page (newLinksInPage/linksInPage).</li>
<li>Column 4 is the time taken.</li>
<li>Column 5 is the page size.</li>
</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>
<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>
</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>&lt;project-name&gt;</code> and <code>&lt;group-name&gt;</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 &lt;svg&gt; 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>
</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
configuration guidance.
</p>
</section><section id="local-catalog"><title>3.13. We need an additional system-wide catalog to share DTDs between projects</title>
<p>
See <link href="site:validation/catalog">Using Forrest</link> for
configuration guidance.
</p>
</section><section id="debug-catalog"><title>3.14. How to debug the Catalog Entity Resolver and local DTDs?</title>
<p>
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>
</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>
<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>
</p>
<source xml:space="preserve">
&lt;map:generator name="serverpages"
pool-grow="2" pool-max="32" pool-min="4"
src="org.apache.cocoon.generation.ServerPagesGenerator"/&gt;
</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">
&lt;map:match pattern="dynamic.xml"&gt;
&lt;map:generate src="content/xdocs/dynamic.xsp" type="serverpages"/&gt;
...
&lt;map:serialize type="xml"/&gt;
&lt;/map:match&gt;
</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>
</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>
<source xml:space="preserve">
&lt;trail&gt;
&lt;link1 name="apache" href="http://www.apache.org/"/&gt;
&lt;link2 name="xml.apache" href="http://xml.apache.org/"/&gt;
&lt;link3 name="" href=""/&gt;
&lt;/trail&gt;
</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>
</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>
</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&amp;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>
</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>
</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">
&lt;?xml version="1.0"?&gt;
&lt;map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0"&gt;
&lt;map:pipelines&gt;
&lt;map:pipeline&gt;
&lt;map:match pattern="resolver-*.html"&gt;
&lt;map:generate src="{properties:content.xdocs}resolver-{1}.xml"/&gt;
&lt;map:transform
src="file:///usr/share/sgml/docbook/xsl-stylesheets/xhtml/docbook.xsl"/&gt;
&lt;map:serialize type="xhtml"/&gt;
&lt;/map:match&gt;
&lt;/map:pipeline&gt;
&lt;/map:pipelines&gt;
&lt;/map:sitemap&gt;
</source>
<p>
You need to define the xhtml serializer used in &lt;map:serialize
type="xhtml"/&gt; 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. &lt;map:serialize type="html"/&gt;
</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">
&lt;?xml version="1.0"?&gt;
&lt;map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0"&gt;
&lt;map:components&gt;
&lt;map:actions&gt;
&lt;map:action logger="sitemap.action.sourcetype"
name="sourcetype"src="org.apache.forrest.sourcetype.SourceTypeAction"&gt;
&lt;sourcetype name="docbook-v4.2"&gt;
&lt;document-declaration public-id="-//OASIS//DTD DocBook XML V4.2//EN"/&gt;
&lt;/sourcetype&gt;
&lt;/map:action&gt;
&lt;/map:actions&gt;
&lt;map:selectors default="parameter"&gt;
&lt;map:selector logger="sitemap.selector.parameter"
name="parameter" src="org.apache.cocoon.selection.ParameterSelector"/&gt;
&lt;/map:selectors&gt;
&lt;/map:components&gt;
&lt;map:pipelines&gt;
&lt;map:pipeline&gt;
&lt;map:match pattern="**.xml"&gt;
&lt;map:act type="sourcetype" src="{properties:content.xdocs}{1}.xml"&gt;
&lt;map:select type="parameter"&gt;
&lt;map:parameter name="parameter-selector-test" value="{sourcetype}"/&gt;
&lt;map:when test="docbook-v4.2"&gt;
&lt;map:generate src="{properties:content.xdocs}{../1}.xml"/&gt;
&lt;map:transform
src="file:///usr/share/sgml/docbook/xsl-stylesheets/html/docbook.xsl"/&gt;
&lt;map:transform src="{forrest:forrest.stylesheets}/html-to-document.xsl"/&gt;
&lt;map:transform type="idgen"/&gt;
&lt;map:serialize type="xml-document"/&gt;
&lt;/map:when&gt;
&lt;/map:select&gt;
&lt;/map:act&gt;
&lt;/map:match&gt;
&lt;/map:pipeline&gt;
&lt;/map:pipelines&gt;
&lt;/map:sitemap&gt;
</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>
</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>
<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>
</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&#8212;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>
</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&lt;AT&gt;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.
</p>
</section></section></section></body></document>