Google Git
Sign in
apache / forrest / forrest_08_release_site / . / docs_0_70 / faq.html
blob: 48a102248afeef363f673bb5a383f9d9e26e524f [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.7)</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="selected" href="../docs_0_70/index.html">0.70 (current)</a><a class="unselected" href="../docs_0_80/index.html">0.80-dev (under development)</a><a class="unselected" href="../docs_0_60/index.html">0.60 (past)</a>
</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.70</div>
<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
<div class="menuitem">
<a href="../docs_0_70/index.html">Overview</a>
</div>
<div class="menupage">
<div class="menupagetitle">FAQs</div>
</div>
<div class="menuitem">
<a href="../docs_0_70/changes.html">Changes</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/todo.html">Todo</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/your-project.html">Using Forrest</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/validation.html">XML Validation</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/linking.html">Menus and Linking</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/searching.html">Searching</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/skins.html">Default Skins</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/skin-package.html">Skin Packages</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/views.html">Views-dev</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/forrest-contract.html">Our Contract</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/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_70/howto/index.html">Overview</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-howto.html">Write a How-to</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-asf-mirror.html">Download mirror</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-pdf-tab.html">Create tab PDF</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-editcss.html">Edit CSS (WYSIWYG)</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-corner-images.html">CSS corner SVG</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-forrest-from-maven.html">Maven Integration</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-buildPlugin.html">Build a Plugin</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-custom-html-source.html">Custom html source</a>
</div>
<div onclick="SwitchMenu('menu_1.1.14.10', '../skin/')" id="menu_1.1.14.10Title" class="menutitle">Multipage HowTo</div>
<div id="menu_1.1.14.10" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_70/howto/multi/howto-multi.html">Introduction</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/multi/step1.html">Step 1</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/multi/step2.html">Step 2</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/multi/step3.html">Step 3</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.1.14.11', '../skin/')" id="menu_1.1.14.11Title" class="menutitle">Views</div>
<div id="menu_1.1.14.11" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_70/howto/howto-view-install.html">Install views</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-view-dsl.html">forrest:view DSL</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-view-contracts.html">contract implementations</a>
</div>
</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_70/build.html">Building Forrest</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/catalog.html">Using DTD Catalogs</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/sitemap-ref.html">Sitemap Reference</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/project-sitemap.html">Project sitemap</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/cap.html">Sourcetype Action</a>
</div>
</div>
<div class="menuitem">
<a href="../docs_0_70/upgrading_07.html">Upgrading to 0.7</a>
</div>
<div onclick="SwitchMenu('menu_1.1.17', '../skin/')" id="menu_1.1.17Title" class="menutitle">Reference docs</div>
<div id="menu_1.1.17" class="menuitemgroup">
<div onclick="SwitchMenu('menu_1.1.17.1', '../skin/')" id="menu_1.1.17.1Title" class="menutitle">DTD documentation</div>
<div id="menu_1.1.17.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.17.2', '../skin/')" id="menu_1.1.17.2Title" class="menutitle">Doc samples</div>
<div id="menu_1.1.17.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 onclick="SwitchMenu('menu_1.1.18', '../skin/')" id="menu_1.1.18Title" class="menutitle">Older Docs</div>
<div id="menu_1.1.18" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_70/primer.html">Forrest Primer</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/libre-intro.html">Libre</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/dreams.html">Dream list</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/cvs-ssh/howto-cvs-ssh.html">CVS over SSH</a>
</div>
</div>
</div>
<div id="credit">
<hr>
This is documentation for current version v0.7
(<a href="http://forrest.apache.org/versions/">More</a>)</div>
<div id="roundbottom">
<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
<!--+
|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 current version v0.7
(<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="#faq">1.1. How to use these FAQs? </a>
</li>
<li>
<a href="#overview">1.2. Where can I read an overview about how to work with Forrest? </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="#older-plugins">1.6. How to use older versions of specific plugins? </a>
</li>
<li>
<a href="#single-document">1.7. What is the best way to generate "standalone documents" using Forrest? </a>
</li>
<li>
<a href="#cygwin_mutex_error">1.8. 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.9. How can I specify the amount of memory to be used by Java? </a>
</li>
</ul>
</li>
<li>
<a href="#content_faqs">2. Content Creation</a>
<ul class="minitoc">
<li>
<a href="#edit-content">2.1. What tools can be used to edit the content?</a>
</li>
<li>
<a href="#site-xml">2.2.
How to use the site.xml configuration file for menus and linking.
</a>
</li>
<li>
<a href="#examples">2.3.
Where are examples of documents and site.xml and tabs.xml files?
</a>
</li>
<li>
<a href="#PDF-output">2.4. How can I generate one pdf-file out of the whole site or selected pages of the site?</a>
</li>
<li>
<a href="#pageBreaks">2.5. How do I insert page breaks into documents?</a>
</li>
<li>
<a href="#clickable-email-address">2.6. How can I generate html-pages to show a 'clickable' email-address (of the
author-element)?</a>
</li>
<li>
<a href="#link_raw">2.7. How do I link to raw files such as config.txt and brochure.pdf? </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="#tab-index">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="#tab-site">2.10. I need help with the interaction between tabs.xml and site.xml </a>
</li>
<li>
<a href="#defaultFileName">2.11. How can I change the default file name that Forrest will look for when I request a
URL like http://myserver or http://myserver/mydir/ ? </a>
</li>
<li>
<a href="#defaultStartPage">2.12. How can I use a start-up-page other than index.html? </a>
</li>
<li>
<a href="#label-entity">2.13. How to use special characters in the labels of the site.xml file? </a>
</li>
<li>
<a href="#encoding">2.14. Does Forrest handle accents for non-English languages?</a>
</li>
<li>
<a href="#cleanSite">2.15. How to make Forrest clean up the project build directories? </a>
</li>
<li>
<a href="#i18n">2.16. How can I internationalise (i18n) my content?</a>
</li>
<li>
<a href="#rawTML">2.17. How can I include HTML content that is not to be skinned by Forrest?</a>
</li>
</ul>
</li>
<li>
<a href="#technical">3. Technical</a>
<ul class="minitoc">
<li>
<a href="#proxy_config">3.1. I'm behind a proxy and it's preventing Plugins from being downloaded, what should I
do?</a>
</li>
<li>
<a href="#CVS_revison_tags">3.2. How can I generate html-pages to show the revision tag of cvs?</a>
</li>
<li>
<a href="#cli-xconf">3.3. How to control the processing of URIs by Cocoon, e.g. exclude certain URIs, include
other additional ones. </a>
</li>
<li>
<a href="#ignoring_javadocs">3.4. How do I stop Forrest breaking on links to external files that may not exist, like
javadocs? </a>
</li>
<li>
<a href="#claimed_patterns">3.5. Some of my files are not being processed because they use common filenames. </a>
</li>
<li>
<a href="#build_msg_a">3.6. What do the symbols and numbers mean when Forrest lists each document that it has
built? </a>
</li>
<li>
<a href="#headless_operation">3.7. When generating PNG images from SVG, I get an error: Can't connect to X11 window
server using ':0.0' as the value of the DISPLAY variable. </a>
</li>
<li>
<a href="#project-logo-svg">3.8.
The project logo that is generated from SVG is truncating my project name.
</a>
</li>
<li>
<a href="#catalog">3.9. How do i configure my favourite XML editor or parser to find the local Forrest
DTDs? </a>
</li>
<li>
<a href="#skin">3.10. How to make the site look better and change its skin? </a>
</li>
<li>
<a href="#xsp">3.11. How do I enable XSP processing?</a>
</li>
<li>
<a href="#breadcrumbs">3.12. How do breadcrumbs work? Why don't they work locally?</a>
</li>
<li>
<a href="#run_port">3.13. How do I make forrest run listen on a different port?</a>
</li>
</ul>
</li>
<li>
<a href="#old_faqs">4. Older version: 0.6</a>
<ul class="minitoc">
<li>
<a href="#old_claimed_patterns">4.1. Some of my files are not being processed because they use common filenames. </a>
</li>
</ul>
</li>
<li>
<a href="#general">5. General</a>
<ul class="minitoc">
<li>
<a href="#generating_menus">5.1. What is the relationship between site.xml and book.xml? </a>
</li>
<li>
<a href="#docbook">5.2. How do I use DocBook as the xml documentation format? </a>
</li>
<li>
<a href="#version">5.3. How to report which version of Forrest is being used and the properties that are
set? </a>
</li>
<li>
<a href="#logs">5.4. Where are the log files to find more infomation about errors? </a>
</li>
<li>
<a href="#how_can_I_help">5.5. How to help? </a>
</li>
<li>
<a href="#patch">5.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="faq"></a>
<h4 class="faq">1.1. How to use these FAQs? </h4>
<div align="right">
<a href="#faq-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
There is no particular order to these FAQs. Use your browser's
"Find in this page" facility to search for keywords.
</p>
</div>
<a name="N10018"></a><a name="overview"></a>
<h4 class="faq">1.2. 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_70/your-project.html">Using Forrest</a> guide. </p>
</div>
<a name="N10024"></a><a name="requirements"></a>
<h4 class="faq">1.3. What are the system requirements for Forrest? </h4>
<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 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>
</div>
<a name="N1002F"></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 closed and not kept current. </p>
</div>
<a name="N10037"></a><a name="svn"></a>
<h4 class="faq">1.5. How can I use SVN to keep up to date with the latest codebase? </h4>
<div align="right">
<a href="#svn-menu">^</a>
</div>
<div style="margin-left: 15px">
<p> Follow these <a href="../docs_0_70/build.html">Building Forrest</a> notes. </p>
<p> The <a href="../docs_0_70/your-project.html">Using Forrest</a> guide provides further
step-by-step assistance in getting started with Forrest for your project. </p>
</div>
<a name="N1004A"></a><a name="older-plugins"></a>
<h4 class="faq">1.6. How to use older versions of specific plugins? </h4>
<div align="right">
<a href="#older-plugins-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
Sometimes one does not want to use the most recent functionality
of a plugin and instead need to use an older version.
Information about changes to each plugin can be found in its
<a href="../pluginDocs/plugins_0_70/index.html">documentation</a>.
</p>
<p>
In the forrest.properties file, specify the version of the plugin
that you require, e.g.
</p>
<pre class="code">project.required.plugins=org.apache.forrest.plugin.input.PhotoGallery-0.1,...</pre>
<p>
Users of Forrest-0.7 will need to do this for the projectInfo plugin
if you get the following error ...
</p>
<pre class="code">Could not find component for role:
[org.apache.cocoon.components.modules.input.InputModule/lm]
(Key='org.apache.cocoon.components.modules.input.InputModule/</pre>
<p>
... then sorry, we mistakenly added new "locationmap" functionality
(due in version 0.8). So do this ...
</p>
<pre class="code">project.required.plugins=org.apache.forrest.plugin.input.projectInfo-0.1,...</pre>
</div>
<a name="N1006B"></a><a name="single-document"></a>
<h4 class="faq">1.7. What is the best way to generate "standalone documents" using Forrest? </h4>
<div align="right">
<a href="#single-document-menu">^</a>
</div>
<div style="margin-left: 15px">
<p> forrest site -Dproject.start-uri=myfile.pdf </p>
<p> The <a href="../docs_0_70/your-project.html">Using Forrest</a> guide provides further
step-by-step assistance in getting started with Forrest for your project. </p>
</div>
<a name="N1007A"></a><a name="cygwin_mutex_error"></a>
<h4 class="faq">1.8. When running ./build.sh in cygwin, I get an error: cygpath.exe:
*** 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.apache.org/jira/secure/ViewIssue.jspa?key=FOR-10">appears
to be a bug in cygwin</a>. Please use the .bat script instead. </p>
</div>
<a name="N1008C"></a><a name="maxmemory"></a>
<h4 class="faq">1.9. How can I specify the amount of memory to be used by Java? </h4>
<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="N100A9"></a><a name="content_faqs"></a>
<h3 class="underlined_5">2. Content Creation</h3>
<a name="N100AD"></a><a name="edit-content"></a>
<h4 class="faq">2.1. What tools can be used to edit the content?</h4>
<div align="right">
<a href="#edit-content-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>If you are using the Apache Forrest xml <a href="../docs_0_70/../dtdx/dtd-docs.html">document format</a>
or DocBook or other xml document types, then you can use any text editor or even a
dedicated xml editor. You must ensure valid xml. See our <a href="../docs_0_70/catalog.html">configuration notes</a> for various editors. </p>
<p>There are content management systems like <a href="http://lenya.apache.org/">Apache Lenya</a>. </p>
<p>Remember that Forrest can also use other source formats, such as OpenOffice.org docs or
JSPWiki. Use the appropriate editor for those document types and ensure that the document
stucture is consistent. Forrest can also use "html" as the source format, in which case
you can use text editors or "html editors" such as the one provided with the Mozilla web
browser. </p>
</div>
<a name="N100C7"></a><a name="site-xml"></a>
<h4 class="faq">2.2.
How to use the site.xml configuration file for menus and linking.
</h4>
<div align="right">
<a href="#site-xml-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
The <span class="codefrag">site.xml</span> configuration file is used for two different purposes:
defining the left-hand navigation menus, and as a method for defining references
to be used when linking between documents.
This file is fully explained in
<a href="../docs_0_70/linking.html">Menus and Linking</a>. Here is a precis:
</p>
<p>
The labels can be whatever text you want.
</p>
<pre class="code">&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;</pre>
<p>
That will create a menu like this with three links:
</p>
<pre class="code">FAQs
Technical
User</pre>
<p>
These documents can be linked to from other documents, like this:
</p>
<pre class="code">&lt;a href="site:v0.70//faq/tech"&gt; link to the top of the Tech FAQs
&lt;a href="site:v0.70//faq/tech/docbook"&gt; link to the DocBook FAQ in the Tech FAQs</pre>
<p>
If that "docbook" entry was a unique name in your site.xml then you
can shorten that latter link:
</p>
<pre class="code">&lt;a href="site:v0.70//docbook"&gt; link to the DocBook FAQ in the Tech FAQs</pre>
</div>
<a name="N100F5"></a><a name="examples"></a>
<h4 class="faq">2.3.
Where are examples of documents and site.xml and tabs.xml files?
</h4>
<div align="right">
<a href="#examples-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
There are examples in the 'forrest seed site' and also the Forrest website documents
are included with the distribution (cd forrest/site-author; forrest run).
</p>
</div>
<a name="N100FD"></a><a name="PDF-output"></a>
<h4 class="faq">2.4. 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_70/howto/howto-pdf-tab.html">How to create a PDF document for each
tab</a>.) </p>
<p> This assumes that you use the <a href="../docs_0_70/linking.html">site.xml</a> method for your
site structure and navigation, rather than the old book.xml method. </p>
</div>
<a name="N10117"></a><a name="pageBreaks"></a>
<h4 class="faq">2.5. How do I insert page breaks into documents?</h4>
<div align="right">
<a href="#pageBreaks-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>Page breaks do not make a great deal of sense in HTML documents intended for display on a
screen. However, PDF documents are intended for printing and therefore page breaks can be
important.</p>
<p>To insert a page break in a PDF document simply add <em>pageBreakBefore</em> and/or
<em>pageBreakAfter</em> to the class attribute of the block you wish to force a
page break on. All the common block grouping elements support this class, for example,
note, warning, p and so on.</p>
<p>If you want these classes to be processed in your HTML documents as well you should add
the following to the <span class="codefrag">extra-css</span> element in your projects
<span class="codefrag">skinconf.xml</span>
</p>
<pre class="code"> .pageBreakBefore { margin-bottom: 0; page-break-before: always; } .pageBreakAfter {
margin-bottom: 0; page-break-after: always; } </pre>
</div>
<a name="N10135"></a><a name="clickable-email-address"></a>
<h4 class="faq">2.6. How can I generate html-pages to show a 'clickable' email-address (of the
author-element)?</h4>
<div align="right">
<a href="#clickable-email-address-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>You would override <span class="codefrag">
$FORREST_HOME/main/webapp/skins/common/xslt/html/document2html.xsl</span> and edit the
"headers/authors" template. </p>
</div>
<a name="N10140"></a><a name="link_raw"></a>
<h4 class="faq">2.7. How do I link to raw files such as config.txt and brochure.pdf? </h4>
<div align="right">
<a href="#link_raw-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>Handling of raw files was significantly changed in Forrest 0.7. See
<a href="../docs_0_70/upgrading_07.html#raw">Upgrading to Apache Forrest 0.7</a> for
all the details.</p>
</div>
<a name="N1014C"></a><a name="pdf_images"></a>
<h4 class="faq">2.8. Images don't display in PDFs. How do I fix this?</h4>
<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="N10179"></a><a name="tab-index"></a>
<h4 class="faq">2.9. The tab link in my site incorrectly assumes that 'index.html' is present in the
linked-to directory. How do I fix this? </h4>
<div align="right">
<a href="#tab-index-menu">^</a>
</div>
<div style="margin-left: 15px">
<p> In <span class="codefrag">tabs.xml</span>, use @href instead of @dir, and omit the trailing '/'. Which
file to serve is then a concern of the sitemap. For example, if the "User Manual" tab
should link to <span class="codefrag">manual/Introduction.html</span> then <span class="codefrag">tabs.xml</span> should
contain: </p>
<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="N10195"></a><a name="tab-site"></a>
<h4 class="faq">2.10. I need help with the interaction between tabs.xml and site.xml </h4>
<div align="right">
<a href="#tab-site-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
See the <a href="../docs_0_70/linking.html#tab-site">tips</a>.
</p>
</div>
<a name="N101A1"></a><a name="defaultFileName"></a>
<h4 class="faq">2.11. How can I change the default file name that Forrest will look for when I request a
URL like http://myserver or http://myserver/mydir/ ? </h4>
<div align="right">
<a href="#defaultFileName-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>To change the default file name from 'index.html' (default) to 'overview.html' you need to
make the following changes:</p>
<ol>
<li> Create a '<a href="#cli-xconf">cli.xconf</a>' 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 <a href="../docs_0_70/project-sitemap.html">sitemap.xmap</a> file. </li>
<li> Add the following code just before the end of the pipelines-element:<pre class="code">
&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;
</pre>
</li>
</ol>
</div>
<a name="N101C9"></a><a name="defaultStartPage"></a>
<h4 class="faq">2.12. How can I use a start-up-page other than index.html? </h4>
<div align="right">
<a href="#defaultStartPage-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>Forrest by default assumes that the first page (home page) of your site is named
index.html. Which is good because most web servers are configured to look for index.html
when you call a url like http://myserver</p>
<p>Like most settings in Forrest however this can be changed, for example when you want your
start-up-page for a CD-based documentation project to be named 'start.html'. </p>
<p>To change the start page of a site:</p>
<ol>
<li>Edit your project's <a href="../docs_0_70/project-sitemap.html">sitemap.xmap</a> file.</li>
<li>Add the following code just before the end of the pipelines-element:<pre class="code">
&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;
</pre>
</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>
</div>
<a name="N101ED"></a><a name="label-entity"></a>
<h4 class="faq">2.13. How to use special characters in the labels of the site.xml file? </h4>
<div align="right">
<a href="#label-entity-menu">^</a>
</div>
<div style="margin-left: 15px">
<p> Use the numeric values for character entities. For example, rather than using
<span class="codefrag">&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.apache.org/jira/browse/FOR-244">Issue FOR-244</a>. </p>
</div>
<a name="N10206"></a><a name="encoding"></a>
<h4 class="faq">2.14. Does Forrest handle accents for non-English languages?</h4>
<div align="right">
<a href="#encoding-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>Yes, Forrest can process text in any language, so you can include:</p>
<ul>
<li>accents: &aacute; &eacute; &iacute; &oacute; &uacute;</li>
<li>diereses: &auml; &euml; &iuml; &ouml; &uuml;</li>
<li>tildes: &atilde; &ntilde; ĩ &otilde; ũ</li>
</ul>
<p>This is because sources for Forrest docs are xml documents, which can include any of
these, provided the encoding declared by the xml doc matches the actual encoding used in
the file. For example if you declare the default encoding:</p>
<pre class="code">&lt;?xml version="1.0" encoding="UTF-8"?&gt;</pre>
<p>but the file content is actually using ISO-8859-1 then you will receive validation
errors, especially if you include some non-ASCII characters.</p>
<p> This situation is commonly encountered when you edit the templates created by
<span class="codefrag">forrest seed</span> with your favorite (probably localized) editor without paying
attention to the encoding, or when you create a new file and simply copy the headers from
another file. </p>
<p>Although UTF-8 is an encoding well-suited for most languages, it is not usually the
default in popular editors or systems. In UNIX-like systems, most popular editors can
handle different encodings to write the file in disk. With some editors the encoding of
the file is preserved, while with others the default is used regardless of the original
encoding. In most cases the encoding used to write files can be controlled by setting the
environment variable <span class="codefrag">LANG</span> to an appropriate value, for instance: </p>
<pre class="code">[localhost]$ export LANG=en_US.UTF-8</pre>
<p>Of course the <em>appropriate</em> way to set the encoding depends on the editor/OS, but
ultimately relys on the user preferences. So you can use the encoding you prefer, as long
as the <span class="codefrag">encoding</span> attribute of the xml declaration matches the actual encoding
of the file. This means that if you are not willing to abandon ISO-8859-1 you can always
use the following declaration instead:</p>
<pre class="code">&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;</pre>
<p>Another option is to use "character entities" such as <span class="codefrag">&amp;ouml;</span>
(&ouml;) or the numeric form <span class="codefrag">&amp;#246;</span> (&ouml;). </p>
<p>Another related issue is that your webserver needs to send http headers with the matching
charset definitions to the html page. </p>
<p>Here are some references which explain further: <a href="http://orixo.com/events/gt2004/bios.html#torsten">GT2004 presentation by Torsten
Schlabach</a> and <a href="http://www.alanwood.net/unicode/">Alan Wood's Unicode
resources</a>. </p>
</div>
<a name="N10258"></a><a name="cleanSite"></a>
<h4 class="faq">2.15. How to make Forrest clean up the project build directories? </h4>
<div align="right">
<a href="#cleanSite-menu">^</a>
</div>
<div style="margin-left: 15px">
<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>
</div>
<a name="N10263"></a><a name="i18n"></a>
<h4 class="faq">2.16. How can I internationalise (i18n) my content?</h4>
<div align="right">
<a href="#i18n-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>The i18n features of Forrest are still under development (as of 0.7) however there are
some features available. For example, navigation menus can be i18n'd (see fresh-site for an
example). Currently, <a href="http://issues.apache.org/jira/browse/FOR-506">work is underway</a> to
i18n skins</p>
<p>All internationalistation of tokens in, for example, the skins and the menus, is carried out
by the <a href="http://cocoon.apache.org/2.1/userdocs/transformers/i18n-transformer.html">Cocoon i18n
Transformer</a>. You can see an example of how it works in the above linked issue.</p>
</div>
<a name="N10276"></a><a name="rawTML"></a>
<h4 class="faq">2.17. How can I include HTML content that is not to be skinned by Forrest?</h4>
<div align="right">
<a href="#rawTML-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>To server, for example, a legacy HTML site add something like the following
to your projects sitemap:</p>
<pre class="code">
&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:match&gt;
</pre>
<p>There is a more detailed discussion of this topic in the samples
of a freshly seeded site. To see this documentation do the following:</p>
<ol>
<li>mkdir seed</li>
<li>cd seed</li>
<li>forrest seed</li>
<li>forrest</li>
<li>
<a href="http://localhost:8888/samples/linking.html#Serving+%28X%29HTML+content+without+Skinning">Read the doc</a>
</li>
</ol>
</div>
<a name="N10299"></a><a name="technical"></a>
<h3 class="underlined_5">3. Technical</h3>
<a name="N1029D"></a><a name="proxy_config"></a>
<h4 class="faq">3.1. I'm behind a proxy and it's preventing Plugins from being downloaded, what should I
do?</h4>
<div align="right">
<a href="#proxy_config-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>You can configure the proxy in the <span class="codefrag">forrest.properties</span> file. Set the
<span class="codefrag">proxy.host</span> and <span class="codefrag">proxy.port</span> accordingly.</p>
<p>You can also cross an authenticated proxy by setting the <span class="codefrag">proxy.user</span> and <span class="codefrag">proxy.password</span> accordingly.</p>
</div>
<a name="N102B7"></a><a name="CVS_revison_tags"></a>
<h4 class="faq">3.2. How can I generate html-pages to show the revision tag of cvs?</h4>
<div align="right">
<a href="#CVS_revison_tags-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>If you have:<span class="codefrag">&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_70/your-project.html"> Using Forrest</a> document.</p>
<p>This technique could also be used for a modification date with $Date: 2004/01/15 08:52:47
$</p>
</div>
<a name="N102C9"></a><a name="cli-xconf"></a>
<h4 class="faq">3.3. How to control the processing of URIs by Cocoon, e.g. exclude certain URIs, include
other additional ones. </h4>
<div align="right">
<a href="#cli-xconf-menu">^</a>
</div>
<div style="margin-left: 15px">
<p> Forrest uses a configuration file to control the processing done by the Apache Cocoon
command-line called cli.xconf </p>
<p> Your project can supply its own <span class="codefrag">cli.xconf</span> and define patterns for URIs to
exclude. There are also other powerful configuration features. </p>
<p> This means creating a directory <span class="codefrag">src/documentation/conf</span> (or wherever
<span class="codefrag">${forrest.conf-dir}</span> points) and copying
<span class="codefrag">$FORREST_HOME/main/webapp/WEB-INF/cli.xconf</span> to it. Declare the location of
this file in the forrest.properties configuration, e.g.
<span class="codefrag">project.configfile=${project.home}/src/documentation/conf/cli.xconf</span>
</p>
<p> Then edit cli.xconf, and add any exclude sections that you require. The default
cli.xconf ignores directory links and links containing 'apidocs' or starting with 'api/': </p>
<pre class="code">
....
&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_70/sitemap-ref.html">sitemap</a>. For example, <strong>foo/*</strong> would match
<span class="codefrag">foo/bar</span>, but not <span class="codefrag">foo/bar/baz</span> &mdash; use
<strong>foo/**</strong> to match that. </div>
</div>
</div>
<a name="N10306"></a><a name="ignoring_javadocs"></a>
<h4 class="faq">3.4. How do I stop Forrest breaking on links to external files that may not exist, like
javadocs? </h4>
<div align="right">
<a href="#ignoring_javadocs-menu">^</a>
</div>
<div style="margin-left: 15px">
<p> This can be done by overriding the <a href="#cli-xconf">
<span class="codefrag">cli.xconf</span>
</a> Cocoon config file, and defining patterns for URLs to exclude. </p>
</div>
<a name="N10315"></a><a name="claimed_patterns"></a>
<h4 class="faq">3.5. Some of my files are not being processed because they use common filenames. </h4>
<div align="right">
<a href="#claimed_patterns-menu">^</a>
</div>
<div style="margin-left: 15px">
<p> Certain patterns are claimed by the default sitemaps for special processing. These
include: <span class="codefrag">site, changes, todo, faq, images, my-images, skinconf, community,
howto</span>
</p>
<p> Sometimes there are workarounds, e.g. faq.html or faq-interview.html would fail, but
interview-faq.html would be fine. In future versions of Forrest we will attempt to deal
with this issue (<a href="http://issues.apache.org/jira/browse/FOR-217">FOR-217</a>).
</p>
</div>
<a name="N10327"></a><a name="build_msg_a"></a>
<h4 class="faq">3.6. What do the symbols and numbers mean when Forrest lists each document that it has
built? </h4>
<div align="right">
<a href="#build_msg_a-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
<pre class="code">...
* [212/166] [0/0] 1.16s 62.4Kb docs_0_60/your-project.pdf
X [0] /docs_0_80/upgrading_08.html BROKEN: No pipeline matched...
* [213/164] [0/0] 0.391s 29.2Kb docs_0_70/howto/howto-buildPlugin.pdf
^ apidocs/index.html
* [214/170] [7/66] 1.476s 45.5Kb docs_0_60/sitemap-ref.html
...</pre>
<ul>
<li>Column 1 is the page build status (*=okay X=brokenLink ^=pageSkipped).</li>
<li>Column 2 is the page count - the number of pages processed and the number remaining. 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.</li>
<li>Column 4 is the time taken.</li>
<li>Column 5 is the page size.</li>
</ul>
</p>
</div>
<a name="N10343"></a><a name="headless_operation"></a>
<h4 class="faq">3.7. When generating PNG images from SVG, I get an error: Can't connect to X11 window
server using ':0.0' as the value of the DISPLAY variable. </h4>
<div align="right">
<a href="#headless_operation-menu">^</a>
</div>
<div style="margin-left: 15px">
<p> If you are using JDK 1.4.0 or newer, you can enable <em>headless</em> operation by
running Forrest with the <span class="codefrag">forrest.jvmarg</span> parameter set to
<span class="codefrag">-Djava.awt.headless=true</span>, like this: </p>
<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="N1035F"></a><a name="project-logo-svg"></a>
<h4 class="faq">3.8.
The project logo that is generated from SVG is truncating my project name.
</h4>
<div align="right">
<a href="#project-logo-svg-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
In a 'forrest seed site' the project and the group logo are generated from a
Scalable Vector Graphics (SVG) file, using the text from the
<span class="codefrag">&lt;project-name&gt;</span> and
<span class="codefrag">&lt;group-name&gt;</span> elements of the <span class="codefrag">skinconf.xml</span> file.
If you have a long project-name then you may need to adjust the width of the image.
Perhaps you want to change the colours too. Edit the file at
<span class="codefrag">src/documentation/content/xdocs/images/project.svg</span> and adjust the "width"
attribute of the &lt;svg&gt; element. For further details see
<a href="http://www.w3.org/Graphics/SVG/">SVG</a> resources.
</p>
</div>
<a name="N10377"></a><a name="catalog"></a>
<h4 class="faq">3.9. How do i configure my favourite XML editor or parser to find the local Forrest
DTDs? </h4>
<div align="right">
<a href="#catalog-menu">^</a>
</div>
<div style="margin-left: 15px">
<p> Notes are provided for various tools at <a href="../docs_0_70/catalog.html">Using Catalog Entity
Resolver for local DTDs</a>. </p>
</div>
<a name="N10383"></a><a name="skin"></a>
<h4 class="faq">3.10. How to make the site look better and change its skin? </h4>
<div align="right">
<a href="#skin-menu">^</a>
</div>
<div style="margin-left: 15px">
<p> There are <a href="../docs_0_70/skins.html">default skins</a> provided, which are configurable
and so should meet the needs of most projects. The aim is to provide many capabilities so
that extra skins are not needed. </p>
<p> See notes about <a href="../docs_0_70/your-project.html#skins">configuration</a> of the skins.
Some projects may have special needs and can define their <a href="../docs_0_70/your-project.html#new_skin">own skin</a>. </p>
</div>
<a name="N1039A"></a><a name="xsp"></a>
<h4 class="faq">3.11. How do I enable XSP processing?</h4>
<div align="right">
<a href="#xsp-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>First consider whether your needs would be better met by Cocoon itself, rather than
Forrest. </p>
<p>That said, there are valid reasons for wanting programmatically generated content, so
here is how to enable XSP:</p>
<ol>
<li>Download <a href="http://cvs.apache.org/viewcvs.cgi/*checkout*/cocoon-2.1/lib/optional/jdtcore-2.1.0.jar?rev=1.1&content-type=application/java">jdtcore-2.1.0.jar</a>, and copy it to the $FORREST_HOME/main/webapp/WEB-INF/lib
directory (or lib/core/ directory in the source distribution).</li>
<li>
<p> Add the following generator definition in the map:generators section of your <a href="../docs_0_70/project-sitemap.html">project sitemap</a>
</p>
<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="N103D5"></a><a name="breadcrumbs"></a>
<h4 class="faq">3.12. How do breadcrumbs work? Why don't they work locally?</h4>
<div align="right">
<a href="#breadcrumbs-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>Breadcrumbs begin with up to three URLs specified in <span class="codefrag">skinconf.xml</span>. Here is
what the Forrest site uses:</p>
<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="N103EA"></a><a name="run_port"></a>
<h4 class="faq">3.13. How do I make forrest run listen on a different port?</h4>
<div align="right">
<a href="#run_port-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>
<span class="codefrag">forrest run -Dforrest.jvmargs="-Djetty.port=80"</span>
</p>
<p>Or copy Forrest's main/webapp/jettyconf.xml file to your project's src/documentation
directory and set the port number in that file. Then do <span class="codefrag">forrest run</span>
</p>
</div>
<a name="N103FE"></a><a name="old_faqs"></a>
<h3 class="underlined_5">4. Older version: 0.6</h3>
<a name="N10402"></a><a name="old_claimed_patterns"></a>
<h4 class="faq">4.1. Some of my files are not being processed because they use common filenames. </h4>
<div align="right">
<a href="#old_claimed_patterns-menu">^</a>
</div>
<div style="margin-left: 15px">
<p> Certain patterns are claimed by the default sitemaps for special processing. These
include: <span class="codefrag">site, changes, todo, faq, images, my-images, skinconf, community,
howto</span>
</p>
<p> Sometimes there are workarounds, e.g. faq.html or faq-interview.html would fail, but
interview-faq.html would be fine. In future versions of Forrest we will attempt to deal
with this issue (<a href="http://issues.apache.org/jira/browse/FOR-217">FOR-217</a>).
</p>
</div>
<a name="N10414"></a><a name="general"></a>
<h3 class="underlined_5">5. General</h3>
<a name="N10418"></a><a name="generating_menus"></a>
<h4 class="faq">5.1. What is the relationship between site.xml and book.xml? </h4>
<div align="right">
<a href="#generating_menus-menu">^</a>
</div>
<div style="margin-left: 15px">
<p> One <span class="codefrag">site.xml</span> file in your project root can replace all the book.xml files (one per
directory) in your site. Internally, Forrest uses <span class="codefrag">site.xml</span> to dynamically generate book.xml
files. However, Forrest first checks for the existence of a book.xml file, so
backwards-compatibility is preserved. If a directory has a book.xml file, the book.xml
will be used to generate the menu. This supplement is useful in situations where
<span class="codefrag">site.xml</span>-generated menus aren't appropriate. See <a href="../docs_0_70/linking.html">Menus and
Linking</a>. </p>
</div>
<a name="N10433"></a><a name="docbook"></a>
<h4 class="faq">5.2. How do I use DocBook as the xml documentation format? </h4>
<div align="right">
<a href="#docbook-menu">^</a>
</div>
<div style="margin-left: 15px">
<p> There are two ways. Forrest has a <span class="codefrag">simplifiedDocbook</span> plugin which can
transform the DocBook format into the Forrest "xdocs" format on-the-fly and then render
that as normal Forrest documents. Be aware that the stylesheet that does this
transformation is deliberately very limited and does not attempt to deal with all DocBook
elements. </p>
<p> The other way is to use the full DocBook stylesheets directly. The DocBook DTDs are
shipped with Forrest and automatically handled. However, you will need to have the DocBook
stylesheets on your system (they are too massive to ship with Forrest) and configure
Forrest accordingly. You will need to create a <a href="../docs_0_70/project-sitemap.html">project
sitemap</a> as explained in <a href="../docs_0_70/your-project.html">Using Forrest</a> and
add matches to handle your DocBook documents. Here is an example. Note that you need to
change it to suit your situation. The match must be very specific so that only the DocBook
documents are matched. The rest of the documents will be handled by Forrest core. Powerful
regex capabilities are available. </p>
<pre class="code">&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 need to define the xhtml serializer used in &lt;map:serialize type="xhtml"/&gt;
in the components section of the sitemap. See the
<a href="http://cocoon.apache.org/2.1/userdocs/serializers/xhtml-serializer.html">Cocoon
docs</a> for the elements you need to add to define this component. You can see examples
of other components being added in the <span class="codefrag">FORREST_HOME/main/webapp/sitemap.xmap</span> file.</p>
<p> You can also use a mixture of the two methods, some handled automatically by Forrest and
some directly using DocBook stylesheets. You can also have a mixture of source files as
"document-v*" DTD and DocBook. </p>
<p> Ensure that the document type declaration in your xml instance is well specified. Use a
public identifier. The DTD will then be properly resolved by Forrest. If you need to use
different DTDs, then see <a href="../docs_0_70/your-project.html#new_dtd">Using Forrest</a> for
configuration guidance. </p>
</div>
<a name="N10461"></a><a name="version"></a>
<h4 class="faq">5.3. How to report which version of Forrest is being used and the properties that are
set? </h4>
<div align="right">
<a href="#version-menu">^</a>
</div>
<div style="margin-left: 15px">
<p> Do <span class="codefrag">'forrest -projecthelp'</span> or <span class="codefrag">'./build.sh'</span> to find the version
number. </p>
<p> To list the properties, add "forrest.echo=true" to your forrest.properties file and
watch the build messages. Doing <span class="codefrag">'forrest -v'</span> will provide verbose build
messages. </p>
</div>
<a name="N10475"></a><a name="logs"></a>
<h4 class="faq">5.4. Where are the log files to find more infomation about errors? </h4>
<div align="right">
<a href="#logs-menu">^</a>
</div>
<div style="margin-left: 15px">
<p> The logfiles are at <span class="codefrag">build/webapp/WEB-INF/logs/</span>
</p>
<p> The log level can be raised with the <span class="codefrag">logkit.xconf</span> configuration. If you are
using Forrest in the interactive webapp mode (which is generally easiest for debugging
errors) then see the <span class="codefrag">build/webapp/WEB-INF/logkit.xconf</span> file. If you are
generating a static site (with command-line 'forrest') then copy
<span class="codefrag">$FORREST_HOME/main/webapp/WEB-INF/logkit.xconf</span> to your project at
<span class="codefrag">src/documentation/content/conf/logkit.xconf</span> and modify it. See more
information and efficiency tips with <a href="http://wiki.apache.org/cocoon/ExploringTheLogs">Cocoon logging</a>. </p>
<p> Doing <span class="codefrag">'forrest -v'</span> will provide verbose build messages to the standard
output. </p>
</div>
<a name="N10499"></a><a name="how_can_I_help"></a>
<h4 class="faq">5.5. How to help? </h4>
<div align="right">
<a href="#how_can_I_help-menu">^</a>
</div>
<div style="margin-left: 15px">
<p> Join one of the Forrest project <a href="../mail-lists.html">mailing lists</a> and
tell us what you would like to see improved. We regard all feedback as valuable,
particularly from newcomers&mdash;often, close proximity blinds software developers to
faults that are obvious to everyone else. Don't be shy! </p>
</div>
<a name="N104A5"></a><a name="patch"></a>
<h4 class="faq">5.6. How to contribute a patch? </h4>
<div align="right">
<a href="#patch-menu">^</a>
</div>
<div style="margin-left: 15px">
<p>Please send all contributions via our <a href="../issues.html">issue tracker</a>. Here
are notes about <a href="../contrib.html#patch">making patches</a>. </p>
<p>More info about contributing can be found at the <a href="../contrib.html">Contributing
to Forrest</a> page. It is always a good idea to check the Forrest <a href="../issues.html">issue tracker</a> before diving in. </p>
</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>