Mailing List Archive: svn commit: r1068306 [8/22] - in /forrest/site: docs_0_100/ docs_0_100/howto/ docs_0_100/howto/cvs-ssh/ docs_0_100/howto/multi/ docs_0_100/images/ pluginDocs/plugins_0_100/ trash/ trash/docs_0_50/ trash/docs_0

Added: forrest/site/docs_0_100/faq.html
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_100/faq.html?rev=1068306&view=auto
==============================================================================
--- forrest/site/docs_0_100/faq.html (added)
+++ forrest/site/docs_0_100/faq.html Tue Feb 8 09:44:46 2011
@@ -0,0 +1,2097 @@
+<!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.10-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<title>Frequently Asked Questions (v0.10-dev)</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">
+
+<div class="breadtrail">
+<a href="http://www.apache.org/">Apache Software Foundation</a> > <a href="http://forrest.apache.org/">Apache Forrest</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+
+<div class="header">
+
+<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>
+
+
+<div class="projectlogo">
+<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../images/project-logo.gif" title="Apache Forrest"></a>
+</div>
+
+
+<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"> 
+ <input name="Search" value="Search" type="submit">
+</form>
+</div>
+
+
+<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>
+
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+
+<div id="level2tabs">
+<a class="unselected" href="../docs_0_90/index.html">0.90 (current)</a><a class="selected" href="../docs_0_100/index.html">0.100-dev (under development)</a><a class="unselected" href="../docs_0_80/index.html">0.80 (past)</a>
+</div>
+
+<script type="text/javascript"></script>
+</div>
+
+<div class="breadtrail">
+
+  
+ </div>
+
+
+<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.100-dev</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../docs_0_100/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/your-project.html">Using Forrest</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3', '../skin/')" id="menu_1.1.3Title" class="menutitle">How-To</div>
+<div id="menu_1.1.3" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/howto/index.html">Overview</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.2', '../skin/')" id="menu_1.1.3.2Title" class="menutitle">Install Forrest</div>
+<div id="menu_1.1.3.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/build.html" title="Build and install the current unreleased version">Building Forrest from Source</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/upgrading_010.html">Upgrading to 0.10-dev</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.4', '../skin/')" id="menu_1.1.3.4Title" class="menutitle">Customize Forrest</div>
+<div id="menu_1.1.3.4" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/sitemap-explain.html">Sitemaps explained</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-custom-html-source.html">Custom html source</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/project-sitemap.html">Project sitemap</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-editcss.html">Edit CSS (WYSIWYG)</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-pdf-tab.html" title="Generate one pdf-document for all pages of a tab">Create tab PDF</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-corner-images.html">CSS corner SVG</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.5', '../skin/')" id="menu_1.1.3.5Title" class="menutitle">Integrate Forrest with tools</div>
+<div id="menu_1.1.3.5" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-forrest-from-maven.html">Maven Integration</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/catalog.html">Using DTD Catalogs</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.6', '../skin/')" id="menu_1.1.3.6Title" class="menutitle">Extend Forrest</div>
+<div id="menu_1.1.3.6" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-buildPlugin.html">Build a Plugin</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/skin-package.html">Package new Skins</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-asf-mirror.html">Download mirror</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.8', '../skin/')" id="menu_1.1.3.8Title" class="menutitle">Adding Documentation</div>
+<div id="menu_1.1.3.8" class="menuitemgroup">
+<div class="menuitem">
+<a href="../howto-howto.html" title="Instructions for writing a new howto-document">Write a How-to</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.8.2', '../skin/')" id="menu_1.1.3.8.2Title" class="menutitle">Multipage HowTo</div>
+<div id="menu_1.1.3.8.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/howto/multi/howto-multi.html">Introduction</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/multi/step1.html">Step 1</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/multi/step2.html">Step 2</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/multi/step3.html">Step 3</a>
+</div>
+</div>
+</div>
+</div>
+<div class="menupage">
+<div class="menupagetitle">FAQs</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.5', '../skin/')" id="menu_1.1.5Title" class="menutitle">Background</div>
+<div id="menu_1.1.5" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/linking.html">Menus and Linking</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/searching.html">Search Options in Forrest</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/locationmap.html">Locationmap</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/properties.html">Properties system</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/sitemap-ref.html">Sitemap Reference</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/skins.html" title="About default skins, their naming and features">Skins</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/status-themes.html">Dispatcher versus Skins</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/cap.html">Sourcetype Action</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/validation.html">XML validation and entity resolution</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/changes.html">Changes</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/glossary.html">Glossary</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.8', '../skin/')" id="menu_1.1.8Title" class="menutitle">Reference docs</div>
+<div id="menu_1.1.8" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.1.8.1', '../skin/')" id="menu_1.1.8.1Title" class="menutitle">DTD documentation</div>
+<div id="menu_1.1.8.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.8.2', '../skin/')" id="menu_1.1.8.2Title" class="menutitle">Doc samples</div>
+<div id="menu_1.1.8.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.9', '../skin/')" id="menu_1.1.9Title" class="menutitle">Older Docs</div>
+<div id="menu_1.1.9" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/primer.html">Forrest Primer</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/libre-intro.html">Libre</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/dreams.html">Dream list</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/cvs-ssh/howto-cvs-ssh.html">CVS over SSH</a>
+</div>
+</div>
+</div>
+<div id="credit">
+<hr>
+ This is documentation for development version v0.10-dev
+ (<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>
+
+<div id="credit2">
+<a href="http://www.apache.org/events/current-event.html"><img border="0" title="ApacheCon" alt="ApacheCon - logo" src="http://www.apache.org/events/current-event-125x125.png" style="width: 125px;height: 125px;"></a>
+</div>
+</div>
+
+
+<div id="content">
+<div class="trail">Font size:
+  <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
+  <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+  <input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
+</div>
+<h1>Frequently Asked Questions</h1>
+<div id="front-matter">
+<div id="motd-area">
+ This is documentation for development version v0.10-dev
+ (<a href="http://forrest.apache.org/versions/">More</a>)</div>
+<div id="minitoc-area">
+<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="#docs">1.3. Where is all of the documentation?</a>
+</li>
+<li>
+<a href="#requirements">1.4. What are the system requirements for Forrest? </a>
+</li>
+<li>
+<a href="#cvs">1.5. The old xml-forrest CVS code repository seems to be stale. What happened? </a>
+</li>
+<li>
+<a href="#svn">1.6. How can I use SVN to keep up to date with the latest codebase? </a>
+</li>
+<li>
+<a href="#older-plugins">1.7. How to use older versions of specific plugins? </a>
+</li>
+<li>
+<a href="#single-document">1.8. What is the best way to generate "standalone documents" using Forrest? </a>
+</li>
+<li>
+<a href="#cygwin_mutex_error">1.9. 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="#oldjing">1.10. On Java 6 fails validate-sitemap task. Missing the RELAX NG datatype library.</a>
+</li>
+<li>
+<a href="#winjava">1.11. Windows gets confused about which Java version to use.</a>
+</li>
+<li>
+<a href="#maxmemory">1.12. How can I specify the amount of memory to be used by Java? </a>
+</li>
+<li>
+<a href="#debug">1.13. How can I start forrest in Java debug mode? </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="#crawler">2.4.
+ Help, one of my documents is not being rendered.
+ </a>
+</li>
+<li>
+<a href="#PDF-output">2.5. 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.6. How do I insert page breaks into documents?</a>
+</li>
+<li>
+<a href="#clickable-email-address">2.7. How can I generate html-pages to show a 'clickable' email-address (of the
+ author-element)?</a>
+</li>
+<li>
+<a href="#link_raw">2.8. How do I link to raw files such as config.txt and brochure.pdf? </a>
+</li>
+<li>
+<a href="#pdf_images">2.9. Images don't display in PDFs. How do I fix this?</a>
+</li>
+<li>
+<a href="#tab-index">2.10. The tab link in my site incorrectly assumes that 'index.html' is present in the
+ linked-to directory. How do I fix this? </a>
+</li>
+<li>
+<a href="#tab-site">2.11. I need help with the interaction between tabs.xml and site.xml </a>
+</li>
+<li>
+<a href="#defaultFileName">2.12. 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.13. How can I use a start-up-page other than index.html? </a>
+</li>
+<li>
+<a href="#output-filename-extension">2.14. How to use a different filename extension for output, e.g. *.php? </a>
+</li>
+<li>
+<a href="#php">2.15. How to generate pages ready for serving via PHP? </a>
+</li>
+<li>
+<a href="#label-entity">2.16. How to use special characters in the labels of the site.xml file? </a>
+</li>
+<li>
+<a href="#encoding">2.17. Does Forrest handle accents for non-English languages?</a>
+</li>
+<li>
+<a href="#xml-entities">2.18. How to use XML entities, for example string
+ replacement?</a>
+</li>
+<li>
+<a href="#cleanSite">2.19. How to make Forrest clean up the project build directories? </a>
+</li>
+<li>
+<a href="#i18n">2.20. How can I internationalise (i18n) my content?</a>
+</li>
+<li>
+<a href="#rawHTML">2.21. How can I include HTML content that is not to be skinned by Forrest?</a>
+</li>
+<li>
+<a href="#javascript">2.22. How to include additional Javascript and CSS files?</a>
+</li>
+<li>
+<a href="#linkmap">2.23. How to show a Table Of Contents for the whole site?</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#technical">3. Technical</a>
+<ul class="minitoc">
+<li>
+<a href="#java-code">3.1. Where is the Java code?</a>
+</li>
+<li>
+<a href="#populate-cache">3.2. How to enhance the responsiveness of the cache?</a>
+</li>
+<li>
+<a href="#proxy_config">3.3. 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.4. How can I generate html-pages to show the Revision tag of CVS or SVN?</a>
+</li>
+<li>
+<a href="#cli-xconf">3.5. 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.6. 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.7. Some of my files are not being processed because they use common filenames. </a>
+</li>
+<li>
+<a href="#build_msg_a">3.8. What do the symbols and numbers mean when Forrest lists each document that it has
+ built? </a>
+</li>
+<li>
+<a href="#headless_operation">3.9. When generating PNG images from SVG, I get an error: Can't connect to X11 window
+ server using ':0.0' as the value of the DISPLAY variable. </a>
+</li>
+<li>
+<a href="#project-logo-svg">3.10.
+ The project logo that is generated from SVG is truncating my project name.
+ </a>
+</li>
+<li>
+<a href="#catalog">3.11. How do i configure my favourite XML editor or parser to find the local Forrest
+ DTDs? </a>
+</li>
+<li>
+<a href="#project-dtd">3.12. How to configure the Catalog Entity Resolver to use my own local project DTDs?</a>
+</li>
+<li>
+<a href="#local-catalog">3.13. We need an additional system-wide catalog to share DTDs between projects</a>
+</li>
+<li>
+<a href="#debug-catalog">3.14. How to debug the Catalog Entity Resolver and local DTDs?</a>
+</li>
+<li>
+<a href="#skin">3.15. How to make the site look better and change its skin? </a>
+</li>
+<li>
+<a href="#xsp">3.16. How do I enable XSP processing?</a>
+</li>
+<li>
+<a href="#breadcrumbs">3.17. How do breadcrumbs work? Why don't they work locally?</a>
+</li>
+<li>
+<a href="#run_port">3.18. How do I make forrest run listen on a different port?</a>
+</li>
+<li>
+<a href="#debugging">3.19. Can I run Forrest with Java debugging turned on?</a>
+</li>
+<li>
+<a href="#checksums">3.20. How do I enable Cocoon's document checksum feature?</a>
+</li>
+<li>
+<a href="#sitemap-entities">3.21. How to configure some Cocoon sitemap components, e.g. output html encoding or doctype?</a>
+</li>
+<li>
+<a href="#svn-eol-style">3.22. Why are there SVN diffs for some documents, even though they have not changed?</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="#verbose-ant">5.5. How to filter or reduce the standard output messages? </a>
+</li>
+<li>
+<a href="#coloured-ant">5.6. How to enabled coloured standard output messages? </a>
+</li>
+<li>
+<a href="#how_can_I_help">5.7. How to help? </a>
+</li>
+<li>
+<a href="#patch">5.8. How to contribute a patch? </a>
+</li>
+<li>
+<a href="#jobs">5.9. How can job positions be advertised? </a>
+</li>
+<li>
+<a href="#press">5.10. Is there a press kit? Who can journalists contact?</a>
+</li>
+<li>
+<a href="#security">5.11. How to report a security issue?</a>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+</div>
+<a name="getting_started"></a>
+<h2 class="underlined_10">1. Getting Started and Building Forrest</h2>
+<div class="section">
+<a name="faq"></a>
+<h3 class="underlined_5">1.1. How to use these FAQs? </h3>
+<p>
+ There is no particular order to these FAQs. Use your browser's "Find
+ in this page" facility to search for keywords.
+ </p>
+<a name="overview"></a>
+<h3 class="underlined_5">1.2. Where can I read an overview about how to work with Forrest? </h3>
+<p>
+ See the <a href="../docs_0_100/your-project.html">Using Forrest</a> guide.
+ </p>
+<a name="docs"></a>
+<h3 class="underlined_5">1.3. Where is all of the documentation?</h3>
+<p>
+ You have a local copy of the main documentation with your version of
+ Forrest. Do 'cd site-author; forrest run' and visit
+ <span class="codefrag">http://localhost:8888/</span> in your browser. The most recent documentation
+ is in SVN trunk which creates the forrest.apache.org website.
+ </p>
+<p>
+ Each <a href="../pluginDocs/plugins_0_100/index.html">plugin</a> has its own
+ documentation and working examples of its techniques.
+ </p>
+<p>
+ The example seed site has other documentation and working examples of
+ various techniques. Do 'cd my-new-directory; forrest seed-sample;
+ forrest run'. Every hour the forrestbot generates a static version of
+ this documentation on our <a href="http://forrest.zones.apache.org/">testing zone</a>.
+ </p>
+<a name="requirements"></a>
+<h3 class="underlined_5">1.4. What are the system requirements for Forrest? </h3>
+<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.5 (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>
+<a name="cvs"></a>
+<h3 class="underlined_5">1.5. The old xml-forrest CVS code repository seems to be stale. What happened? </h3>
+<p>
+ Forrest switched from a CVS code repository to SVN (Subversion) code
+ repository. The old CVS repository is closed and not kept current.
+ </p>
+<a name="svn"></a>
+<h3 class="underlined_5">1.6. How can I use SVN to keep up to date with the latest codebase? </h3>
+<p>
+ Follow these <a href="../docs_0_100/howto/../build.html">Building Forrest</a> notes.
+ </p>
+<p>
+ The <a href="../docs_0_100/your-project.html">Using Forrest</a> guide provides
+ further step-by-step assistance in getting started with Forrest for
+ your project.
+ </p>
+<a name="older-plugins"></a>
+<h3 class="underlined_5">1.7. How to use older versions of specific plugins? </h3>
+<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_100/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>
+<a name="single-document"></a>
+<h3 class="underlined_5">1.8. What is the best way to generate "standalone documents" using Forrest? </h3>
+<p>
+ There is a trick that can cut down your turnaround time with building.
+ In forrest.properties ...
+ </p>
+<pre class="code">
+# The URL to start crawling from
+#project.start-uri=linkmap.html
+ </pre>
+<p>
+ Uncomment that and set it to the specific page that you want. Forrest
+ will build that single document, then of course it will keep crawling
+ links from there. It might be confined to a sub-directory, but
+ depending on links could end up generating the whole site. The main
+ thing is that your page of interest is built first.
+ </p>
+<p>
+ It is probably easiest to make this change temporarily as a
+ command-line parameter, e.g.
+ </p>
+<pre class="code">
+forrest -Dproject.start-uri=live-sites.html
+ </pre>
+<p>
+ You can terminate forrest with 'kill' or Ctrl-C after it has built
+ your pages of interest.
+ </p>
+<p>
+ Cocoon can be instructed via the <a href="#cli-xconf">Cocoon
+ cli.xconf</a> file to not follow links (see its "follow-links"
+ parameter). So this will build only the document that was specified.
+ Be careful, if you also usually build PDF pages, then they will not be
+ built.
+ </p>
+<p>
+ Cocoon can also be instructed to not process certain URIs if you need
+ to temporarily exclude then.
+ </p>
+<p>
+ Another useful technique is to use 'wget' or Apache Ant's Get task to
+ retrieve individual files, e.g. Do 'forrest run' and then
+ <span class="codefrag">'wget http://localhost:8888/index.pdf'</span>
+
+</p>
+<a name="cygwin_mutex_error"></a>
+<h3 class="underlined_5">1.9. When running ./build.sh in cygwin, I get an error: cygpath.exe:
+ *** can't create title mutex, Win32 error 6. </h3>
+<p>
+ This
+ <a href="http://issues.apache.org/jira/browse/FOR-10">appears
+ to be a bug in cygwin</a>. Please use the .bat script instead.
+ </p>
+<a name="oldjing"></a>
+<h3 class="underlined_5">1.10. On Java 6 fails validate-sitemap task. Missing the RELAX NG datatype library.</h3>
+<pre class="code">
+validate-sitemap:
+apache-forrest-0.8/main/webapp/resources/schema/relaxng/sitemap-v06.rng:72:31:
+error: datatype library "http://www.w3.org/2001/XMLSchema-datatypes" not recognized
+</pre>
+<p>
+ The version of Jing needs to be updated.
+ </p>
+<p>
+ This is fixed in Forrest-0.9-dev version.
+ See <a href="http://issues.apache.org/jira/browse/FOR-984">FOR-984</a>.
+ </p>
+<p>
+ One workaround is to update your copy of the
+ <a href="http://code.google.com/p/jing-trang/">Jing</a> jar at
+ <span class="codefrag">$FORREST_HOME/lib/core/</span>
+
+</p>
+<p>
+ Another workaround is to edit the forrest.properties configuration file
+ to expose the "forrest.validate.sitemap" property and set it to "false".
+ Might need to do the same for the "forrest.validate.stylesheets" property.
+ </p>
+<a name="winjava"></a>
+<h3 class="underlined_5">1.11. Windows gets confused about which Java version to use.</h3>
+<p>
+ Cough, yes!. See this
+ <a href="http://mail-archives.apache.org/mod_mbox/forrest-user/200704.mbox/%3c462CA40F.5020400@rblasch.org%3e">explanation</a>
+ on the Forrest mail lists.
+ </p>
+<a name="maxmemory"></a>
+<h3 class="underlined_5">1.12. How can I specify the amount of memory to be used by Java? </h3>
+<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">main/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>
+<a name="debug"></a>
+<h3 class="underlined_5">1.13. How can I start forrest in Java debug mode? </h3>
+<p>
+ The <span class="codefrag">forrest.jvmargs</span> property in the
+ <span class="codefrag">forrest.properties</span> file can be used to start forrest in
+ debug mode on a specific port. <span class="codefrag">forrest.jvmargs=-Xdebug
+ -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n</span>
+
+</p>
+</div>
+<a name="content_faqs"></a>
+<h2 class="underlined_10">2. Content Creation</h2>
+<div class="section">
+<a name="edit-content"></a>
+<h3 class="underlined_5">2.1. What tools can be used to edit the content?</h3>
+<p>
+ If you are using the Apache Forrest XML
+ <a href="../docs_0_100/../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_100/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>
+<a name="site-xml"></a>
+<h3 class="underlined_5">2.2.
+ How to use the site.xml configuration file for menus and linking.
+ </h3>
+<p>
+ The <span class="codefrag">site.xml</span> configuration file is used for two different
+ purposes: defining the navigation menus, and as a method for defining
+ references to be used when linking between documents. This file is
+ fully explained in <a href="../docs_0_100/linking.html">Menus and Linking</a>.
+ Here is a precis:
+ </p>
+<p>
+ The labels can be whatever text you want.
+ </p>
+<pre class="code">
+<faq label="FAQs" href="faq.html">
+ <tech label="Technical" href="faq-tech.html">
+ <docbook href="#docbook"/>
+ <ignoring_javadocs href="#ignoring_javadocs"/>
+ </tech>
+ <user label="User" href="faq-user.html">
+</faq>
+ </pre>
+<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">
+<a href="site:faq/tech"> link to the top of the Tech FAQs
+<a href="site:faq/tech/docbook"> link to the DocBook FAQ in the Tech FAQs
+ </pre>
+<p>
+ If that "docbook" entry was a unique name in your site.xml then you
+ can shorten that latter link:
+ </p>
+<pre class="code">
+<a href="site:docbook"> link to the DocBook FAQ in the Tech FAQs
+ </pre>
+<a name="examples"></a>
+<h3 class="underlined_5">2.3.
+ Where are examples of documents and site.xml and tabs.xml files?
+ </h3>
+<p>
+ There are examples in the 'forrest seed site' and also the Forrest
+ website documents are included with the distribution (<span class="codefrag">cd
+ forrest/site-author; forrest run</span>).
+ </p>
+<a name="crawler"></a>
+<h3 class="underlined_5">2.4.
+ Help, one of my documents is not being rendered.
+ </h3>
+<p>
+ Did you make a link to it? Forrest does not find documents by scanning
+ the filesystem to find the source documents. Rather it starts at one
+ document and crawls the links to find other documents to process.
+ </p>
+<p>
+ There are essentially two ways to create links. Via a site.xml file to
+ define the navigation and menu structure, or via direct relative
+ linking. See the to previous FAQs.
+ </p>
+<p>
+ Normally the source material will be local. The Forrest crawler does
+ not follow and process off-site links. The new locationmap (0.8+)
+ enables content to be drawn from remote sources.
+ </p>
+<a name="PDF-output"></a>
+<h3 class="underlined_5">2.5. How can I generate one pdf-file out of the whole site or selected pages of the site?</h3>
+<p>
+ Add the following entries to your site.xml file.
+ Note that the href must be exactly "wholesite" or "site" which triggers
+ a special match in the sitemap to aggregate all documents.
+ </p>
+<pre class="code">
+
+ <about tab="home" label="About" href="">
+ ...
+ <all_site label="Full HTML" href="wholesite.html"/>
+ <all_sitePDF label="Full PDF" href="wholesite.pdf"/>
+ ...
+ </about>
+ </pre>
+<p>
+ In this case the menu labeled "About" will have 2 new items: "Full
+ PDF" and "Full HTML".
+ </p>
+<p>
+ See also <a href="../docs_0_100/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_100/linking.html">site.xml</a> method for your site
+ structure and navigation, rather than the old book.xml method.
+ </p>
+<div class="warning">
+<div class="label">Warning</div>
+<div class="content">
+ There are many issues with the "wholesite" aggregation. Search the
+ issue tracker and mail lists.
+ </div>
+</div>
+<a name="pageBreaks"></a>
+<h3 class="underlined_5">2.6. How do I insert page breaks into documents?</h3>
+<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>
+<a name="clickable-email-address"></a>
+<h3 class="underlined_5">2.7. How can I generate html-pages to show a 'clickable' email-address (of the
+ author-element)?</h3>
+<p>
+ You would override <span class="codefrag">
+ $FORREST_HOME/main/webapp/skins/common/xslt/html/document-to-html.xsl</span>
+ and edit the "headers/authors" template.
+ </p>
+<a name="link_raw"></a>
+<h3 class="underlined_5">2.8. How do I link to raw files such as config.txt and brochure.pdf? </h3>
+<p>
+ Handling of raw files was significantly changed in Forrest 0.7. See
+ <a href="../trash/docs_0_70/upgrading_07.html#raw">Upgrading to Apache Forrest
+ 0.7</a> for all the details.
+ </p>
+<a name="pdf_images"></a>
+<h3 class="underlined_5">2.9. Images don't display in PDFs. How do I fix this?</h3>
+<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
+ <span class="codefrag">http://java.sun.com/products/java-media/jai</span>). 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>
+<a name="tab-index"></a>
+<h3 class="underlined_5">2.10. The tab link in my site incorrectly assumes that 'index.html' is present in the
+ linked-to directory. How do I fix this? </h3>
+<p>
+ In <span class="codefrag">tabs.xml</span>, use @href instead of @dir, and omit the
+ trailing '/'. Which file to serve is then a concern of the sitemap.
+ For example, if the "User Manual" tab should link to
+ <span class="codefrag">manual/Introduction.html</span> then <span class="codefrag">tabs.xml</span>
+ should contain:
+ </p>
+<pre class="code">
+
+ <tab label="User Manual" href="manual"/>
+ </pre>
+<p>
+ and add this rule to the sitemap:
+ </p>
+<pre class="code">
+
+ <map:match pattern="manual">
+ <map:redirect-to uri="manual/Introduction.html"/>
+ </map:match>
+ </pre>
+<a name="tab-site"></a>
+<h3 class="underlined_5">2.11. I need help with the interaction between tabs.xml and site.xml </h3>
+<p>
+ See the <a href="../docs_0_100/linking.html#tab-site">tips</a>.
+ </p>
+<a name="defaultFileName"></a>
+<h3 class="underlined_5">2.12. 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/ ? </h3>
+<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
+ <default-filename>index.html</default-filename>
+ with 'overview.html'. </li>
+
+<li> Edit your project's <a href="../docs_0_100/project-sitemap.html">sitemap.xmap</a> file. </li>
+
+<li> Add the following code just before the end of the pipelines-element:<pre class="code">
+
+ <map:pipeline>
+ <map:match type="regexp" pattern="^.+/$">
+ <map:redirect-to uri="overview.html"/>
+ </map:match>
+ </map:pipeline>
+
+ </pre>
+</li>
+
+</ol>
+<a name="defaultStartPage"></a>
+<h3 class="underlined_5">2.13. How can I use a start-up-page other than index.html? </h3>
+<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_100/project-sitemap.html">sitemap.xmap</a> file.</li>
+
+<li>Add the following code just before the end of the pipelines-element:<pre class="code">
+
+ <map:pipeline>
+ <map:match pattern="">
+ <map:redirect-to uri="start.html" />
+ </map:match>
+ </map:pipeline>
+
+ </pre>
+</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>
+<a name="output-filename-extension"></a>
+<h3 class="underlined_5">2.14. How to use a different filename extension for output, e.g. *.php? </h3>
+<p>
+ Use the power of the Cocoon sitemaps. There is default handling for *.php (see main/webapp/sitemap.xmap) to map the 'php' extension to an internal request for "html". See more about <a href="#php">PHP</a> below.
+ </p>
+<p>
+ Use the same internal re-direction technique for your special needs, e.g. copy that php match to your project sitemap and use ".htm" instead.
+ </p>
+<a name="php"></a>
+<h3 class="underlined_5">2.15. How to generate pages ready for serving via PHP? </h3>
+<p>
+ Use the *.php filename extension (see <a href="#output-filename-extension">above</a>)
+ for the output html links in site.xml navigation. Add your php processing instructions to the source documents.
+ </p>
+<p>
+ However, beware <a href="http://issues.apache.org/jira/browse/FOR-999">FOR-999</a>
+ "processing-instruction nodes in source are not always passed through to html output"
+ whereby only PIs in certain body elements are handled.
+ </p>
+<a name="label-entity"></a>
+<h3 class="underlined_5">2.16. How to use special characters in the labels of the site.xml file? </h3>
+<p>
+ Use the numeric values for character entities. For example, rather
+ than using <span class="codefrag">
+&ouml;
+ </span> use <span class="codefrag">
+&#246;
+ </span>
+
+</p>
+<p>
+ See the
+ <a href="http://www.w3.org/TR/xhtml-modularization/dtd_module_defs.html#a_xhtml_character_entities">XHTML
+ Character Entities</a> and see more discussion at
+ <a href="http://issues.apache.org/jira/browse/FOR-244">Issue
+ FOR-244</a>.
+ </p>
+<a name="encoding"></a>
+<h3 class="underlined_5">2.17. Does Forrest handle accents for non-English languages?</h3>
+<p>
+ Yes, Forrest can process text in any language, so you can include:
+ </p>
+<ul>
+
+<li>accents: á é í ó ú</li>
+
+<li>diereses: ä ë ï ö ü</li>
+
+<li>tildes: ã ñ Ã„Â© õ Ã…Â©</li>
+
+</ul>
+<p>
+ This is because sources for Forrest docs are XML documents, which can
+ include any of these, provided the encoding declared by the XML doc
+ matches the actual encoding used in the file. For example if you
+ declare the default encoding:
+ </p>
+<pre class="code">
+<?xml version="1.0" encoding="UTF-8"?>
+ </pre>
+<p>
+ but the file content is actually using ISO-8859-1 then you will
+ receive validation errors, especially if you include some non-ASCII
+ characters.
+ </p>
+<p>
+ This situation is commonly encountered when you edit the templates
+ created by <span class="codefrag">forrest seed</span> with your favorite (probably
+ localized) editor without paying attention to the encoding, or when
+ you create a new file and simply copy the headers from another file.
+ </p>
+<p>
+ Although UTF-8 is an encoding well-suited for most languages, it is
+ not usually the default in popular editors or systems. In UNIX-like
+ systems, most popular editors can handle different encodings to write
+ the file in disk. With some editors the encoding of the file is
+ preserved, while with others the default is used regardless of the
+ original encoding. In most cases the encoding used to write files can
+ be controlled by setting the environment variable <span class="codefrag">LANG</span> to
+ an appropriate value, for instance:
+ </p>
+<pre class="code">[localhost]$ export LANG=en_US.UTF-8</pre>
+<p>
+ Of course the <em>appropriate</em> way to set the encoding depends on
+ the editor/OS, but ultimately relys on the user preferences. So you
+ can use the encoding you prefer, as long as the <span class="codefrag">encoding</span>
+ attribute of the XML declaration matches the actual encoding of the
+ file. This means that if you are not willing to abandon ISO-8859-1 you
+ can always use the following declaration instead:
+ </p>
+<pre class="code">
+<?xml version="1.0" encoding="ISO-8859-1"?>
+ </pre>
+<p>
+ Another option is to use "character entities" such as <span class="codefrag">
+&ouml;
+ </span> (ö) or the numeric form <span class="codefrag">
+&#246;
+ </span> (ö).
+ </p>
+<p>
+ Another related issue is that your webserver needs to send http
+ headers with the matching charset definitions to the html page.
+ </p>
+<p>
+ Here are some references which explain further:
+ <a href="http://orixo.com/events/gt2004/bios.html#torsten">GT2004
+ presentation by Torsten Schlabach</a> and
+ <a href="http://www.alanwood.net/unicode/">Alan Wood's Unicode
+ resources</a>.
+ </p>
+<a name="xml-entities"></a>
+<h3 class="underlined_5">2.18. How to use XML entities, for example string
+ replacement?</h3>
+<p>
+ A set of symbols is available. See the demonstration in a fresh
+ 'forrest seed' site (at
+ <a href="http://forrest.zones.apache.org/ft/build/forrest-seed/samples-b/xml-entities.html">samples-b/xml-entities.html</a>).
+ For example, use
+ "<span class="codefrag">&myp-t;</span>" to represent the project name together with
+ trademark symbol "My Project Name™". Avoid lengthy typing and
+ potential spelling errors.
+ </p>
+<a name="cleanSite"></a>
+<h3 class="underlined_5">2.19. How to make Forrest clean up the project build directories? </h3>
+<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>
+<a name="i18n"></a>
+<h3 class="underlined_5">2.20. How can I internationalise (i18n) my content?</h3>
+<p>
+ For example, navigation
+ menus can be internationalized and different content can be served.
+ </p>
+<p>
+ There is an example to demonstrate and explain the facilities.
+ See a 'forrest seed-sample' site.
+ </p>
+<p>
+ All internationalisation of tokens is carried out by the
+ <a href="http://cocoon.apache.org/2.1/userdocs/i18nTransformer.html">Cocoon
+ i18n Transformer</a>.
+ </p>
+<a name="rawHTML"></a>
+<h3 class="underlined_5">2.21. How can I include HTML content that is not to be skinned by Forrest?</h3>
+<p>
+ To serve, for example a legacy HTML site, add something like the
+ following to your project's sitemap and place the source content in a
+ <span class="codefrag">src/documentation/content/old_site/</span> directory.
+ </p>
+<pre class="code">
+
+ <map:match pattern="old_site/**.html">
+ <map:select type="exists">
+ <map:when test="{properties:content}{0}">
+ <map:read src="{properties:content}{0}" mime-type="text/html"/>
+
+ </map:when>
+ </map:select>
+ </map:match>
+ </pre>
+<p>
+ Exactly what the match should be is dependant on your content
+ structure. It is outside the scope of this FAQ to provide full
+ details, but new users may like to refer to the
+ <a href="../docs_0_100/sitemap-ref.html">Cocoon sitemap</a> docs.
+ </p>
+<p>
+ There is a more detailed discussion of this topic in the samples of a
+ freshly seeded site. To see this documentation do the following:
+ </p>
+<ol>
+
+<li>mkdir seed</li>
+
+<li>cd seed</li>
+
+<li>forrest seed-sample</li>
+
+<li>forrest run</li>
+
+<li>
+<span class="codefrag">http://localhost:8888/samples-b/linking.html#no-decoration</span>
+</li>
+
+</ol>
+<a name="javascript"></a>
+<h3 class="underlined_5">2.22. How to include additional Javascript and CSS files?</h3>
+<p>
+ Place various resources (e.g. javascript, css) into the "project
+ skins" directory. The default forrest.properties has this at
+ src/documentation/skins/$skin-name/ Javascript files would go in a
+ "scripts" subdirectory. CSS files would go in a "css" subdirectory.
+ </p>
+<p>
+ Then refer to those from your source documents with URIs like
+ /skin/blah.js and /skin/foo.css
+ </p>
+<p>
+ See how this is handled in the core sitemap called
+ forrest/main/webapp/resources.xmap Search for "javascript" then follow
+ to the <map:resource name="skin-read"> section.
+ </p>
+<a name="linkmap"></a>
+<h3 class="underlined_5">2.23. How to show a Table Of Contents for the whole site?</h3>
+<p>
+ Every site has an automatically generated document at
+ <span class="codefrag">/linkmap.html</span> which is produced from the site.xml
+ navigation configuration. It uses the @label and absolutized @href and
+ element name and @description attribute for each node.
+ </p>
+<p>
+ For example, the Forrest project's <a href="../linkmap.html">Site
+ Linkmap Table of Contents</a>.
+ </p>
+<p>
+ The document is also useful when developing your documentation and
+ linking to other docs. The element names (column #2) e.g.
+ href="site:<strong>mail-lists</strong>" or
+ href="site:<strong>howto/overview</strong>"
+ </p>
+<p>
+ This is also the document that 'forrest site' uses to kick-start the
+ Cocoon crawler which then follows links to build each page. See the
+ project.start-uri in the forrest.properties file.
+ </p>
+</div>
+<a name="technical"></a>
+<h2 class="underlined_10">3. Technical</h2>
+<div class="section">
+<a name="java-code"></a>
+<h3 class="underlined_5">3.1. Where is the Java code?</h3>
+<p>
+ Because we are based on Apache Cocoon, a lot of the functionality is
+ provided behind-the-scenes, i.e. we use Cocoon's sitemaps and sitemap
+ components such as XSLT transformers. So there is not much need for
+ Java code in Forrest.
+ </p>
+<p>
+ For Forrest developers who want to explore or enhance that code, see
+ the Apache Cocoon SVN trunk. From time-to-time we update Forrest's
+ packaged version of Cocoon and so can include your contributions.
+ </p>
+<p>
+ That said, you will find some Java code in Forrest at main/java/...
+ for Cocoon components that have been developed at Forrest, e.g.
+ Locationmap and Dispatcher. There is also Java code for some plugins
+ with specialised purpose, e.g. PhotoGallery.
+ </p>
+<a name="populate-cache"></a>
+<h3 class="underlined_5">3.2. How to enhance the responsiveness of the cache?</h3>
+<p>
+ Apache Cocoon has a sophisticated cache. When running Forrest in
+ dynamic mode, the initial visitor will receive slower response. The
+ very first page served will cause Cocoon to cache the pipelines. Later
+ requests will re-use those cached components and add others to the
+ cache. A good technique is to warm up the cache after the forrest
+ webapp has been re-started. Requesting the front page alone will
+ populate the cache with the common items used for other pages. Using a
+ spider such as wget, will warm up everything.
+ </p>
+<p>
+ The Cocoon cache and sitemaps can be tuned. See
+ <a href="http://cocoon.apache.org/2.1/performancetips.html">Cocoon
+ Performance Tips</a> and
+ <a href="http://wiki.apache.org/cocoon/CocoonPerformance">CocoonPerformance</a>
+ and the "Object Stores" section of
+ main/webapp/WEB-INF/cocoon.xconf
+ </p>
+<p>
+ Responsiveness can be further enhanced by utilising a transparent
+ proxy server, e.g. Apache HTTP Server as a frontend. See
+ <a href="http://wiki.apache.org/cocoon/ApacheModProxy">CocoonAndApacheModProxy</a>.
+ </p>
+<a name="proxy_config"></a>
+<h3 class="underlined_5">3.3. I'm behind a proxy and it's preventing Plugins from being downloaded, what should I
+ do?</h3>
+<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 class="note">
+<div class="label">Generalise the proxy configuration</div>
+<div class="content">
+ You certainly need to cross your proxy for every Forrest projects you
+ have. To avoid to edit every project <span class="codefrag">forrest.properties</span>
+ files, you can do once in your
+ <span class="codefrag">${user.home}/forrest.properties</span> !
+ </div>
+</div>
+<a name="CVS_revison_tags"></a>
+<h3 class="underlined_5">3.4. How can I generate html-pages to show the Revision tag of CVS or SVN?</h3>
+<p>
+ If you have:<span class="codefrag"><version>$Revision: 1.30
+ $</version></span>The '1.30' will be extracted and
+ displayed at the bottom of the page as "version 1.30". See for
+ example the bottom of the <a href="../docs_0_100/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>
+<p>
+ When using Subversion, remember to set the relevant svn:keywords
+ properties.
+ </p>
+<a name="cli-xconf"></a>
+<h3 class="underlined_5">3.5. How to control the processing of URIs by Cocoon, e.g. exclude certain URIs, include
+ other additional ones. </h3>
+<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">
+
+ ....
+ 
+ <strong>
+
+ <exclude pattern="**/"/>
+ <exclude pattern="**apidocs**"/>
+ <exclude pattern="api/**"/>
+ </strong>
+
+ <uri src="favicon.ico"/>
+</cocoon>
+ </pre>
+<p>
+ This is just an example, and you should modify it appropriately for
+ your site.
+ </p>
+<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_100/sitemap-ref.html">sitemap</a>. For example,
+ <strong>foo/*</strong> would match <span class="codefrag">foo/bar</span>, but not
+ <span class="codefrag">foo/bar/baz</span> — use <strong>foo/**</strong> to match
+ that.
+ </div>
+</div>
+<p>
+ See the example "<a href="../docs_0_100/howto/howto-asf-mirror.html">HowTo Generate an ASF mirrors page</a>"
+ which explains how to include non-linked extra documents to the processing
+ using the Cocoon CLI.
+ </p>
+<a name="ignoring_javadocs"></a>
+<h3 class="underlined_5">3.6. How do I stop Forrest breaking on links to external files that may not exist, like
+ javadocs? </h3>
+<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>
+<a name="claimed_patterns"></a>
+<h3 class="underlined_5">3.7. Some of my files are not being processed because they use common filenames. </h3>
+<p>
+ Certain patterns are claimed by the default sitemaps for special
+ processing. These reserved words include: <span class="codefrag">site, wholesite, 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>
+<a name="build_msg_a"></a>
+<h3 class="underlined_5">3.8. What do the symbols and numbers mean when Forrest lists each document that it has
+ built? </h3>
+<p>
+ Each time that Cocoon processes a link, it will report the status
+ messages ...
+ </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 (pagesComplete/pagesRemaining). The latter will change because during processing one page, Cocoon will discover more.</li>
+
+<li>Column 3 is the number of links that were gathered from that page (newLinksInPage/linksInPage).</li>
+
+<li>Column 4 is the time taken.</li>
+
+<li>Column 5 is the page size.</li>
+
+</ul>
+<a name="headless_operation"></a>
+<h3 class="underlined_5">3.9. When generating PNG images from SVG, I get an error: Can't connect to X11 window
+ server using ':0.0' as the value of the DISPLAY variable. </h3>
+<p>
+ If you are using JDK 1.5 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>
+<a name="project-logo-svg"></a>
+<h3 class="underlined_5">3.10.
+ The project logo that is generated from SVG is truncating my project name.
+ </h3>
+<p>
+ In a 'forrest seed site' the project and the group logo are generated
+ from a Scalable Vector Graphics (SVG) file, using the text from the
+ <span class="codefrag"><project-name></span> and <span class="codefrag"><group-name></span>
+ elements of the <span class="codefrag">skinconf.xml</span> file. If you have a long
+ project-name then you may need to adjust the width of the image.
+ Perhaps you want to change the colours too. Edit the file at
+ <span class="codefrag">src/documentation/content/xdocs/images/project.svg</span> and
+ adjust the "width" attribute of the <svg> element. For further
+ details see <a href="http://www.w3.org/Graphics/SVG/">SVG</a>
+ resources.
+ </p>
+<a name="catalog"></a>
+<h3 class="underlined_5">3.11. How do i configure my favourite XML editor or parser to find the local Forrest
+ DTDs? </h3>
+<p>
+ Notes are provided for various tools at
+ <a href="../docs_0_100/catalog.html">Using Catalog Entity Resolver for local
+ DTDs</a>.
+ </p>
+<a name="project-dtd"></a>
+<h3 class="underlined_5">3.12. How to configure the Catalog Entity Resolver to use my own local project DTDs?</h3>
+<p>
+ See <a href="../docs_0_100/your-project.html#new_dtd">Using Forrest</a> for
+ configuration guidance.
+ </p>
+<a name="local-catalog"></a>
+<h3 class="underlined_5">3.13. We need an additional system-wide catalog to share DTDs between projects</h3>
+<p>
+ See <a href="../docs_0_100/validation.html#catalog">Using Forrest</a> for
+ configuration guidance.
+ </p>
+<a name="debug-catalog"></a>
+<h3 class="underlined_5">3.14. How to debug the Catalog Entity Resolver and local DTDs?</h3>
+<p>
+ See <a href="../docs_0_100/validation.html#debug-catalog">XML validation</a>.
+ </p>
+<a name="skin"></a>
+<h3 class="underlined_5">3.15. How to make the site look better and change its skin? </h3>
+<p>
+ There are <a href="../docs_0_100/your-project.html#skins">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_100/your-project.html#skins">configuration</a> of the
+ skins. Some projects may have special needs and can define their
+ <a href="../docs_0_100/your-project.html#new_skin">own skin</a>.
+ </p>
+<a name="xsp"></a>
+<h3 class="underlined_5">3.16. How do I enable XSP processing?</h3>
+<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://svn.apache.org/repos/asf/cocoon/trunk/lib/optional/">jdtcore-*.jar</a> from Cocoons SVN tree, and copy it to the $FORREST_HOME/main/webapp/WEB-INF/lib
+ directory (or lib/core/ directory in the source distribution).</li>
+
+<li>
+<p>
+ Add the following generator definition in the map:generators
+ section of your
+ <a href="../docs_0_100/project-sitemap.html">project
+ sitemap</a>
+
+</p>
+
+<pre class="code">
+
+ <map:generator name="serverpages"
+ pool-grow="2" pool-max="32" pool-min="4"
+ src="org.apache.cocoon.generation.ServerPagesGenerator"/>
+ </pre>
+</li>
+
+<li>
+<p>
+ Decide how you want to use XSP. For single files, you could just
+ define a *.xml matcher:
+ </p>
+
+<pre class="code">
+
+<map:match pattern="dynamic.xml">
+ <map:generate src="content/xdocs/dynamic.xsp" type="serverpages"/>
+ ...
+ <map:serialize type="xml"/>
+</map:match>
+ </pre>
+
+<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>
+<a name="breadcrumbs"></a>
+<h3 class="underlined_5">3.17. How do breadcrumbs work? Why don't they work locally?</h3>
+<p>
+ Breadcrumbs begin with up to three URLs specified in
+ <span class="codefrag">skinconf.xml</span>. Here is what the Forrest site uses:
+ </p>
+<pre class="code">
+
+ <trail>
+ <link1 name="Apache Software Foundation" href="http://www.apache.org/"/>
+ <link2 name="Apache Forrest" href="http://forrest.apache.org/"/>
+ <link3 name="" href=""/>
+ </trail>
+ </pre>
+<p>
+ If any links are blank, they are not used. After these first links,
+ JavaScript looks at the URL for the current page and makes a link for
+ each directory after the domain. If you are viewing the site locally,
+ there is no domain and so there will be no extra breadcrumbs, only the
+ ones that are specified in <span class="codefrag">skinconf.xml</span>.
+ </p>
+<a name="run_port"></a>
+<h3 class="underlined_5">3.18. How do I make forrest run listen on a different port?</h3>
+<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>
+<a name="debugging"></a>
+<h3 class="underlined_5">3.19. Can I run Forrest with Java debugging turned on?</h3>
+<p>
+ If you use an IDE like Eclipse and want to debug java code in Forrest
+ you need to start Forrest with debugging mode turned on. To do this
+ you need to add <span class="codefrag">-Xdebug
+ -Xrunjdwp:transport=dt_socket,address=8000,server=y,susp end=n</span>
+ to the <span class="codefrag">forrest.jvmargs</span> property in the
+ <span class="codefrag">forrest.properties</span> file. Don't forget to ensure the
+ property is uncommented in that file.
+ </p>
+<a name="checksums"></a>
+<h3 class="underlined_5">3.20. How do I enable Cocoon's document checksum feature?</h3>
+<p>
+ Why might you want to do this? There is really no effect on Cocoon
+ processing, but a little time can be saved on filesystem writes, which
+ will accumulate to a big savings for a site with thousands of files.
+ </p>
+<p>
+ Some tools depend on the "date-last-modified" timestamp of the
+ generated files. For example, the Forrestbot will then deploy only the
+ modified files.
+ </p>
+<p>
+ There was some discussion about this on the Forrest developer mailing
+ list:
+ <a href="http://marc.theaimsgroup.com/?l=forrest-dev&s=cocoon+checksum">Cocoon
+ Checksum</a> Specifically note that this feature only stops Cocoon
+ from writing to disk if the new file is the same as the existing file.
+ Cocoon still spends the same amount of time generating the content as
+ it would if checksums were not enabled.
+ </p>
+<p>
+ Locate the <span class="codefrag">checksums-uri</span> tag within cli.xconf and replace
+ the contents with an absolute path and filename for the checksums
+ file. Projects can supply their own (see FAQ:
+ <a href="#cli-xconf">Cocoon cli.xconf</a>) or use the default
+ installation-wide cli.xconf file.
+ </p>
+<a name="sitemap-entities"></a>
+<h3 class="underlined_5">3.21. How to configure some Cocoon sitemap components, e.g. output html encoding or doctype?</h3>
+<p>
+ The core Cocoon components are defined in the
+ <span class="codefrag">main/webapp/sitemap.xmap</span> file. Normally the default
+ settings are suitable. There are some things that you might like to
+ change per project. For example, change the html encoding for output
+ html files from the default UTF-8 or configure a different document
+ type declaration for the Dispatcher.
+ </p>
+<p>
+ Create a fresh site with 'forrest seed' and see the set of symbols at the
+ <span class="codefrag">src/documentation/resources/schema/symbols-project-v10.ent</span> file.
+ Copy that file to your own projects at the same location. Also add the
+ entry to your project xml catalog as shown in the seed site at
+ <span class="codefrag">src/documentation/resources/schema/catalog.xcat</span> file.
+ </p>
+<p>
+ Now copy the particular entity that you wish to re-define from
+ <span class="codefrag">main/webapp/resources/schema/entity/symbols-core-v10.ent</span>
+ file into your project symbols file and edit the entity declaration.
+ Re-start Forrest.
+ </p>
+<a name="svn-eol-style"></a>
+<h3 class="underlined_5">3.22. Why are there SVN diffs for some documents, even though they have not changed?</h3>
+<p>
+ These un-necessary differences happen because the comitter who did 'svn add' for those files
+ did not have their Subversion client configured properly for the "svn:eol-style" setting.
+ See some <a href="../tasks.html#subversion-monitoring">notes</a>
+ about rectifying this issue.
+ </p>
+</div>
+<a name="old_faqs"></a>
+<h2 class="underlined_10">4. Older version: 0.6</h2>
+<div class="section">
+<a name="old_claimed_patterns"></a>
+<h3 class="underlined_5">4.1. Some of my files are not being processed because they use common filenames. </h3>
+<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="general"></a>
+<h2 class="underlined_10">5. General</h2>
+<div class="section">
+<a name="generating_menus"></a>
+<h3 class="underlined_5">5.1. What is the relationship between site.xml and book.xml? </h3>
+<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_100/linking.html">Menus and Linking</a>.
+ </p>
+<a name="docbook"></a>
+<h3 class="underlined_5">5.2. How do I use DocBook as the XML documentation format? </h3>
+<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_100/project-sitemap.html">project sitemap</a> as explained
+ in <a href="../docs_0_100/your-project.html">Using Forrest</a> and add matches
+ to handle your DocBook documents. Here is an example. Note that you
+ need to change it to suit your situation. The match must be very
+ specific so that only the DocBook documents are matched. The rest of
+ the documents will be handled by Forrest core. Powerful regex
+ capabilities are available.
+ </p>
+<pre class="code">
+<?xml version="1.0"?>
+<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
+ <map:pipelines>
+ <map:pipeline>
+ <map:match pattern="resolver-*.html">
+ <map:generate src="{properties:content.xdocs}resolver-{1}.xml"/>
+ <map:transform
+ src="file:///usr/share/sgml/docbook/xsl-stylesheets/xhtml/docbook.xsl"/>
+ <map:serialize type="xhtml"/>
+ </map:match>
+ </map:pipeline>
+ </map:pipelines>
+</map:sitemap>
+ </pre>
+<p>
+ You need to define the xhtml serializer used in <map:serialize
+ type="xhtml"/> in the components section of the sitemap. See the
+ <a href="http://cocoon.apache.org/2.1/userdocs/serializers/xhtml-serializer.html">Cocoon
+ docs</a> for the elements you need to add to define this component.
+ You can see examples of other components being added in the
+ <span class="codefrag">FORREST_HOME/main/webapp/sitemap.xmap</span> file. Alternatively
+ use the "html" DocBook stylesheets and the default Cocoon serializer,
+ i.e. <map:serialize type="html"/>
+ </p>
+<p>
+ The output of the above sitemap will be plain html not adorned with a
+ Forrest theme and navigation. If instead you need the latter, then use
+ the following technique instead. This transforms DocBook xml to html,
+ then uses a Forrest core stylesheet to transform and serialize to the
+ internal xml format, then the normal machinery takes over and does the
+ output transformation. This use the Content Aware Pipelines
+ (<a href="../docs_0_100/cap.html">SourceTypeAction</a>) to peek at the source
+ xml. If it is DocBook-4.2 then this sitemap match is triggered, if not
+ then it falls through to the core of Forrest.
+ </p>
+<pre class="code">
+<?xml version="1.0"?>
+<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
+ <map:components>
+ <map:actions>
+ <map:action logger="sitemap.action.sourcetype"
+ name="sourcetype"src="org.apache.forrest.sourcetype.SourceTypeAction">
+ <sourcetype name="docbook-v4.2">
+ <document-declaration public-id="-//OASIS//DTD DocBook XML V4.2//EN"/>
+ </sourcetype>
+ </map:action>
+ </map:actions>
+ <map:selectors default="parameter">
+ <map:selector logger="sitemap.selector.parameter"
+ name="parameter" src="org.apache.cocoon.selection.ParameterSelector"/>
+ </map:selectors>
+ </map:components>
+ <map:pipelines>
+ <map:pipeline>
+ <map:match pattern="**.xml">
+ <map:act type="sourcetype" src="{properties:content.xdocs}{1}.xml">
+ <map:select type="parameter">
+ <map:parameter name="parameter-selector-test" value="{sourcetype}"/>
+ <map:when test="docbook-v4.2">
+ <map:generate src="{properties:content.xdocs}{../1}.xml"/>
+ <map:transform
+ src="file:///usr/share/sgml/docbook/xsl-stylesheets/html/docbook.xsl"/>
+ <map:transform src="{forrest:forrest.stylesheets}/html-to-document.xsl"/>
+ <map:transform type="idgen"/>
+ <map:serialize type="xml-document"/>
+ </map:when>
+ </map:select>
+ </map:act>
+ </map:match>
+ </map:pipeline>
+ </map:pipelines>
+</map:sitemap>
+ </pre>
+<p>
+ You can also use a mixture of the methods, some handled automatically
+ by Forrest and some directly using DocBook stylesheets. You can also
+ have a mixture of source files as "document-v*" DTD and DocBook.
+ </p>
+<p>
+ Ensure that the document type declaration in your XML instance is well
+ specified. Use a public identifier. The DTD will then be properly
+ resolved by Forrest. If you need to use different DTDs, then see
+ <a href="../docs_0_100/your-project.html#new_dtd">Using Forrest</a> for
+ configuration guidance.
+ </p>
+<a name="version"></a>
+<h3 class="underlined_5">5.3. How to report which version of Forrest is being used and the properties that are
+ set? </h3>
+<p>
+ Do <span class="codefrag">'forrest -projecthelp'</span> or <span class="codefrag">'./build.sh'</span> to
+ find the version number.
+ Also when starting <span class="codefrag">'forrest'</span> or <span class="codefrag">'forrest run'</span>
+ the versions are reported for forrest, java, and ant.
+ </p>
+<p>
+ To list the properties and other stuff, 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 and other useful
+ information.
+ </p>
+<p>
+ In <span class="codefrag">'forrest run'</span> mode, use the
+ <a href="../tools/forrestbar.html">Forrestbar</a> to see the build-info
+ and properties, or access them directly:
+ </p>
+<ul>
+
+<li>
+<span class="codefrag">http://localhost:8888/build-info</span>
+</li>
+
+<li>
+<span class="codefrag">http://localhost:8888/module.properties.properties</span>
+</li>
+
+</ul>
+<p>
+ See the documentation about the new <a href="../docs_0_100/properties.html">Properties</a>
+ system.
+ </p>
+<a name="logs"></a>
+<h3 class="underlined_5">5.4. Where are the log files to find more infomation about errors? </h3>
+<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">main/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/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>
+<a name="verbose-ant"></a>
+<h3 class="underlined_5">5.5. How to filter or reduce the standard output messages? </h3>
+<p>
+ Where normally you would do
+ <span class="codefrag">'forrest'</span> or <span class="codefrag">'forrest run'</span> etc. instead use
+ the "quiet" option, and do
+ <span class="codefrag">'forrest -q'</span> or <span class="codefrag">'forrest -q run'</span> etc.
+ If errors are reported, then drop the "quiet" option and run again to
+ get the context for the error.
+ </p>
+<p>
+ Doing <span class="codefrag">'forrest -v'</span> will provide very verbose build messages to
+ the standard output.
+ </p>
+<a name="coloured-ant"></a>
+<h3 class="underlined_5">5.6. How to enabled coloured standard output messages? </h3>
+<p>
+ Adding colour to the forrest output messages will greatly assist
+ readability.
+ </p>
+<p>
+ Set the ANT_ARGS environment variable like so:<br>
+
+<span class="codefrag">export ANT_ARGS="$ANT_ARGS -logger org.apache.tools.ant.listener.AnsiColorLogger"</span>
+
+</p>
+<p>
+ To change the default colours, set the ANT_OPTS environment variable
+ like so:<br>
+
+<span class="codefrag">export ANT_OPTS="$ANT_OPTS -Dant.logger.defaults=$FORREST_HOME/etc/AnsiColorLogger.properties"</span>
+<br>
+ and create that configuration file as
+ <a href="http://ant.apache.org/manual/listeners.html#AnsiColorLogger">explained</a>
+ in the Apache Ant Manual.
+ That is required on Mac OS X and the "Attribute" for each colour needs
+ to be "0" rather than the default "2".
+ </p>
+<p>
+ Note that not all terminals support ANSI color codes.
+ </p>
+<a name="how_can_I_help"></a>
+<h3 class="underlined_5">5.7. How to help? </h3>
+<p>
+ Join one of the Forrest project <a href="../mail-lists.html">mailing
+ lists</a> and tell us what you would like to see improved. We
+ regard all feedback as valuable, particularly from
+ newcomers—often, close proximity blinds software developers to
+ faults that are obvious to everyone else. Don't be shy!
+ </p>
+<a name="patch"></a>
+<h3 class="underlined_5">5.8. How to contribute a patch? </h3>
+<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>
+<a name="jobs"></a>
+<h3 class="underlined_5">5.9. How can job positions be advertised? </h3>
+<p>
+ Employers can send notices about employment opportunities. There is a
+ special jobs<AT>apache.org mailing list. You can also send these
+ notices to the project mailing lists, e.g. dev list at Forrest or
+ Cocoon (add [jobs] to the subject line). You can also approach
+ particular developers off-list. However only genuine jobs, not pleas
+ for free support (see <a href="../mail-lists.html">mailing
+ lists</a>).
+ </p>
+<p>
+ Some enlightened employers enable their employees to contribute
+ material which was created during work time using work-related
+ resources. Please note the need to file a Corporate Contributor
+ License Agreement
+ (<a href="http://www.apache.org/licenses/">CCLA</a>) with The
+ Apache Software Foundation.
+ </p>
+<a name="press"></a>
+<h3 class="underlined_5">5.10. Is there a press kit? Who can journalists contact?</h3>
+<p>
+ Press enquiries should be co-ordinated through the ASF Public Relations Committee (PRC).
+ See <a href="http://www.apache.org/foundation/contact.html">contact</a> information.
+ The PRC also provides guidelines and handles particular usage of ASF
+ trademarks and logos (see also
+ <a href="http://www.apache.org/foundation/licence-FAQ.html#Marks">FAQ</a>
+ and
+ <a href="http://www.apache.org/foundation/marks/">Guidelines</a>).
+ </p>
+<p>
+ The Apache Forrest logo
+ (<a href="/images/project-logo.png">PNG</a>)
+ and banner (<a href="http://svn.apache.org/repos/asf/forrest/trunk/site-author/resources/images/apache-forrest-original.svg">SVG</a>
+ | <a href="/images/apache-forrest.png">PNG</a>)
+ are available.
+ Unfortunately the logo is only available as PNG.
+ </p>
+<a name="security"></a>
+<h3 class="underlined_5">5.11. How to report a security issue?</h3>
+<p>
+ Security and vulnerability issues are co-ordinated through the
+ <a href="http://www.apache.org/security/">ASF Security Team</a>.
+ This is only for reporting undisclosed security vulnerabilities in
+ Apache products. For other issues, use the Forrest project
+ <a href="../issues.html">Issue tracker</a>.
+ </p>
+</div>
+</div>
+
+<div class="clearboth"> </div>
+</div>
+<div id="footer">
+
+<div class="lastmodified">
+<script type="text/javascript"></script>
+</div>
+<div class="copyright">
+ Copyright ©
+ 2002-2011 <a href="http://www.apache.org/licenses/">The Apache Software Foundation. Licensed under Apache License 2.0</a>
+<br>
+ Apache Forrest, Forrest, Apache, the Apache feather logo, and the Apache Forrest
+ logos are trademarks of The Apache Software Foundation.
+ </div>
+
+</div>
+</body>
+</html>

Propchange: forrest/site/docs_0_100/faq.html
------------------------------------------------------------------------------
svn:eol-style = native