Google Git
Sign in
apache / forrest / 175ec5292dee766761b512a6948e4b2c46e78c07 / . / docs_0_60 / faq.html
blob: 9ff668951990f4a3a958c6dab0d25161c5c68396 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta content="Apache Forrest" name="Generator">
<meta name="Forrest-version" content="0.8-dev">
<meta name="Forrest-skin-name" content="pelt">
<title>Frequently Asked Questions (v0.6)</title>
<link type="text/css" href="../skin/basic.css" rel="stylesheet">
<link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet">
<link media="print" type="text/css" href="../skin/print.css" rel="stylesheet">
<link type="text/css" href="../skin/profile.css" rel="stylesheet">
<script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script>
<link rel="shortcut icon" href="../favicon.ico">
</head>
<body onload="init()">
<script type="text/javascript">ndeSetTextSize();</script>
<div id="top">
<!--+
|breadtrail
+-->
<div class="breadtrail">
<a href="http://www.apache.org/">apache</a> &gt; <a href="http://forrest.apache.org/">forrest</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
</div>
<!--+
|header
+-->
<div class="header">
<!--+
|start group logo
+-->
<div class="grouplogo">
<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../images/apache-forrest.png" title="The Apache Software Foundation"></a>
</div>
<!--+
|end group logo
+-->
<!--+
|start Project Logo
+-->
<div class="projectlogo">
<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../images/project-logo.gif" title="Apache Forrest"></a>
</div>
<!--+
|end Project Logo
+-->
<!--+
|start Search
+-->
<div class="searchbox">
<form action="http://www.google.com/search" method="get" class="roundtopsmall">
<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">&nbsp;
<input name="Search" value="Search" type="submit">
</form>
</div>
<!--+
|end search
+-->
<!--+
|start Tabs
+-->
<ul id="tabs">
<li>
<a class="unselected" href="../index.html">Welcome</a>
</li>
<li>
<a class="unselected" href="../contrib.html">Developers</a>
</li>
<li class="current">
<a class="selected" href="../versions/index.html">Versioned Docs</a>
</li>
<li>
<a class="unselected" href="../pluginDocs/index.html">Plugins</a>
</li>
<li>
<a class="unselected" href="../tools/index.html">Tools</a>
</li>
</ul>
<!--+
|end Tabs
+-->
</div>
</div>
<div id="main">
<div id="publishedStrip">
<!--+
|start Subtabs
+-->
<div id="level2tabs">
<a class="unselected" href="../docs_0_70/index.html">0.70 (current)</a><a class="unselected" href="../docs_0_80/index.html">0.80-dev (under development)</a><a class="selected" href="../docs_0_60/index.html">0.60 (past)</a>
</div>
<!--+
|end Endtabs
+-->
<script type="text/javascript"><!--
document.write("Last Published: " + document.lastModified);
// --></script>
</div>
<!--+
|breadtrail
+-->
<div class="breadtrail">
&nbsp;
</div>
<!--+
|start Menu, mainarea
+-->
<!--+
|start Menu
+-->
<div id="menu">
<div onclick="SwitchMenu('menu_selected_1.1', '../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">0.60</div>
<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
<div class="menuitem">
<a href="../docs_0_60/index.html">Overview</a>
</div>
<div class="menupage">
<div class="menupagetitle">FAQs</div>
</div>
<div class="menuitem">
<a href="../docs_0_60/changes.html">Changes</a>
</div>
<div class="menuitem">
<a href="../docs_0_60/todo.html">Todo</a>
</div>
<div class="menuitem">
<a href="../docs_0_60/your-project.html">Using Forrest</a>
</div>
<div class="menuitem">
<a href="../docs_0_60/upgrading_06.html">Upgrading to 0.6</a>
</div>
<div class="menuitem">
<a href="../docs_0_60/validation.html">XML Validation</a>
</div>
<div class="menuitem">
<a href="../docs_0_60/linking.html">Menus and Linking</a>
</div>
<div class="menuitem">
<a href="../docs_0_60/searching.html">Searching</a>
</div>
<div class="menuitem">
<a href="../docs_0_60/skins.html">Default Skins</a>
</div>
<div class="menuitem">
<a href="../docs_0_60/skin-package.html">Skin Packages</a>
</div>
<div class="menuitem">
<a href="../docs_0_60/forrest-contract.html">Our Contract</a>
</div>
<div class="menuitem">
<a href="../docs_0_60/compliance.html">Standards Compliance</a>
</div>
<div onclick="SwitchMenu('menu_1.1.14', '../skin/')" id="menu_1.1.14Title" class="menutitle">How-To</div>
<div id="menu_1.1.14" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_60/howto/index.html">Overview</a>
</div>
<div class="menuitem">
<a href="../docs_0_60/howto/howto-howto.html">Single Page</a>
</div>
<div onclick="SwitchMenu('menu_1.1.14.3', '../skin/')" id="menu_1.1.14.3Title" class="menutitle">Multi-Page</div>
<div id="menu_1.1.14.3" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_60/howto/multi/howto-multi.html">Intro</a>
</div>
<div class="menuitem">
<a href="../docs_0_60/howto/multi/step1.html">Step 1</a>
</div>
<div class="menuitem">
<a href="../docs_0_60/howto/multi/step2.html">Step 2</a>
</div>
<div class="menuitem">
<a href="../docs_0_60/howto/multi/step3.html">Step 3</a>
</div>
</div>
<div class="menuitem">
<a href="../docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.html">With Images</a>
</div>
<div class="menuitem">
<a href="../docs_0_60/howto/howto-howto.html">Write a How-to</a>
</div>
<div class="menuitem">
<a href="../docs_0_60/howto/howto-asf-mirror.html">Download mirror</a>
</div>
<div class="menuitem">
<a href="../docs_0_60/howto/howto-pdf-tab.html">Create tab PDF</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.1.15', '../skin/')" id="menu_1.1.15Title" class="menutitle">Advanced Topics</div>
<div id="menu_1.1.15" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_60/build.html">Building Forrest</a>
</div>
<div class="menuitem">
<a href="../docs_0_60/catalog.html">Using DTD Catalogs</a>
</div>
<div class="menuitem">
<a href="../docs_0_60/sitemap-ref.html">Sitemap Reference</a>
</div>
<div class="menuitem">
<a href="../docs_0_60/project-sitemap.html">Project sitemap</a>
</div>
<div class="menuitem">
<a href="../docs_0_60/cap.html">Sourcetype Action</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.1.16', '../skin/')" id="menu_1.1.16Title" class="menutitle">Reference docs</div>
<div id="menu_1.1.16" class="menuitemgroup">
<div onclick="SwitchMenu('menu_1.1.16.1', '../skin/')" id="menu_1.1.16.1Title" class="menutitle">DTD documentation</div>
<div id="menu_1.1.16.1" class="menuitemgroup">
<div class="menuitem">
<a href="../dtdx/dtd-docs.html">Overview</a>
</div>
<div class="menuitem">
<a href="../dtdx/document-v20.dtdx.html">document-v20</a>
</div>
<div class="menuitem">
<a href="../dtdx/howto-v20.dtdx.html">howto-v20</a>
</div>
<div class="menuitem">
<a href="../dtdx/faq-v20.dtdx.html">faq-v20</a>
</div>
<div class="menuitem">
<a href="../dtdx/document-v13.dtdx.html">document-v13</a>
</div>
<div class="menuitem">
<a href="../dtdx/howto-v13.dtdx.html">howto-v13</a>
</div>
<div class="menuitem">
<a href="../dtdx/faq-v13.dtdx.html">faq-v13</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.1.16.2', '../skin/')" id="menu_1.1.16.2Title" class="menutitle">Doc samples</div>
<div id="menu_1.1.16.2" class="menuitemgroup">
<div class="menuitem">
<a href="../dtdx/document-v13.html">document-v13</a>
</div>
<div class="menuitem">
<a href="../dtdx/document-v20.html">document-v20</a>
</div>
</div>
</div>
</div>
<div id="credit">
<hr>
This is documentation for past version v0.6
(<a href="http://forrest.apache.org/versions/">More</a>)</div>
<div id="roundbottom">
<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
<!--+
|alternative credits
+-->
<div id="credit2">
<a href="http://apachecon.com/2007/EU/"><img border="0" title="ApacheCon Europe 2007" alt="ApacheCon Europe 2007 - logo" src="http://apache.org/ads/ApacheCon/2007-europe-125x125.png" style="width: 125px;height: 125px;"></a><a href="http://people.apache.org/calendar.html#200711"><img border="0" title="ApacheCon US 2007" alt="ApacheCon US 2007 - logo" src="http://apache.org/ads/ApacheCon/2007-usa-125x125.png" style="width: 125px;height: 125px;"></a>
</div>
</div>
<!--+
|end Menu
+-->
<!--+
|start content
+-->
<div id="content">
<div title="Portable Document Format" class="pdflink">
<a class="dida" href="faq.pdf"><img alt="PDF -icon" src="../skin/images/pdfdoc.gif" class="skin"><br>
PDF</a>
</div>
<div class="trail">Font size:
&nbsp;<input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
&nbsp;<input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
&nbsp;<input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
</div>
<h1>Frequently Asked Questions</h1>
<div id="motd-area">
This is documentation for past version v0.6
(<a href="http://forrest.apache.org/versions/">More</a>)</div>
<div id="minitoc-area">
<ul class="minitoc">
<li>
<a href="#Questions">Questions</a>
<ul class="minitoc">
<li>
<a href="#getting_started">1. Getting Started and Building Forrest</a>
<ul class="minitoc">
<li>
<a href="#overview">1.1.
Where can i read an overview about how to work with Forrest?
</a>
</li>
<li>
<a href="#website-status">1.2.
Which version of Forrest does the website documentation relate to?
</a>
</li>
<li>
<a href="#requirements">1.3.
What are the system requirements for Forrest?
</a>
</li>
<li>
<a href="#cvs">1.4.
The old xml-forrest CVS code repository seems to be stale. What happened?
</a>
</li>
<li>
<a href="#svn">1.5.
How can I use SVN to keep up to date with the latest codebase?
</a>
</li>
<li>
<a href="#cygwin_mutex_error">1.6.
When running ./build.sh in cygwin, I get an error:
cygpath.exe: *** can't create title mutex, Win32 error 6.
</a>
</li>
<li>
<a href="#maxmemory">1.7.
How can I specify the amount of memory to be used by Java?
</a>
</li>
</ul>
</li>
<li>
<a href="#technical">2. Technical</a>
<ul class="minitoc">
<li>
<a href="#PDF-output">2.1. How can I generate one pdf-file out of
the whole site or selected pages of the site?</a>
</li>
<li>
<a href="#clickable-email-adress">2.2. How can I generate html-pages to show a
'clickable' email-address (of the author-element)?</a>
</li>
<li>
<a href="#CVS_revison_tags">2.3. How can I generate html-pages to show the
revision tag of cvs?</a>
</li>
<li>
<a href="#ignoring_javadocs">2.4.
How do I stop Forrest breaking on links to external files that may not
exist, like javadocs?
</a>
</li>
<li>
<a href="#link_raw">2.5. How do I link to raw files such as config.txt and brochure.pdf?
</a>
</li>
<li>
<a href="#claimed_patterns">2.6. Some of my files are not being processed because they use
common filenames.
</a>
</li>
<li>
<a href="#build_msg_a">2.7. What do the symbols and numbers mean when Forrest lists each
document that it has built?
</a>
</li>
<li>
<a href="#pdf_images">2.8. Images don't display in PDFs. How do I fix this?</a>
</li>
<li>
<a href="#index.html">2.9.
The tab link in my site incorrectly assumes that 'index.html' is present in
the linked-to directory. How do I fix this?
</a>
</li>
<li>
<a href="#headless_operation">2.10.
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.
</a>
</li>
<li>
<a href="#catalog">2.11.
How do i configure my favourite XML editor or parser to find the
local Forrest DTDs?
</a>
</li>
<li>
<a href="#label-entity">2.12.
How to use special characters in the labels of the site.xml file?
</a>
</li>
<li>
<a href="#skin">2.13.
How to make the site look better and change its skin?
</a>
</li>
<li>
<a href="#xsp">2.14. How do I enable XSP processing?</a>
</li>
<li>
<a href="#breadcrumbs">2.15. How do breadcrumbs work? Why don't they work locally?</a>
</li>
</ul>
</li>
<li>
<a href="#old_faqs">3. Older versions</a>
<ul class="minitoc">
<li>
<a href="#unresolved_project.home">3.1. When invoking Forrest 0.4 from the
forrest.antproxy.xml, the build fails because
${project.home} isn't resolved.
</a>
</li>
<li>
<a href="#odd_html">3.2.
After upgrading to 0.4 my HTML looks significantly different, and table
widths are wrong. What happened?
</a>
</li>
<li>
<a href="#validation_error-doctype_root_null">3.3.
When building my project, I get an validation error: Document root
element "site", must match DOCTYPE root "null"..
</a>
</li>
<li>
<a href="#building_error-custom_sitemap">3.4.
When building my project, I get any of these errors:
menu.xmap (The system cannot find the file specified)
static.xmap (The system cannot find the file specified)
Type 'xml-document' is not defined for 'serialize'
</a>
</li>
</ul>
</li>
<li>
<a href="#general">4. General</a>
<ul class="minitoc">
<li>
<a href="#generating_menus">4.1. What is the relationship between site.xml and
book.xml?
</a>
</li>
<li>
<a href="#docbook">4.2.
How do I use DocBook as the xml documentation format?
</a>
</li>
<li>
<a href="#version">4.3.
How to report which version of Forrest is being used and the
properties that are set?
</a>
</li>
<li>
<a href="#logs">4.4.
Where are the log files to find more infomation about errors?
</a>
</li>
<li>
<a href="#how_can_I_help">4.5.
How to help?
</a>
</li>
<li>
<a href="#patch">4.6.
How to contribute a patch?
</a>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<a name="N10008"></a><a name="Questions"></a>
<h2 class="underlined_10">Questions</h2>
<div class="section">
<a name="N1000C"></a><a name="getting_started"></a>
<h3 class="underlined_5">1. Getting Started and Building Forrest</h3>
<a name="N10010"></a><a name="overview"></a>
<h4 class="faq">1.1.
Where can i read an overview about how to work with Forrest?
</h4>
<div align="right">
<a href="#overview-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
See the <a href="../docs_0_60/your-project.html">Using Forrest</a> guide.
</p>
</div>
<a name="N1001C"></a><a name="website-status"></a>
<h4 class="faq">1.2.
Which version of Forrest does the website documentation relate to?
</h4>
<div align="right">
<a href="#website-status-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
The documentation on the Forrest website relates to the current
head development version of the source repository. See
<a href="index.html#status">further explanation</a>.
</p>
</div>
<a name="N10028"></a><a name="requirements"></a>
<h4 class="faq">1.3.
What are the system requirements for Forrest?
</h4>
<div align="right">
<a href="#requirements-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
Forrest includes everything necessary to build and run, except
of course for Java. In addition to all the Cocoon JARs, Forrest
includes and uses its own version of Ant. The
<a href="http://cocoon.apache.org/2.1/installing/requirements.html">Cocoon requirements</a>
indicate that Java 1.3+ is required.
</p>
</div>
<a name="N10034"></a><a name="cvs"></a>
<h4 class="faq">1.4.
The old xml-forrest CVS code repository seems to be stale. What happened?
</h4>
<div align="right">
<a href="#cvs-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
Forrest switched from a CVS code repository to SVN (subversion)
code repository. The old CVS repository is not kept current.
</p>
</div>
<a name="N1003C"></a><a name="svn"></a>
<h4 class="faq">1.5.
How can I use SVN to keep up to date with the latest codebase?
</h4>
<div align="right">
<a href="#svn-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
Follow these <a href="../docs_0_60/build.html">Building Forrest</a> notes.
</p>
<p>
The <a href="../docs_0_60/your-project.html">Using Forrest</a> guide provides
further step-by-step assistance in getting started with Forrest for your project.
</p>
</div>
<a name="N1004F"></a><a name="cygwin_mutex_error"></a>
<h4 class="faq">1.6.
When running ./build.sh in cygwin, I get an error:
cygpath.exe: *** can't create title mutex, Win32 error 6.
</h4>
<div align="right">
<a href="#cygwin_mutex_error-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
This
<a href="http://issues.cocoondev.org/secure/ViewIssue.jspa?key=FOR-10">appears
to be a bug in cygwin</a>. Please use the .bat script instead.
</p>
</div>
<a name="N10061"></a><a name="maxmemory"></a>
<h4 class="faq">1.7.
How can I specify the amount of memory to be used by Java?
</h4>
<div align="right">
<a href="#maxmemory-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
There are two ways to control this. If you get an OutOfMemoryError when Cocoon is generating pages,
see the first paragraph. If you get an OutOfMemoryError when outside of Cocoon (e.g., copying raw
files), see the second paragraph.
</p>
<p>
The <span class="codefrag">maxmemory</span> property in the <span class="codefrag">forrest.properties</span> file controls how much
memory Cocoon uses. Like many other properties you can copy them from the default configuration at
<span class="codefrag">src/core/fresh-site/forrest.properties</span>
</p>
<p>
Set the <span class="codefrag">ANT_OPTS</span> environment variable before you run forrest. The exact value you set
it to is dependant on your JVM, but something like <span class="codefrag">ANT_OPTS=-Xmx500M</span> will probably work.
</p>
</div>
<a name="N1007E"></a><a name="technical"></a>
<h3 class="underlined_5">2. Technical</h3>
<a name="N10082"></a><a name="PDF-output"></a>
<h4 class="faq">2.1. How can I generate one pdf-file out of
the whole site or selected pages of the site?</h4>
<div align="right">
<a href="#PDF-output-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>Add the following entries to your site.xml file:</p>
<pre class="code">
&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;</pre>
<p>
In this case the menu labeled "About" will have 2 new items:
"Full PDF" and "Full HTML". (See also
<a href="../docs_0_60/howto/howto-pdf-tab.html">How to create a PDF document for each tab</a>.)
</p>
<p>
This assumes that you use the
<a href="../docs_0_60/linking.html">site.xml</a> method for your site
structure and navigation, rather than the old book.xml method.
</p>
</div>
<a name="N1009C"></a><a name="clickable-email-adress"></a>
<h4 class="faq">2.2. How can I generate html-pages to show a
'clickable' email-address (of the author-element)?</h4>
<div align="right">
<a href="#clickable-email-adress-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>You would override <span class="codefrag">
src/core/context/skins/common/xslt/html/document2html.xsl</span>
and edit the "headers/authors" template.
</p>
</div>
<a name="N100A7"></a><a name="CVS_revison_tags"></a>
<h4 class="faq">2.3. How can I generate html-pages to show the
revision tag of cvs?</h4>
<div align="right">
<a href="#CVS_revison_tags-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>If you have:<span class="codefrag">&lt;version&gt;$Revision: 1.30
$&lt;/version&gt;</span>The '1.30' will be extracted and
displayed at the bottom of the page as "version 1.30". See for
example the bottom of the
<a href="../docs_0_60/your-project.html"> Using Forrest</a> document.</p>
<p>This technique could also be used for a modification date with
$Date: 2005/01/15 08:52:47 $</p>
</div>
<a name="N100B9"></a><a name="ignoring_javadocs"></a>
<h4 class="faq">2.4.
How do I stop Forrest breaking on links to external files that may not
exist, like javadocs?
</h4>
<div align="right">
<a href="#ignoring_javadocs-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
This can be done by overriding the <span class="codefrag">cli.xconf</span> config file,
and defining patterns for URLs to exclude.
</p>
<p>
This means creating a directory <span class="codefrag">src/documentation/conf</span>
(or wherever <span class="codefrag">${forrest.conf-dir}</span> points) and copying
<span class="codefrag">$FORREST_HOME/context/WEB-INF/cli.xconf</span> to it. Then edit
cli.xconf, and add any exclude sections you require at the end. The
default cli.xconf ignores directory links and links containing
'apidocs' or starting with 'api/':
</p>
<pre class="code">
....
&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;</pre>
<p>This is just an example, and you should modify it appropriately for
your site.</p>
<div class="note">
<div class="label">Note</div>
<div class="content">
Wildcards may be used. These are a powerful feature of Cocoon's
<a href="../docs_0_60/sitemap-ref.html">sitemap</a>.
For example, <strong>foo/*</strong> would match
<span class="codefrag">foo/bar</span>, but not <span class="codefrag">foo/bar/baz</span>
&mdash; use <strong>foo/**</strong> to match that.
</div>
</div>
</div>
<a name="N100ED"></a><a name="link_raw"></a>
<h4 class="faq">2.5. How do I link to raw files such as config.txt and brochure.pdf?
</h4>
<div align="right">
<a href="#link_raw-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
Place them in the <span class="codefrag">src/documentation/content</span> directory
and they will get copied into the output tree where you can link to
them. You can also have sub-directories there to reflect your xdocs
tree. See the samples documents when you 'forrest seed' a new
project for a demonstration of this ability.
</p>
<p>
For example, if
<span class="codefrag">src/documentation/content/xdocs/tools/downloads.xml</span>
has a <span class="codefrag">&lt;link href="tool.zip"&gt;</span> then put
<span class="codefrag">tool.zip</span> in the
<span class="codefrag">src/documentation/content/tools/</span> directory.
</p>
<p>
See the explanation and demonstration of "linking" in your local
'forrest seed' site.
</p>
</div>
<a name="N1010A"></a><a name="claimed_patterns"></a>
<h4 class="faq">2.6. Some of my files are not being processed because they use
common filenames.
</h4>
<div align="right">
<a href="#claimed_patterns-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
Certain patterns are claimed by the default sitemaps for
special processing. These include:
<span class="codefrag">site, changes, todo, faq, images, my-images, skinconf,
community, howto</span>
</p>
<p>
Sometimes there are workarounds, e.g. perhaps "my_site".
In future versions of Forrest we will attempt to deal with this issue.
</p>
</div>
<a name="N10118"></a><a name="build_msg_a"></a>
<h4 class="faq">2.7. What do the symbols and numbers mean when Forrest lists each
document that it has built?
</h4>
<div align="right">
<a href="#build_msg_a-menu">^</a>
</div>
<div style="margin-left: 15px">
<pre class="code">
* [56/0] 6.281s 23.0Kb index.html
* [0/0] 0.0060s 4.0Kb images/project-logo.gif
^ apidocs/index.html
* [50/0] 1.582s 18.7Kb todo.html
X [0] brokenlink.html BROKEN: reason
* [50/0] 1.222s 20.2Kb dreams.html
* [0/0] 0.535s 11.1Kb dreams.pdf
...</pre>
<p>
Column 1 is the page build status (*=okay X=brokenLink ^=pageSkipped).
Column 2 is the number of links that were gathered from that page.
Column 3 is the time taken.
Column 4 is the page size.
</p>
</div>
<a name="N10124"></a><a name="pdf_images"></a>
<h4 class="faq">2.8. Images don't display in PDFs. How do I fix this?</h4>
<div align="right">
<a href="#pdf_images-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
Forrest uses <a href="http://xml.apache.org/fop/">Apache FOP</a>
for rendering PDFs. FOP cannot handle all image types natively, and
requires third-party jars to be added. FOP natively handles BMP, GIF,
JPG, TIFF and EPS (with a few limitations). FOP can also handle SVG
(via Batik!and PNG (see below). For details, see
<a href="http://xml.apache.org/fop/graphics.html">FOP Graphics
formats</a>
</p>
<p>To get PNGs working in PDFs with Jimi:</p>
<ol>
<li>Download Jimi from
<a href="http://java.sun.com/products/jimi/">http://java.sun.com/products/jimi/</a>
</li>
<li>Unpack the Jimi distribution and copy JimiProClasses.zip to
<span class="codefrag">$FORREST/lib/optional/jimi-1.0.jar</span>.</li>
</ol>
<p>Alternatively you can use JAI (Java Advanced Imaging API at
http://java.sun.com/products/java-media/jai). For more
info, see
<a href="http://xml.apache.org/fop/graphics.html#packages">FOP Graphics
Packages</a>
</p>
<div class="note">
<div class="label">Note</div>
<div class="content">Due to Sun's licensing, we cannot redistribute Jimi or JAI with
Forrest.</div>
</div>
</div>
<a name="N10150"></a><a name="index.html"></a>
<h4 class="faq">2.9.
The tab link in my site incorrectly assumes that 'index.html' is present in
the linked-to directory. How do I fix this?
</h4>
<div align="right">
<a href="#index.html-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
In <span class="codefrag">tabs.xml</span>, use @href instead of @dir, and omit the
trailing '/'. Which file to serve is then a concern of the sitemap.
For example, if the "User Manual" tab should link to
<span class="codefrag">manual/Introduction.html</span> then
<span class="codefrag">tabs.xml</span> should contain:
</p>
<pre class="code">
&lt;tab label="User Manual" href="manual"/&gt;</pre>
<p>
and add this rule to the sitemap:
</p>
<pre class="code">
&lt;map:match pattern="manual"&gt;
&lt;map:redirect-to uri="manual/Introduction.html"/&gt;
&lt;/map:match&gt;</pre>
</div>
<a name="N1016C"></a><a name="headless_operation"></a>
<h4 class="faq">2.10.
When generating PNG images from SVG, I get an error: Can't connect to X11 window server using ':0.0' as the value of the DISPLAY variable.
</h4>
<div align="right">
<a href="#headless_operation-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
If you are using JDK 1.4.0 or newer, you can enable <em>headless</em>
operation by running Forrest with the <span class="codefrag">forrest.jvmarg</span>
parameter set to <span class="codefrag">-Djava.awt.headless=true</span>, like this:
</p>
<pre class="code">forrest -Dforrest.jvmargs=-Djava.awt.headless=true site</pre>
<p>
See also
<a href="http://cocoon.apache.org/2.1/faq/faq-configure-environment.html">Cocoon FAQ</a>.
</p>
</div>
<a name="N10188"></a><a name="catalog"></a>
<h4 class="faq">2.11.
How do i configure my favourite XML editor or parser to find the
local Forrest DTDs?
</h4>
<div align="right">
<a href="#catalog-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
Notes are provided for various tools at
<a href="../docs_0_60/catalog.html">Using Catalog Entity Resolver for
local DTDs</a>.
</p>
</div>
<a name="N10194"></a><a name="label-entity"></a>
<h4 class="faq">2.12.
How to use special characters in the labels of the site.xml file?
</h4>
<div align="right">
<a href="#label-entity-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
Use the numeric values for character entities.
For example, rather than using
<span class="codefrag">&amp;ouml;</span> use
<span class="codefrag">&amp;#246;</span>
</p>
<p>
See the
<a href="http://www.w3.org/TR/xhtml-modularization/dtd_module_defs.html#a_xhtml_character_entities">XHTML Character Entities</a>
and see more discussion at
<a href="http://issues.cocoondev.org/browse/FOR-244">Issue FOR-244</a>.
</p>
</div>
<a name="N101AD"></a><a name="skin"></a>
<h4 class="faq">2.13.
How to make the site look better and change its skin?
</h4>
<div align="right">
<a href="#skin-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
There are <a href="../docs_0_60/skins.html">default skins</a> provided,
which are configurable and so should meet the needs of most projects.
The aim is to provide many capabilities so that extra skins are not
needed.
</p>
<p>
See notes about
<a href="../docs_0_60/your-project.html#skins">configuration</a> of the skins.
Some projects may have special needs and can define their
<a href="../docs_0_60/your-project.html#new_skin">own skin</a>.
</p>
</div>
<a name="N101C4"></a><a name="xsp"></a>
<h4 class="faq">2.14. How do I enable XSP processing?</h4>
<div align="right">
<a href="#xsp-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>First consider whether your needs would be better met by Cocoon itself, rather than Forrest.
</p>
<p>That said, there are valid reasons for wanting programmatically generated content, so here is how to enable
XSP:</p>
<ol>
<li>Download
<a href="http://cvs.apache.org/viewcvs.cgi/*checkout*/cocoon-2.1/lib/optional/jdtcore-2.1.0.jar?rev=1.1&content-type=application/java">jdtcore-2.1.0.jar</a>,
and copy it to the $FORREST_HOME/context/WEB-INF/lib directory
(or lib/core/ directory in the source
distribution).</li>
<li>
<p>Override sitemap.xmap in your local project (copy $FORREST_HOME/context/sitemap.xmap to
src/documentation/), and add the following generator definition in the map:generators section:</p>
<pre class="code">
&lt;map:generator name="serverpages"
pool-grow="2" pool-max="32" pool-min="4"
src="org.apache.cocoon.generation.ServerPagesGenerator"/&gt;</pre>
</li>
<li>
<p>Decide how you want to use XSP. For single files, you could just define a *.xml matcher:</p>
<pre class="code">
&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;</pre>
<p>You may instead wish to override forrest.xmap to define a general mapping for XSPs.</p>
</li>
</ol>
<p>See also the
<a href="http://wiki.apache.org/cocoon/AddingXSPToForrest">AddingXSPToForrest</a> Wiki page.</p>
</div>
<a name="N101F9"></a><a name="breadcrumbs"></a>
<h4 class="faq">2.15. How do breadcrumbs work? Why don't they work locally?</h4>
<div align="right">
<a href="#breadcrumbs-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>Breadcrumbs begin with up to three URLs specified in
<span class="codefrag">skinconf.xml</span>. Here is what the Forrest site uses:</p>
<pre class="code">
&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;</pre>
<p>If any links are blank, they are not used. After these first links,
JavaScript looks at the URL for the current page and
makes a link for each directory after the domain. If you are viewing
the site locally, there is no domain and so
there will be no extra breadcrumbs, only the ones that are specified
in <span class="codefrag">skinconf.xml</span>.
</p>
</div>
<a name="N1020E"></a><a name="old_faqs"></a>
<h3 class="underlined_5">3. Older versions</h3>
<a name="N10212"></a><a name="unresolved_project.home"></a>
<h4 class="faq">3.1. When invoking Forrest 0.4 from the
forrest.antproxy.xml, the build fails because
${project.home} isn't resolved.
</h4>
<div align="right">
<a href="#unresolved_project.home-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>This is a bug in 0.4. The following modification to
<span class="codefrag">FORREST_HOME/forrest.antproxy.xml</span> should fix it:</p>
<pre class="code">--- forrest.antproxy.xml 7 Feb 2003 22:21:15 -0000 1.2
+++ forrest.antproxy.xml 22 Feb 2003 09:39:42 -0000
@@ -41,6 +41,7 @@
&lt;/path&gt;
&lt;target name="forrest"&gt;
+ &lt;property name="project.home" location="."/&gt;
&lt;java classname="org.apache.tools.ant.Main" fork="true"&gt;
&lt;classpath refid="forrest-classpath"/&gt;
&lt;jvmarg value="-Dforrest.home=${forrest.home}"/&gt;</pre>
</div>
<a name="N10227"></a><a name="odd_html"></a>
<h4 class="faq">3.2.
After upgrading to 0.4 my HTML looks significantly different, and table
widths are wrong. What happened?
</h4>
<div align="right">
<a href="#odd_html-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
Forrest now uses a HTML 4.0.1 <span class="codefrag">DOCTYPE</span> declaration:</p>
<pre class="code">
&lt;!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd"&gt;</pre>
<p>
This causes browsers to render the page in standards-compliance mode,
or rather, not in "quirks" mode. For some operations (like determining
table column widths), quirks mode results in better looking pages.
For the old pre-0.4 behaviour, create a custom sitemap and remove the
line:</p>
<pre class="code">
&lt;doctype-system&gt;http://www.w3.org/TR/html4/loose.dtd&lt;/doctype-system&gt;</pre>
</div>
<a name="N1023D"></a><a name="validation_error-doctype_root_null"></a>
<h4 class="faq">3.3.
When building my project, I get an validation error: Document root
element "site", must match DOCTYPE root "null"..
</h4>
<div align="right">
<a href="#validation_error-doctype_root_null-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
You are probably trying to build the project with an old version of
Forrest (built before 2003-01-08) that is incorrectly trying to validate
the <span class="codefrag">site.xml</span> file. If so, please update your Forrest
installation.
</p>
<p>
Alternatively, you may be building with an up-to-date Forrest, but have
overridden <span class="codefrag">forrest.validate.xdocs.excludes</span> in
<span class="codefrag">forrest.properties</span>. With the introduction of
<span class="codefrag">site.xml</span>, the above property must have <span class="codefrag">site.xml</span>
listed to prevent an attempt at DTD-based validation.
</p>
</div>
<a name="N1025A"></a><a name="building_error-custom_sitemap"></a>
<h4 class="faq">3.4.
When building my project, I get any of these errors:
menu.xmap (The system cannot find the file specified)
static.xmap (The system cannot find the file specified)
Type 'xml-document' is not defined for 'serialize'
</h4>
<div align="right">
<a href="#building_error-custom_sitemap-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
You are using an old version of sitemap.xmap (download the historic document
'Upgrading to Forrest 0.5' from the subversion repository).
</p>
</div>
<a name="N1026B"></a><a name="general"></a>
<h3 class="underlined_5">4. General</h3>
<a name="N1026F"></a><a name="generating_menus"></a>
<h4 class="faq">4.1. What is the relationship between site.xml and
book.xml?
</h4>
<div align="right">
<a href="#generating_menus-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
One <span class="codefrag">site.xml</span> file in your project root can replace all the book.xml files
(one per directory) in your site. Internally, Forrest uses <span class="codefrag">site.xml</span> to
dynamically generate book.xml files. However, Forrest first checks
for the existence of a book.xml file, so backwards-compatibility is
preserved. If a directory has a book.xml file, the book.xml will be
used to generate the menu. This supplement is useful in situations
where <span class="codefrag">site.xml</span>-generated menus aren't appropriate.
See <a href="../docs_0_60/linking.html">Menus and Linking</a>.
</p>
</div>
<a name="N1028A"></a><a name="docbook"></a>
<h4 class="faq">4.2.
How do I use DocBook as the xml documentation format?
</h4>
<div align="right">
<a href="#docbook-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
There are two ways. Forrest can transform the DocBook format into the
Forrest "xdocs" format on-the-fly and then render that as normal
Forrest documents.
Be aware that the stylesheet that does this transformation is
deliberately very limited and does not attempt to deal with all
DocBook elements.
</p>
<p>
The other way is to use the full DocBook stylesheets directly. The DocBook
DTDs are shipped with Forrest and automatically handled. However, you
will need to have the DocBook stylesheets on your system (they are
too massive to ship with Forrest) and configure Forrest accordingly.
You will need to create a
<a href="../docs_0_60/project-sitemap.html">project sitemap</a>
as explained in
<a href="../docs_0_60/your-project.html">Using Forrest</a>
and add matches to handle your DocBook documents.
Here is an example. Note that you need to change it to suit your
situation. The match must be very specific so that only the
DocBook documents are matched. The rest of the documents will be
handled by Forrest core. Powerful regex capabilities are available.
</p>
<pre class="code">&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;
</pre>
<p>
You can also use a mixture of the two methods, some handled
automatically by Forrest and some directly using DocBook stylesheets.
You can also have a mixture of source files as "document-v*" DTD and DocBook.
</p>
<p>
Ensure that the document type declaration in your xml instance is
well specified. Use a public identifier. The DTD will then be properly
resolved by Forrest. If you need to use different DTDs, then see
<a href="../docs_0_60/your-project.html#new_dtd">Using Forrest</a>
for configuration guidance.
</p>
</div>
<a name="N102AB"></a><a name="version"></a>
<h4 class="faq">4.3.
How to report which version of Forrest is being used and the
properties that are set?
</h4>
<div align="right">
<a href="#version-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
Do <span class="codefrag">'forrest -projecthelp'</span> or <span class="codefrag">'./build.sh'</span>
to find the version number.
</p>
<p>
To list the properties, add "forrest.echo=true" to your
forrest.properties file and watch the build messages.
Doing <span class="codefrag">'forrest -v'</span> will provide verbose build messages.
</p>
</div>
<a name="N102BF"></a><a name="logs"></a>
<h4 class="faq">4.4.
Where are the log files to find more infomation about errors?
</h4>
<div align="right">
<a href="#logs-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
The logfiles are at <span class="codefrag">build/webapp/WEB-INF/logs/</span>
</p>
<p>
The log level can be raised with the <span class="codefrag">logkit.xconf</span>
configuration. If you are using Forrest in the interactive webapp
mode (which is generally easiest for debugging errors) then see the
<span class="codefrag">build/webapp/WEB-INF/logkit.xconf</span> file.
If you are generating a static site (with command-line 'forrest')
then copy <span class="codefrag">$FORREST_HOME/context/WEB-INF/logkit.xconf</span>
to your project at
<span class="codefrag">src/documentation/content/conf/logkit.xconf</span>
and modify it. See more information and efficiency tips with
<a href="http://wiki.apache.org/cocoon/ExploringTheLogs">Cocoon logging</a>.
</p>
<p>
Doing <span class="codefrag">'forrest -v'</span> will provide verbose build messages
to the standard output.
</p>
</div>
<a name="N102E3"></a><a name="how_can_I_help"></a>
<h4 class="faq">4.5.
How to help?
</h4>
<div align="right">
<a href="#how_can_I_help-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
Join one of the Forrest project
<a href="../mail-lists.html">mailing lists</a>
and tell us what you would like to see improved. We regard all feedback
as valuable, particularly from newcomers&mdash;often, close proximity
blinds software developers to faults that are obvious to everyone
else. Don't be shy!
</p>
</div>
<a name="N102EF"></a><a name="patch"></a>
<h4 class="faq">4.6.
How to contribute a patch?
</h4>
<div align="right">
<a href="#patch-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>Please send all contributions via our
<a href="../issues.html">issue tracker</a>.
Here are notes about
<a href="../contrib.html#patch">making patches</a>.
</p>
<p>More info about contributing can be found at the
<a href="../contrib.html">Contributing to Forrest</a> page.
It is always a good idea to check the Forrest
<a href="../issues.html">issue tracker</a>
and
<a href="../docs_0_60/todo.html">to do list</a>
before diving in.
</p>
</div>
</div>
</div>
<!--+
|end content
+-->
<div class="clearboth">&nbsp;</div>
</div>
<div id="footer">
<!--+
|start bottomstrip
+-->
<div class="lastmodified">
<script type="text/javascript"><!--
document.write("Last Published: " + document.lastModified);
// --></script>
</div>
<div class="copyright">
Copyright &copy;
2002-2007 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
</div>
<!--+
|end bottomstrip
+-->
</div>
</body>
</html>