| <!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.8-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"> |
| <!--+ |
| |breadtrail |
| +--> |
| <div class="breadtrail"> |
| <a href="http://www.apache.org/">apache</a> > <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"> |
| <input name="Search" value="Search" type="submit"> |
| </form> |
| </div> |
| <!--+ |
| |end search |
| +--> |
| <!--+ |
| |start Tabs |
| +--> |
| <ul id="tabs"> |
| <li> |
| <a class="unselected" href="../index.html">Welcome</a> |
| </li> |
| <li> |
| <a class="unselected" href="../contrib.html">Developers</a> |
| </li> |
| <li class="current"> |
| <a class="selected" href="../versions/index.html">Versioned Docs</a> |
| </li> |
| <li> |
| <a class="unselected" href="../pluginDocs/index.html">Plugins</a> |
| </li> |
| <li> |
| <a class="unselected" href="../tools/index.html">Tools</a> |
| </li> |
| </ul> |
| <!--+ |
| |end Tabs |
| +--> |
| </div> |
| </div> |
| <div id="main"> |
| <div id="publishedStrip"> |
| <!--+ |
| |start Subtabs |
| +--> |
| <div id="level2tabs"> |
| <a class="unselected" href="../docs_0_70/index.html">0.70 (current)</a><a class="selected" 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"> |
| |
| |
| </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.80-dev</div> |
| <div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;"> |
| <div class="menuitem"> |
| <a href="../docs_0_80/index.html">Overview</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/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_80/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_80/build.html" title="Build and install the current unreleased version">Building Forrest from Source</a> |
| </div> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/upgrading_08.html">Upgrading to 0.8</a> |
| </div> |
| <div class="menuitem"> |
| <a href="">Use Forrest</a> |
| </div> |
| <div onclick="SwitchMenu('menu_1.1.3.5', '../skin/')" id="menu_1.1.3.5Title" class="menutitle">Customize Forrest</div> |
| <div id="menu_1.1.3.5" class="menuitemgroup"> |
| <div class="menuitem"> |
| <a href="../docs_0_80/sitemap-explain.html">Sitemaps explained</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/howto/howto-custom-html-source.html">Custom html source</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/project-sitemap.html">Project sitemap</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/howto/howto-editcss.html">Edit CSS (WYSIWYG)</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/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_80/howto/howto-corner-images.html">CSS corner SVG</a> |
| </div> |
| </div> |
| <div onclick="SwitchMenu('menu_1.1.3.6', '../skin/')" id="menu_1.1.3.6Title" class="menutitle">Integrate Forrest with tools</div> |
| <div id="menu_1.1.3.6" class="menuitemgroup"> |
| <div class="menuitem"> |
| <a href="../docs_0_80/howto/howto-forrest-from-maven.html">Maven Integration</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/catalog.html">Using DTD Catalogs</a> |
| </div> |
| </div> |
| <div onclick="SwitchMenu('menu_1.1.3.7', '../skin/')" id="menu_1.1.3.7Title" class="menutitle">Extend Forrest</div> |
| <div id="menu_1.1.3.7" class="menuitemgroup"> |
| <div class="menuitem"> |
| <a href="../docs_0_80/howto/howto-buildPlugin.html">Build a Plugin</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/skin-package.html">Package new Skins</a> |
| </div> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/howto/howto-asf-mirror.html">Download mirror</a> |
| </div> |
| <div onclick="SwitchMenu('menu_1.1.3.9', '../skin/')" id="menu_1.1.3.9Title" class="menutitle">Adding Documentation</div> |
| <div id="menu_1.1.3.9" 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.9.2', '../skin/')" id="menu_1.1.3.9.2Title" class="menutitle">Multipage HowTo</div> |
| <div id="menu_1.1.3.9.2" class="menuitemgroup"> |
| <div class="menuitem"> |
| <a href="../docs_0_80/howto/multi/howto-multi.html">Introduction</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/howto/multi/step1.html">Step 1</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/howto/multi/step2.html">Step 2</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/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_80/linking.html">Menus and Linking</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/searching.html">Search Options in Forrest</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/locationmap.html">Locationmap</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/sitemap-ref.html">Sitemap Reference</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/skins.html" title="About default skins, their naming and features">Skins</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/status-themes.html">Dispatcher versus Skins</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/cap.html">Sourcetype Action</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/validation.html">XML validation and entity resolution</a> |
| </div> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/changes.html">Changes</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/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_80/primer.html">Forrest Primer</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/libre-intro.html">Libre</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/dreams.html">Dream list</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/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.8 |
| (<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: |
| <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="motd-area"> |
| This is documentation for development version v0.8 |
| (<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="#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="#maxmemory">1.10. How can I specify the amount of memory to be used by Java? </a> |
| </li> |
| <li> |
| <a href="#debug">1.11. 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="#label-entity">2.14. How to use special characters in the labels of the site.xml file? </a> |
| </li> |
| <li> |
| <a href="#encoding">2.15. Does Forrest handle accents for non-English languages?</a> |
| </li> |
| <li> |
| <a href="#xml-entities">2.16. How to use XML entities, for example string |
| replacement?</a> |
| </li> |
| <li> |
| <a href="#cleanSite">2.17. How to make Forrest clean up the project build directories? </a> |
| </li> |
| <li> |
| <a href="#i18n">2.18. How can I internationalise (i18n) my content?</a> |
| </li> |
| <li> |
| <a href="#rawHTML">2.19. How can I include HTML content that is not to be skinned by Forrest?</a> |
| </li> |
| <li> |
| <a href="#javascript">2.20. How to include additional Javascript and CSS files?</a> |
| </li> |
| <li> |
| <a href="#linkmap">2.21. 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> |
| </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> |
| <li> |
| <a href="#jobs">5.7. How can job positions be advertised? </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_80/your-project.html">Using Forrest</a> guide. |
| </p> |
| </div> |
| <a name="N10024"></a><a name="docs"></a> |
| <h4 class="faq">1.3. Where is all of the documentation?</h4> |
| <div align="right"> |
| <a href="#docs-menu">^</a> |
| </div> |
| <div style="margin-left: 15px"> |
| <p> |
| You have a local copy of the main documentation with your version of |
| Forrest. Do 'cd site-author; forrest run' and visit |
| http://localhost:8888/ in your browser. The most recent documentation |
| is in SVN trunk which creates the forrest.apache.org website. |
| </p> |
| <p> |
| Each <a href="../pluginDocs/plugins_0_80/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> |
| </div> |
| <a name="N1003A"></a><a name="requirements"></a> |
| <h4 class="faq">1.4. 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="N10045"></a><a name="cvs"></a> |
| <h4 class="faq">1.5. 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="N1004D"></a><a name="svn"></a> |
| <h4 class="faq">1.6. 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_80/howto/../build.html">Building Forrest</a> notes. |
| </p> |
| <p> |
| The <a href="../docs_0_80/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="N10060"></a><a name="older-plugins"></a> |
| <h4 class="faq">1.7. 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_80/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="N10081"></a><a name="single-document"></a> |
| <h4 class="faq">1.8. 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> |
| 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 'wget |
| http://localhost:8888/index.pdf'. |
| </p> |
| </div> |
| <a name="N100A7"></a><a name="cygwin_mutex_error"></a> |
| <h4 class="faq">1.9. 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="N100B9"></a><a name="maxmemory"></a> |
| <h4 class="faq">1.10. 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">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> |
| </div> |
| <a name="N100D6"></a><a name="debug"></a> |
| <h4 class="faq">1.11. How can I start forrest in Java debug mode? </h4> |
| <div align="right"> |
| <a href="#debug-menu">^</a> |
| </div> |
| <div style="margin-left: 15px"> |
| <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="N100E7"></a><a name="content_faqs"></a> |
| <h3 class="underlined_5">2. Content Creation</h3> |
| <a name="N100EB"></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_80/../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_80/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="N10105"></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 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_80/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> |
| </div> |
| <a name="N10133"></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 (<span class="codefrag">cd |
| forrest/site-author; forrest run</span>). |
| </p> |
| </div> |
| <a name="N1013E"></a><a name="crawler"></a> |
| <h4 class="faq">2.4. |
| Help, one of my documents is not being rendered. |
| </h4> |
| <div align="right"> |
| <a href="#crawler-menu">^</a> |
| </div> |
| <div style="margin-left: 15px"> |
| <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> |
| </div> |
| <a name="N1014C"></a><a name="PDF-output"></a> |
| <h4 class="faq">2.5. 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"> |
| |
| <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". (See also <a href="../docs_0_80/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_80/linking.html">site.xml</a> method for your site |
| structure and navigation, rather than the old book.xml method. |
| </p> |
| </div> |
| <a name="N10166"></a><a name="pageBreaks"></a> |
| <h4 class="faq">2.6. 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="N10184"></a><a name="clickable-email-address"></a> |
| <h4 class="faq">2.7. 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/document-to-html.xsl</span> |
| and edit the "headers/authors" template. |
| </p> |
| </div> |
| <a name="N1018F"></a><a name="link_raw"></a> |
| <h4 class="faq">2.8. 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="N1019B"></a><a name="pdf_images"></a> |
| <h4 class="faq">2.9. 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 |
| <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> |
| </div> |
| <a name="N101CA"></a><a name="tab-index"></a> |
| <h4 class="faq">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? </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"> |
| |
| <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> |
| </div> |
| <a name="N101E6"></a><a name="tab-site"></a> |
| <h4 class="faq">2.11. 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_80/linking.html#tab-site">tips</a>. |
| </p> |
| </div> |
| <a name="N101F2"></a><a name="defaultFileName"></a> |
| <h4 class="faq">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/ ? </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 |
| <default-filename>index.html</default-filename> |
| with 'overview.html'. </li> |
| |
| <li> Edit your project's <a href="../docs_0_80/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> |
| </div> |
| <a name="N1021A"></a><a name="defaultStartPage"></a> |
| <h4 class="faq">2.13. 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_80/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> |
| </div> |
| <a name="N1023E"></a><a name="label-entity"></a> |
| <h4 class="faq">2.14. 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"> |
| &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> |
| </div> |
| <a name="N10257"></a><a name="encoding"></a> |
| <h4 class="faq">2.15. 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: á é í ó ú</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> |
| </div> |
| <a name="N102A9"></a><a name="xml-entities"></a> |
| <h4 class="faq">2.16. How to use XML entities, for example string |
| replacement?</h4> |
| <div align="right"> |
| <a href="#xml-entities-menu">^</a> |
| </div> |
| <div style="margin-left: 15px"> |
| <p> |
| A set of symbols is available. See the demonstration in a fresh |
| 'forrest seed' site (at samples/xml-entities.html). 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> |
| </div> |
| <a name="N102B4"></a><a name="cleanSite"></a> |
| <h4 class="faq">2.17. 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="N102BF"></a><a name="i18n"></a> |
| <h4 class="faq">2.18. 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/i18nTransformer.html">Cocoon |
| i18n Transformer</a>. You can see an example of how it works in the |
| above linked issue. |
| </p> |
| </div> |
| <a name="N102D2"></a><a name="rawHTML"></a> |
| <h4 class="faq">2.19. How can I include HTML content that is not to be skinned by Forrest?</h4> |
| <div align="right"> |
| <a href="#rawHTML-menu">^</a> |
| </div> |
| <div style="margin-left: 15px"> |
| <p> |
| To serve, for example a legacy HTML site, add something like the |
| following to your project's sitemap and place the source content at |
| the <span class="codefrag">src/documentation/content/xdocs/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"/> |
| <!-- |
| Use this instead if you want JTidy to clean up your HTML |
| <map:generate type="html" src="{properties:content}/{0}" /> |
| <map:serialize type="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_80/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</li> |
| |
| <li> |
| <span class="codefrag">http://localhost:8888/samples/linking.html#no-decoration</span> |
| </li> |
| |
| </ol> |
| </div> |
| <a name="N102FE"></a><a name="javascript"></a> |
| <h4 class="faq">2.20. How to include additional Javascript and CSS files?</h4> |
| <div align="right"> |
| <a href="#javascript-menu">^</a> |
| </div> |
| <div style="margin-left: 15px"> |
| <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> |
| </div> |
| <a name="N1030C"></a><a name="linkmap"></a> |
| <h4 class="faq">2.21. How to show a Table Of Contents for the whole site?</h4> |
| <div align="right"> |
| <a href="#linkmap-menu">^</a> |
| </div> |
| <div style="margin-left: 15px"> |
| <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="N1032A"></a><a name="technical"></a> |
| <h3 class="underlined_5">3. Technical</h3> |
| <a name="N1032E"></a><a name="java-code"></a> |
| <h4 class="faq">3.1. Where is the Java code?</h4> |
| <div align="right"> |
| <a href="#java-code-menu">^</a> |
| </div> |
| <div style="margin-left: 15px"> |
| <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> |
| </div> |
| <a name="N1033C"></a><a name="populate-cache"></a> |
| <h4 class="faq">3.2. How to enhance the responsiveness of the cache?</h4> |
| <div align="right"> |
| <a href="#populate-cache-menu">^</a> |
| </div> |
| <div style="margin-left: 15px"> |
| <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/forrest-core.xconf |
| </p> |
| <p> |
| Responsiveness can be further enhanced by utilising a transparent |
| proxy server, e.g. Apache HTTP Server as a frontend. See |
| <a href="http://wiki.apache.org/cocoon/ApacheModProxy">CocoonAndApacheModProxy</a>. |
| </p> |
| </div> |
| <a name="N10356"></a><a name="proxy_config"></a> |
| <h4 class="faq">3.3. 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 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> |
| </div> |
| <a name="N1037A"></a><a name="CVS_revison_tags"></a> |
| <h4 class="faq">3.4. How can I generate html-pages to show the Revision tag of CVS or SVN?</h4> |
| <div align="right"> |
| <a href="#CVS_revison_tags-menu">^</a> |
| </div> |
| <div style="margin-left: 15px"> |
| <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_80/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> |
| </div> |
| <a name="N1038F"></a><a name="cli-xconf"></a> |
| <h4 class="faq">3.5. 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"> |
| |
| .... |
| <!-- Includes and excludes can be used to limit which URLs are rendered --> |
| <strong> |
| |
| <exclude pattern="**/"/> |
| <exclude pattern="**apidocs**"/> |
| <exclude pattern="api/**"/> |
| </strong> |
| |
| <uri src="favicon.ico"/> |
| </cocoon> |
| </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_80/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> |
| </div> |
| <a name="N103CC"></a><a name="ignoring_javadocs"></a> |
| <h4 class="faq">3.6. 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="N103DB"></a><a name="claimed_patterns"></a> |
| <h4 class="faq">3.7. 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 reserved words 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="N103ED"></a><a name="build_msg_a"></a> |
| <h4 class="faq">3.8. 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> |
| 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> |
| </div> |
| <a name="N1040B"></a><a name="headless_operation"></a> |
| <h4 class="faq">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. </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="N10427"></a><a name="project-logo-svg"></a> |
| <h4 class="faq">3.10. |
| 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"><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> |
| </div> |
| <a name="N1043F"></a><a name="catalog"></a> |
| <h4 class="faq">3.11. How do i configure my favourite XML editor or parser to find the local Forrest |
| DTDs? </h4> |
| <div align="right"> |
| <a href="#catalog-menu">^</a> |
| </div> |
| <div style="margin-left: 15px"> |
| <p> |
| Notes are provided for various tools at |
| <a href="../docs_0_80/catalog.html">Using Catalog Entity Resolver for local |
| DTDs</a>. |
| </p> |
| </div> |
| <a name="N1044B"></a><a name="project-dtd"></a> |
| <h4 class="faq">3.12. How to configure the Catalog Entity Resolver to use my own local project DTDs?</h4> |
| <div align="right"> |
| <a href="#project-dtd-menu">^</a> |
| </div> |
| <div style="margin-left: 15px"> |
| <p> |
| See <a href="../docs_0_80/your-project.html#new_dtd">Using Forrest</a> for |
| configuration guidance. |
| </p> |
| </div> |
| <a name="N10457"></a><a name="local-catalog"></a> |
| <h4 class="faq">3.13. We need an additional system-wide catalog to share DTDs between projects</h4> |
| <div align="right"> |
| <a href="#local-catalog-menu">^</a> |
| </div> |
| <div style="margin-left: 15px"> |
| <p> |
| See <a href="../docs_0_80/validation.html#catalog">Using Forrest</a> for |
| configuration guidance. |
| </p> |
| </div> |
| <a name="N10463"></a><a name="debug-catalog"></a> |
| <h4 class="faq">3.14. How to debug the Catalog Entity Resolver and local DTDs?</h4> |
| <div align="right"> |
| <a href="#debug-catalog-menu">^</a> |
| </div> |
| <div style="margin-left: 15px"> |
| <p> |
| See <a href="../docs_0_80/validation.html#debug-catalog">XML validation</a>. |
| </p> |
| </div> |
| <a name="N1046F"></a><a name="skin"></a> |
| <h4 class="faq">3.15. 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_80/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_80/your-project.html#skins">configuration</a> of the |
| skins. Some projects may have special needs and can define their |
| <a href="../docs_0_80/your-project.html#new_skin">own skin</a>. |
| </p> |
| </div> |
| <a name="N10486"></a><a name="xsp"></a> |
| <h4 class="faq">3.16. 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://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_80/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> |
| </div> |
| <a name="N104BD"></a><a name="breadcrumbs"></a> |
| <h4 class="faq">3.17. 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"> |
| |
| <trail> |
| <link1 name="apache" href="http://www.apache.org/"/> |
| <link2 name="xml.apache" href="http://xml.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> |
| </div> |
| <a name="N104D2"></a><a name="run_port"></a> |
| <h4 class="faq">3.18. 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="N104E6"></a><a name="debugging"></a> |
| <h4 class="faq">3.19. Can I run Forrest with Java debugging turned on?</h4> |
| <div align="right"> |
| <a href="#debugging-menu">^</a> |
| </div> |
| <div style="margin-left: 15px"> |
| <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> |
| </div> |
| <a name="N104F7"></a><a name="checksums"></a> |
| <h4 class="faq">3.20. How do I enable Cocoon's document checksum feature?</h4> |
| <div align="right"> |
| <a href="#checksums-menu">^</a> |
| </div> |
| <div style="margin-left: 15px"> |
| <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> |
| </div> |
| <a name="N10513"></a><a name="old_faqs"></a> |
| <h3 class="underlined_5">4. Older version: 0.6</h3> |
| <a name="N10517"></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="N10529"></a><a name="general"></a> |
| <h3 class="underlined_5">5. General</h3> |
| <a name="N1052D"></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_80/linking.html">Menus and Linking</a>. |
| </p> |
| </div> |
| <a name="N10548"></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_80/project-sitemap.html">project sitemap</a> as explained |
| in <a href="../docs_0_80/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_80/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_80/your-project.html#new_dtd">Using Forrest</a> for |
| configuration guidance. |
| </p> |
| </div> |
| <a name="N10581"></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="N10595"></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">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> |
| </div> |
| <a name="N105B9"></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—often, close proximity blinds software developers to |
| faults that are obvious to everyone else. Don't be shy! |
| </p> |
| </div> |
| <a name="N105C5"></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> |
| <a name="N105E0"></a><a name="jobs"></a> |
| <h4 class="faq">5.7. How can job positions be advertised? </h4> |
| <div align="right"> |
| <a href="#jobs-menu">^</a> |
| </div> |
| <div style="margin-left: 15px"> |
| <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> |
| </div> |
| </div> |
| </div> |
| <!--+ |
| |end content |
| +--> |
| <div class="clearboth"> </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 © |
| 2002-2007 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a> |
| </div> |
| <!--+ |
| |end bottomstrip |
| +--> |
| </div> |
| </body> |
| </html> |
