You are viewing a plain text version of this content. The canonical link for it is here.
Posted to svn@forrest.apache.org by cr...@apache.org on 2005/04/11 16:59:14 UTC
svn commit: r160895 [13/28] - in forrest/site/0.7: ./ docs/ docs/howto/
docs/images/ docs/plugins/
Propchange: forrest/site/0.7/docs/faq-v20.dtdx.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/0.7/docs/faq-v20.dtdx.pdf
URL: http://svn.apache.org/viewcvs/forrest/site/0.7/docs/faq-v20.dtdx.pdf?view=auto&rev=160895
==============================================================================
Binary file - no diff available.
Propchange: forrest/site/0.7/docs/faq-v20.dtdx.pdf
------------------------------------------------------------------------------
svn:mime-type = application/pdf
Added: forrest/site/0.7/docs/faq.html
URL: http://svn.apache.org/viewcvs/forrest/site/0.7/docs/faq.html?view=auto&rev=160895
==============================================================================
--- forrest/site/0.7/docs/faq.html (added)
+++ forrest/site/0.7/docs/faq.html Mon Apr 11 07:58:59 2005
@@ -0,0 +1,1328 @@
+<!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.7-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<meta-data></meta-data>
+<title>Frequently Asked Questions (v0.7)</title>
+<link type="text/css" href="../skin/basic.css" rel="stylesheet">
+<link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet">
+<link media="print" type="text/css" href="../skin/print.css" rel="stylesheet">
+<link type="text/css" href="../skin/profile.css" rel="stylesheet">
+<script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script>
+<link rel="shortcut icon" href="../favicon.ico">
+</head>
+<body onload="init()">
+<script type="text/javascript">ndeSetTextSize();</script>
+<div id="top">
+<!--+
+ |breadtrail
+ +-->
+<div class="breadtrail">
+<a href="http://www.apache.org/">apache</a> > <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:');" value="Search the site with google:" size="25" name="q" id="query" type="text">
+ <input name="Search" value="Search" type="submit">
+</form>
+</div>
+<!--+
+ |end search
+ +-->
+<!--+
+ |start Tabs
+ +-->
+<ul id="tabs">
+<li>
+<a class="base-not-selected" href="../index.html">Welcome</a>
+</li>
+<li>
+<a class="base-not-selected" href="../contrib.html">Project</a>
+</li>
+<li class="current">
+<a class="base-selected" href="../docs/index.html">0.7 Docs</a>
+</li>
+<li>
+<a class="base-not-selected" href="../docs/howto/index.html">0.7 How-To</a>
+</li>
+</ul>
+<!--+
+ |end Tabs
+ +-->
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<!--+
+ |start Subtabs
+ +-->
+<div id="level2tabs">
+<a class="base-not-selected" href="..">Core</a> | <a class="base-not-selected" href="..">ForrestBot</a> | <a class="base-not-selected" href="..">ForrestBar</a>
+</div>
+<!--+
+ |end Endtabs
+ +-->
+<script type="text/javascript" language="JavaScript"><!--
+ document.write("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');">Documentation</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a title="" href="../docs/index.html">Overview</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">FAQs</div>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/changes.html">Changes</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/todo.html">Todo</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/your-project.html">Using Forrest</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/validation.html">XML Validation</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/linking.html">Menus and Linking</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/searching.html">Searching</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/skins.html">Default Skins</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/skin-package.html">Skin Packages</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/plugins/usingPlugins.html">Plugins</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/views.html">Views-dev</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrest-contract.html">Our Contract</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/compliance.html">Standards Compliance</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.15', '../skin/')" id="menu_1.1.15Title" class="menutitle">Advanced Topics</div>
+<div id="menu_1.1.15" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/build.html">Building Forrest</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/catalog.html">Using DTD Catalogs</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/sitemap-ref.html">Sitemap Reference</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/project-sitemap.html">Project sitemap</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/plugins/pluginInfrastructure.html">Plugin Infrastructure</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/cap.html">Sourcetype Action</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.16', '../skin/')" id="menu_1.1.16Title" class="menutitle">Other versions</div>
+<div id="menu_1.1.16" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs.html">Overview</a>
+</div>
+<div class="menuitem">
+<a title="" href="http://forrest.apache.org/docs/../0.8/">0.8-dev</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/index.html">0.7 (current)</a>
+</div>
+<div class="menuitem">
+<a title="" href="http://forrest.apache.org/docs/../0.6/">0.6</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.17', '../skin/')" id="menu_1.1.17Title" class="menutitle">Upgrading</div>
+<div id="menu_1.1.17" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/upgrading_07.html">Upgrading to 0.7</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/upgrading_06.html">Upgrading to 0.6</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.18', '../skin/')" id="menu_1.1.18Title" class="menutitle">SubProjects</div>
+<div id="menu_1.1.18" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/forrestbar.html">ForrestBar</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrestbot.html">Forrestbot</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrestbot-web-interface.html">Forrestbot Webapp</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.19', '../skin/')" id="menu_1.1.19Title" class="menutitle">Reference docs</div>
+<div id="menu_1.1.19" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.1.19.1', '../skin/')" id="menu_1.1.19.1Title" class="menutitle">DTD documentation</div>
+<div id="menu_1.1.19.1" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/dtd-docs.html">Overview</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v20.dtdx.html">document-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/howto-v20.dtdx.html">howto-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/faq-v20.dtdx.html">faq-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v13.dtdx.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/howto-v13.dtdx.html">howto-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/faq-v13.dtdx.html">faq-v13</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.19.2', '../skin/')" id="menu_1.1.19.2Title" class="menutitle">Doc samples</div>
+<div id="menu_1.1.19.2" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/document-v13.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v20.html">document-v20</a>
+</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.20', '../skin/')" id="menu_1.1.20Title" class="menutitle">Older Docs</div>
+<div id="menu_1.1.20" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/primer.html">Forrest Primer</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/libre-intro.html">Libre</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/dreams.html">Dream list</a>
+</div>
+</div>
+</div>
+<div id="credit">
+<hr>
+ This is documentation for current release v0.7
+ (<a href="http://forrest.apache.org/docs.html">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>
+<!--+
+ |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 current release v0.7
+ (<a href="http://forrest.apache.org/docs.html">More</a> ...)</div>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#Questions">Questions</a>
+<ul class="minitoc">
+<li>
+<a href="#getting_started">1. Getting Started and Building Forrest</a>
+<ul class="minitoc">
+<li>
+<a href="#overview">1.1.
+ Where can I read an overview about how to work with Forrest?
+ </a>
+</li>
+<li>
+<a href="#requirements">1.2.
+ What are the system requirements for Forrest?
+ </a>
+</li>
+<li>
+<a href="#cvs">1.3.
+ The old xml-forrest CVS code repository seems to be stale. What happened?
+ </a>
+</li>
+<li>
+<a href="#svn">1.4.
+ How can I use SVN to keep up to date with the latest codebase?
+ </a>
+</li>
+<li>
+<a href="#single-document">1.5.
+ What is the best way to generate "standalone documents" using Forrest?
+ </a>
+</li>
+<li>
+<a href="#cygwin_mutex_error">1.6.
+ When running ./build.sh in cygwin, I get an error:
+ cygpath.exe: *** can't create title mutex, Win32 error 6.
+ </a>
+</li>
+<li>
+<a href="#maxmemory">1.7.
+ How can I specify the amount of memory to be used by Java?
+ </a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#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="#PDF-output">2.2. 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.3. How do I insert page breaks into documents?</a>
+</li>
+<li>
+<a href="#clickable-email-address">2.4. How can I generate html-pages to show a
+ 'clickable' email-address (of the author-element)?</a>
+</li>
+<li>
+<a href="#link_raw">2.5. How do I link to raw files such as config.txt and brochure.pdf?
+ </a>
+</li>
+<li>
+<a href="#pdf_images">2.6. Images don't display in PDFs. How do I fix this?</a>
+</li>
+<li>
+<a href="#index.html">2.7.
+ 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="#label-entity">2.8.
+ How to use special characters in the labels of the site.xml file?
+ </a>
+</li>
+<li>
+<a href="#encoding">2.9. Does Forrest handle accents for non-English languages?</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#technical">3. Technical</a>
+<ul class="minitoc">
+<li>
+<a href="#proxy_config">3.1. I'm behind a proxy and it's preventing Plugins from
+ being downloaded, what should I do?</a>
+</li>
+<li>
+<a href="#CVS_revison_tags">3.2. How can I generate html-pages to show the
+ revision tag of cvs?</a>
+</li>
+<li>
+<a href="#ignoring_javadocs">3.3.
+ 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.4. Some of my files are not being processed because they use
+ common filenames.
+ </a>
+</li>
+<li>
+<a href="#build_msg_a">3.5. What do the symbols and numbers mean when Forrest lists each
+ document that it has built?
+ </a>
+</li>
+<li>
+<a href="#headless_operation">3.6.
+ When generating PNG images from SVG, I get an error: Can't connect to X11 window server using ':0.0' as the value of the DISPLAY variable.
+ </a>
+</li>
+<li>
+<a href="#catalog">3.7.
+ How do i configure my favourite XML editor or parser to find the
+ local Forrest DTDs?
+ </a>
+</li>
+<li>
+<a href="#skin">3.8.
+ How to make the site look better and change its skin?
+ </a>
+</li>
+<li>
+<a href="#xsp">3.9. How do I enable XSP processing?</a>
+</li>
+<li>
+<a href="#breadcrumbs">3.10. How do breadcrumbs work? Why don't they work locally?</a>
+</li>
+<li>
+<a href="#run_port">3.11. How do I make forrest run listen on a different port?</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#old_faqs">4. Older version: 0.6</a>
+<ul class="minitoc">
+<li>
+<a href="#old_claimed_patterns">4.1. Some of my files are not being processed because they use
+ common filenames.
+ </a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#general">5. General</a>
+<ul class="minitoc">
+<li>
+<a href="#generating_menus">5.1. What is the relationship between site.xml and
+ book.xml?
+ </a>
+</li>
+<li>
+<a href="#docbook">5.2.
+ How do I use DocBook as the xml documentation format?
+ </a>
+</li>
+<li>
+<a href="#version">5.3.
+ How to report which version of Forrest is being used and the
+ properties that are set?
+ </a>
+</li>
+<li>
+<a href="#logs">5.4.
+ Where are the log files to find more infomation about errors?
+ </a>
+</li>
+<li>
+<a href="#how_can_I_help">5.5.
+ How to help?
+ </a>
+</li>
+<li>
+<a href="#patch">5.6.
+ How to contribute a patch?
+ </a>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+<a name="N10008"></a><a name="Questions"></a>
+<h2 class="underlined_10">Questions</h2>
+<div class="section">
+<a name="N1000C"></a><a name="getting_started"></a>
+<h3 class="underlined_5">1. Getting Started and Building Forrest</h3>
+<a name="N10010"></a><a name="overview"></a>
+<h4 class="faq">1.1.
+ Where can I read an overview about how to work with Forrest?
+ </h4>
+<div align="right">
+<a href="#overview-menu">^</a>
+</div>
+<div style="margin-left: 15px">
+<p>
+ See the <a href="../docs/your-project.html">Using Forrest</a> guide.
+ </p>
+</div>
+<a name="N1001C"></a><a name="requirements"></a>
+<h4 class="faq">1.2.
+ What are the system requirements for Forrest?
+ </h4>
+<div align="right">
+<a href="#requirements-menu">^</a>
+</div>
+<div style="margin-left: 15px">
+<p>
+ Forrest includes everything necessary to build and run, except
+ of course for Java. In addition to all the Cocoon JARs, Forrest
+ includes and uses its own version of Ant. Java 1.4+ is required.
+ </p>
+</div>
+<a name="N10024"></a><a name="cvs"></a>
+<h4 class="faq">1.3.
+ The old xml-forrest CVS code repository seems to be stale. What happened?
+ </h4>
+<div align="right">
+<a href="#cvs-menu">^</a>
+</div>
+<div style="margin-left: 15px">
+<p>
+ Forrest switched from a CVS code repository to SVN (subversion)
+ code repository. The old CVS repository is not kept current.
+ </p>
+</div>
+<a name="N1002C"></a><a name="svn"></a>
+<h4 class="faq">1.4.
+ 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/build.html">Building Forrest</a> notes.
+ </p>
+<p>
+ The <a href="../docs/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="N1003F"></a><a name="single-document"></a>
+<h4 class="faq">1.5.
+ What is the best way to generate "standalone documents" using Forrest?
+ </h4>
+<div align="right">
+<a href="#single-document-menu">^</a>
+</div>
+<div style="margin-left: 15px">
+<p>
+ forrest site -Dproject.start-uri=myfile.pdf
+ </p>
+<p>
+ The <a href="../docs/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="N1004E"></a><a name="cygwin_mutex_error"></a>
+<h4 class="faq">1.6.
+ When running ./build.sh in cygwin, I get an error:
+ cygpath.exe: *** can't create title mutex, Win32 error 6.
+ </h4>
+<div align="right">
+<a href="#cygwin_mutex_error-menu">^</a>
+</div>
+<div style="margin-left: 15px">
+<p>
+ This
+ <a href="http://issues.cocoondev.org/secure/ViewIssue.jspa?key=FOR-10">appears
+ to be a bug in cygwin</a>. Please use the .bat script instead.
+ </p>
+</div>
+<a name="N10060"></a><a name="maxmemory"></a>
+<h4 class="faq">1.7.
+ How can I specify the amount of memory to be used by Java?
+ </h4>
+<div align="right">
+<a href="#maxmemory-menu">^</a>
+</div>
+<div style="margin-left: 15px">
+<p>
+ There are two ways to control this. If you get an OutOfMemoryError when Cocoon is generating pages,
+ see the first paragraph. If you get an OutOfMemoryError when outside of Cocoon (e.g., copying raw
+ files), see the second paragraph.
+ </p>
+<p>
+ The <span class="codefrag">maxmemory</span> property in the <span class="codefrag">forrest.properties</span> file controls how much
+ memory Cocoon uses. Like many other properties you can copy them from the default configuration at
+ <span class="codefrag">src/core/fresh-site/forrest.properties</span>
+
+</p>
+<p>
+ Set the <span class="codefrag">ANT_OPTS</span> environment variable before you run forrest. The exact value you set
+ it to is dependant on your JVM, but something like <span class="codefrag">ANT_OPTS=-Xmx500M</span> will probably work.
+ </p>
+</div>
+<a name="N1007D"></a><a name="content_faqs"></a>
+<h3 class="underlined_5">2. Content Creation</h3>
+<a name="N10081"></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/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/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="N1009B"></a><a name="PDF-output"></a>
+<h4 class="faq">2.2. 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/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/linking.html">site.xml</a> method for your site
+ structure and navigation, rather than the old book.xml method.
+ </p>
+</div>
+<a name="N100B5"></a><a name="pageBreaks"></a>
+<h4 class="faq">2.3. 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> or <em>pageBreakAfter</em> to the class
+ attribute of a section.</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="N100D2"></a><a name="clickable-email-address"></a>
+<h4 class="faq">2.4. 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">
+ src/core/context/skins/common/xslt/html/document2html.xsl</span>
+ and edit the "headers/authors" template.
+ </p>
+</div>
+<a name="N100DD"></a><a name="link_raw"></a>
+<h4 class="faq">2.5. How do I link to raw files such as config.txt and brochure.pdf?
+ </h4>
+<div align="right">
+<a href="#link_raw-menu">^</a>
+</div>
+<div style="margin-left: 15px">
+<p>
+ Place them in the <span class="codefrag">src/documentation/content</span> directory
+ and they will get copied into the output tree where you can link to
+ them. You can also have sub-directories there to reflect your xdocs
+ tree. See the samples documents when you 'forrest seed' a new
+ project for a demonstration of this ability.
+ </p>
+<p>
+ For example, if
+ <span class="codefrag">src/documentation/content/xdocs/tools/downloads.xml</span>
+ has a <span class="codefrag"><link href="tool.zip"></span> then put
+ <span class="codefrag">tool.zip</span> in the
+ <span class="codefrag">src/documentation/content/tools/</span> directory.
+ </p>
+<p>
+ See the explanation and demonstration of "linking" in your local
+ 'forrest seed' site.
+ </p>
+</div>
+<a name="N100FA"></a><a name="pdf_images"></a>
+<h4 class="faq">2.6. Images don't display in PDFs. How do I fix this?</h4>
+<div align="right">
+<a href="#pdf_images-menu">^</a>
+</div>
+<div style="margin-left: 15px">
+<p>
+ Forrest uses <a href="http://xml.apache.org/fop/">Apache FOP</a>
+ for rendering PDFs. FOP cannot handle all image types natively, and
+ requires third-party jars to be added. FOP natively handles BMP, GIF,
+ JPG, TIFF and EPS (with a few limitations). FOP can also handle SVG
+ (via Batik!and PNG (see below). For details, see
+ <a href="http://xml.apache.org/fop/graphics.html">FOP Graphics
+ formats</a>
+
+</p>
+<p>To get PNGs working in PDFs with Jimi:</p>
+<ol>
+
+<li>Download Jimi from
+ <a href="http://java.sun.com/products/jimi/">http://java.sun.com/products/jimi/</a>
+</li>
+
+<li>Unpack the Jimi distribution and copy JimiProClasses.zip to
+ <span class="codefrag">$FORREST/lib/optional/jimi-1.0.jar</span>.</li>
+
+</ol>
+<p>Alternatively you can use JAI (Java Advanced Imaging API at
+ http://java.sun.com/products/java-media/jai). For more
+ info, see
+ <a href="http://xml.apache.org/fop/graphics.html#packages">FOP Graphics
+ Packages</a>
+
+</p>
+<div class="frame 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="N10126"></a><a name="index.html"></a>
+<h4 class="faq">2.7.
+ The tab link in my site incorrectly assumes that 'index.html' is present in
+ the linked-to directory. How do I fix this?
+ </h4>
+<div align="right">
+<a href="#index.html-menu">^</a>
+</div>
+<div style="margin-left: 15px">
+<p>
+ In <span class="codefrag">tabs.xml</span>, use @href instead of @dir, and omit the
+ trailing '/'. Which file to serve is then a concern of the sitemap.
+ For example, if the "User Manual" tab should link to
+ <span class="codefrag">manual/Introduction.html</span> then
+ <span class="codefrag">tabs.xml</span> should contain:
+ </p>
+<pre class="code">
+ <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="N10142"></a><a name="label-entity"></a>
+<h4 class="faq">2.8.
+ 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.cocoondev.org/browse/FOR-244">Issue FOR-244</a>.
+ </p>
+</div>
+<a name="N1015B"></a><a name="encoding"></a>
+<h4 class="faq">2.9. 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="N101AD"></a><a name="technical"></a>
+<h3 class="underlined_5">3. Technical</h3>
+<a name="N101B1"></a><a name="proxy_config"></a>
+<h4 class="faq">3.1. I'm behind a proxy and it's preventing Plugins from
+ being downloaded, what should I do?</h4>
+<div align="right">
+<a href="#proxy_config-menu">^</a>
+</div>
+<div style="margin-left: 15px">
+<p>You can configure the proxy in the <span class="codefrag">forrest.properties</span>
+ file. Set the <span class="codefrag">proxy.host</span> and <span class="codefrag">proxy.port</span>
+ accordingly (the port will default to port 80).</p>
+</div>
+<a name="N101C2"></a><a name="CVS_revison_tags"></a>
+<h4 class="faq">3.2. How can I generate html-pages to show the
+ revision tag of cvs?</h4>
+<div align="right">
+<a href="#CVS_revison_tags-menu">^</a>
+</div>
+<div style="margin-left: 15px">
+<p>If you have:<span class="codefrag"><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/your-project.html"> Using Forrest</a> document.</p>
+<p>This technique could also be used for a modification date with
+ $Date: 2004/01/15 08:52:47 $</p>
+</div>
+<a name="N101D4"></a><a name="ignoring_javadocs"></a>
+<h4 class="faq">3.3.
+ How do I stop Forrest breaking on links to external files that may not
+ exist, like javadocs?
+ </h4>
+<div align="right">
+<a href="#ignoring_javadocs-menu">^</a>
+</div>
+<div style="margin-left: 15px">
+<p>
+ This can be done by overriding the <span class="codefrag">cli.xconf</span> config file,
+ and defining patterns for URLs to exclude.
+ </p>
+<p>
+ This means creating a directory <span class="codefrag">src/documentation/conf</span>
+ (or wherever <span class="codefrag">${forrest.conf-dir}</span> points) and copying
+ <span class="codefrag">$FORREST_HOME/context/WEB-INF/cli.xconf</span> to it. Then edit
+ cli.xconf, and add any exclude sections you require at the end. The
+ default cli.xconf ignores directory links and links containing
+ 'apidocs' or starting with 'api/':
+ </p>
+<pre class="code">
+ ....
+ <!-- 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="frame note">
+<div class="label">Note</div>
+<div class="content">
+ Wildcards may be used. These are a powerful feature of Cocoon's
+ <a href="../docs/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="N10208"></a><a name="claimed_patterns"></a>
+<h4 class="faq">3.4. Some of my files are not being processed because they use
+ common filenames.
+ </h4>
+<div align="right">
+<a href="#claimed_patterns-menu">^</a>
+</div>
+<div style="margin-left: 15px">
+<p>
+ Certain patterns are claimed by the default sitemaps for
+ special processing. These include:
+ <span class="codefrag">site, changes, todo, faq, images, my-images, skinconf,
+ community, howto</span>
+
+</p>
+<p>
+ Sometimes there are workarounds, e.g. faq.html or faq-interview.html
+ would fail, but interview-faq.html would be fine.
+ In future versions of Forrest we will attempt to deal with this issue
+ (<a href="http://issues.cocoondev.org/browse/FOR-217">FOR-217</a>).
+ </p>
+</div>
+<a name="N1021A"></a><a name="build_msg_a"></a>
+<h4 class="faq">3.5. What do the symbols and numbers mean when Forrest lists each
+ document that it has built?
+ </h4>
+<div align="right">
+<a href="#build_msg_a-menu">^</a>
+</div>
+<div style="margin-left: 15px">
+<pre class="code">
+* [56/0] 6.281s 23.0Kb index.html
+* [0/0] 0.0060s 4.0Kb images/project-logo.gif
+^ apidocs/index.html
+* [50/0] 1.582s 18.7Kb todo.html
+X [0] brokenlink.html BROKEN: reason
+* [50/0] 1.222s 20.2Kb dreams.html
+* [0/0] 0.535s 11.1Kb dreams.pdf
+...</pre>
+<p>
+ Column 1 is the page build status (*=okay X=brokenLink ^=pageSkipped).
+ Column 2 is the number of links that were gathered from that page.
+ Column 3 is the time taken.
+ Column 4 is the page size.
+ </p>
+</div>
+<a name="N10226"></a><a name="headless_operation"></a>
+<h4 class="faq">3.6.
+ 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="N10242"></a><a name="catalog"></a>
+<h4 class="faq">3.7.
+ 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/catalog.html">Using Catalog Entity Resolver for
+ local DTDs</a>.
+ </p>
+</div>
+<a name="N1024E"></a><a name="skin"></a>
+<h4 class="faq">3.8.
+ 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/skins.html">default skins</a> provided,
+ which are configurable and so should meet the needs of most projects.
+ The aim is to provide many capabilities so that extra skins are not
+ needed.
+ </p>
+<p>
+ See notes about
+ <a href="../docs/your-project.html#skins">configuration</a> of the skins.
+ Some projects may have special needs and can define their
+ <a href="../docs/your-project.html#new_skin">own skin</a>.
+ </p>
+</div>
+<a name="N10265"></a><a name="xsp"></a>
+<h4 class="faq">3.9. How do I enable XSP processing?</h4>
+<div align="right">
+<a href="#xsp-menu">^</a>
+</div>
+<div style="margin-left: 15px">
+<p>First consider whether your needs would be better met by Cocoon itself, rather than Forrest.
+ </p>
+<p>That said, there are valid reasons for wanting programmatically generated content, so here is how to enable
+ XSP:</p>
+<ol>
+
+<li>Download
+ <a href="http://cvs.apache.org/viewcvs.cgi/*checkout*/cocoon-2.1/lib/optional/jdtcore-2.1.0.jar?rev=1.1&content-type=application/java">jdtcore-2.1.0.jar</a>,
+ and copy it to the $FORREST_HOME/context/WEB-INF/lib directory
+ (or lib/core/ directory in the source
+ distribution).</li>
+
+<li>
+<p>Override sitemap.xmap in your local project (copy $FORREST_HOME/context/sitemap.xmap to
+ src/documentation/), and add the following generator definition in the map:generators section:</p>
+
+<pre class="code">
+ <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="N1029A"></a><a name="breadcrumbs"></a>
+<h4 class="faq">3.10. 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="N102AF"></a><a name="run_port"></a>
+<h4 class="faq">3.11. 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 src/core/context/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="N102C1"></a><a name="old_faqs"></a>
+<h3 class="underlined_5">4. Older version: 0.6</h3>
+<a name="N102C5"></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.cocoondev.org/browse/FOR-217">FOR-217</a>).
+ </p>
+</div>
+<a name="N102D7"></a><a name="general"></a>
+<h3 class="underlined_5">5. General</h3>
+<a name="N102DB"></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/linking.html">Menus and Linking</a>.
+ </p>
+</div>
+<a name="N102F6"></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">simplified-docbook</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/project-sitemap.html">project sitemap</a>
+ as explained in
+ <a href="../docs/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="{project: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 can also use a mixture of the two methods, some handled
+ automatically by Forrest and some directly using DocBook stylesheets.
+ You can also have a mixture of source files as "document-v*" DTD and DocBook.
+ </p>
+<p>
+ Ensure that the document type declaration in your xml instance is
+ well specified. Use a public identifier. The DTD will then be properly
+ resolved by Forrest. If you need to use different DTDs, then see
+ <a href="../docs/your-project.html#new_dtd">Using Forrest</a>
+ for configuration guidance.
+ </p>
+</div>
+<a name="N1031A"></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="N1032E"></a><a name="logs"></a>
+<h4 class="faq">5.4.
+ Where are the log files to find more infomation about errors?
+ </h4>
+<div align="right">
+<a href="#logs-menu">^</a>
+</div>
+<div style="margin-left: 15px">
+<p>
+ The logfiles are at <span class="codefrag">build/webapp/WEB-INF/logs/</span>
+
+</p>
+<p>
+ The log level can be raised with the <span class="codefrag">logkit.xconf</span>
+ configuration. If you are using Forrest in the interactive webapp
+ mode (which is generally easiest for debugging errors) then see the
+ <span class="codefrag">build/webapp/WEB-INF/logkit.xconf</span> file.
+ If you are generating a static site (with command-line 'forrest')
+ then copy <span class="codefrag">$FORREST_HOME/context/WEB-INF/logkit.xconf</span>
+ to your project at
+ <span class="codefrag">src/documentation/content/conf/logkit.xconf</span>
+ and modify it. See more information and efficiency tips with
+ <a href="http://wiki.apache.org/cocoon/ExploringTheLogs">Cocoon logging</a>.
+ </p>
+<p>
+ Doing <span class="codefrag">'forrest -v'</span> will provide verbose build messages
+ to the standard output.
+ </p>
+</div>
+<a name="N10352"></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="http://forrest.apache.org/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="N1035E"></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="http://issues.cocoondev.org/secure/BrowseProject.jspa?id=10000">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="http://issues.cocoondev.org/secure/BrowseProject.jspa?id=10000">issue tracker</a>
+ before diving in.
+ </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-2005 The Apache Software Foundation.</div>
+<!--+
+ |end bottomstrip
+ +-->
+</div>
+</body>
+</html>
Propchange: forrest/site/0.7/docs/faq.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/0.7/docs/faq.pdf
URL: http://svn.apache.org/viewcvs/forrest/site/0.7/docs/faq.pdf?view=auto&rev=160895
==============================================================================
Binary file - no diff available.
Propchange: forrest/site/0.7/docs/faq.pdf
------------------------------------------------------------------------------
svn:mime-type = application/pdf
Added: forrest/site/0.7/docs/faq.xml
URL: http://svn.apache.org/viewcvs/forrest/site/0.7/docs/faq.xml?view=auto&rev=160895
==============================================================================
--- forrest/site/0.7/docs/faq.xml (added)
+++ forrest/site/0.7/docs/faq.xml Mon Apr 11 07:58:59 2005
@@ -0,0 +1,586 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ Copyright 2002-2004 The Apache Software Foundation or its licensors,
+ as applicable.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+--><document><header><title>Frequently Asked Questions</title></header><body><section id="Questions"><title>Questions</title><section id="getting_started"><title>1. Getting Started and Building Forrest</title><section id="overview"><title>1.1.
+ Where can I read an overview about how to work with Forrest?
+ </title>
+ <p>
+ See the <link href="site:your-project">Using Forrest</link> guide.
+ </p>
+ </section><section id="requirements"><title>1.2.
+ What are the system requirements for Forrest?
+ </title>
+ <p>
+ Forrest includes everything necessary to build and run, except
+ of course for Java. In addition to all the Cocoon JARs, Forrest
+ includes and uses its own version of Ant. Java 1.4+ is required.
+ </p>
+ </section><section id="cvs"><title>1.3.
+ The old xml-forrest CVS code repository seems to be stale. What happened?
+ </title>
+ <p>
+ Forrest switched from a CVS code repository to SVN (subversion)
+ code repository. The old CVS repository is not kept current.
+ </p>
+ </section><section id="svn"><title>1.4.
+ How can I use SVN to keep up to date with the latest codebase?
+ </title>
+ <p>
+ Follow these <link href="site:build">Building Forrest</link> notes.
+ </p>
+ <p>
+ The <link href="site:your-project">Using Forrest</link> guide provides
+ further step-by-step assistance in getting started with Forrest for your project.
+ </p>
+ </section><section id="single-document"><title>1.5.
+ What is the best way to generate "standalone documents" using Forrest?
+ </title>
+ <p>
+ forrest site -Dproject.start-uri=myfile.pdf
+ </p>
+ <p>
+ The <link href="site:your-project">Using Forrest</link> guide provides
+ further step-by-step assistance in getting started with Forrest for your project.
+ </p>
+ </section><section id="cygwin_mutex_error"><title>1.6.
+ When running <code>./build.sh</code> in cygwin, I get an error:
+ <code>cygpath.exe: *** can't create title mutex, Win32 error 6</code>.
+ </title>
+ <p>
+ This
+ <link href="http://issues.cocoondev.org/secure/ViewIssue.jspa?key=FOR-10">appears
+ to be a bug in cygwin</link>. Please use the .bat script instead.
+ </p>
+ </section><section id="maxmemory"><title>1.7.
+ How can I specify the amount of memory to be used by Java?
+ </title>
+ <p>
+ There are two ways to control this. If you get an OutOfMemoryError when Cocoon is generating pages,
+ see the first paragraph. If you get an OutOfMemoryError when outside of Cocoon (e.g., copying raw
+ files), see the second paragraph.
+ </p>
+ <p>
+ The <code>maxmemory</code> property in the <code>forrest.properties</code> file controls how much
+ memory Cocoon uses. Like many other properties you can copy them from the default configuration at
+ <code>src/core/fresh-site/forrest.properties</code>
+ </p>
+ <p>
+ Set the <code>ANT_OPTS</code> environment variable before you run forrest. The exact value you set
+ it to is dependant on your JVM, but something like <code>ANT_OPTS=-Xmx500M</code> will probably work.
+ </p>
+ </section></section><section id="content_faqs"><title>2. Content Creation</title><section id="edit-content"><title>2.1. What tools can be used to edit the content?</title>
+ <p>If you are using the Apache Forrest xml
+ <link href="site:dtd-docs">document format</link> or DocBook
+ or other xml document types, then you can use any text editor
+ or even a dedicated xml editor. You must ensure valid xml. See our
+ <link href="site:catalog">configuration notes</link>
+ for various editors.
+ </p>
+ <p>There are content management systems like
+ <link href="ext:lenya">Apache Lenya</link>.
+ </p>
+ <p>Remember that Forrest can also use other source formats, such as
+ OpenOffice.org docs or JSPWiki. Use the appropriate editor for those
+ document types and ensure that the document stucture is consistent.
+ Forrest can also use "html" as the source format, in which case you
+ can use text editors or "html editors" such as the one provided
+ with the Mozilla web browser.
+ </p>
+ </section><section id="PDF-output"><title>2.2. How can I generate one pdf-file out of
+ the whole site or selected pages of the site?</title>
+ <p>Add the following entries to your site.xml file:</p>
+ <source xml:space="preserve">
+ <about tab="home" label="About" href="">
+ 	 ...
+ <all_site label="Full HTML" href="wholesite.html"/>
+ <all_sitePDF label="Full PDF" href="wholesite.pdf"/>
+ ...
+ </about></source>
+ <p>
+ In this case the menu labeled "About" will have 2 new items:
+ "Full PDF" and "Full HTML". (See also
+ <link href="site:howto/pdf-tab">How to create a PDF document for each tab</link>.)
+ </p>
+ <p>
+ This assumes that you use the
+ <link href="site:linking">site.xml</link> method for your site
+ structure and navigation, rather than the old book.xml method.
+ </p>
+ </section><section id="pageBreaks"><title>2.3. How do I insert page breaks into documents?</title>
+ <p>Page breaks do not make a great deal of sense in HTML documents
+ intended for display on a screen. However, PDF documents are intended
+ for printing and therefore page breaks can be important.</p>
+ <p>To insert a page break in a PDF document simply add
+ <em>pageBreakBefore</em> or <em>pageBreakAfter</em> to the class
+ attribute of a section.</p>
+ <p>If you want these classes to be processed in your HTML documents
+ as well you should add the following to the <code>extra-css</code>
+ element in your projects <code>skinconf.xml</code></p>
+ <source xml:space="preserve">
+ .pageBreakBefore {
+ margin-bottom: 0;
+ page-break-before: always;
+ }
+
+ .pageBreakAfter {
+ margin-bottom: 0;
+ page-break-after: always;
+ }
+ </source>
+ </section><section id="clickable-email-address"><title>2.4. How can I generate html-pages to show a
+ 'clickable' email-address (of the author-element)?</title>
+ <p>You would override <code>
+ src/core/context/skins/common/xslt/html/document2html.xsl</code>
+ and edit the "headers/authors" template.
+ </p>
+ </section><section id="link_raw"><title>2.5. How do I link to raw files such as config.txt and brochure.pdf?
+ </title>
+ <p>
+ Place them in the <code>src/documentation/content</code> directory
+ and they will get copied into the output tree where you can link to
+ them. You can also have sub-directories there to reflect your xdocs
+ tree. See the samples documents when you 'forrest seed' a new
+ project for a demonstration of this ability.
+ </p>
+ <p>
+ For example, if
+ <code>src/documentation/content/xdocs/tools/downloads.xml</code>
+ has a <code><link href="tool.zip"></code> then put
+ <code>tool.zip</code> in the
+ <code>src/documentation/content/tools/</code> directory.
+ </p>
+ <p>
+ See the explanation and demonstration of "linking" in your local
+ 'forrest seed' site.
+ </p>
+ </section><section id="pdf_images"><title>2.6. Images don't display in PDFs. How do I fix this?</title>
+ <p>
+	 Forrest uses <link href="http://xml.apache.org/fop/">Apache FOP</link>
+ for rendering PDFs. FOP cannot handle all image types natively, and
+ requires third-party jars to be added. FOP natively handles BMP, GIF,
+	 JPG, TIFF and EPS (with a few limitations). FOP can also handle SVG
+	 (via Batik!and PNG (see below). For details, see
+	 <link href="http://xml.apache.org/fop/graphics.html">FOP Graphics
+ formats</link>
+ </p>
+ <p>To get PNGs working in PDFs with Jimi:</p>
+ <ol>
+ <li>Download Jimi from
+ <link href="http://java.sun.com/products/jimi/">http://java.sun.com/products/jimi/</link></li>
+ <li>Unpack the Jimi distribution and copy JimiProClasses.zip to
+ <code>$FORREST/lib/optional/jimi-1.0.jar</code>.</li>
+ </ol>
+ <p>Alternatively you can use JAI (Java Advanced Imaging API at
+	 http://java.sun.com/products/java-media/jai). For more
+ info, see
+ <link href="http://xml.apache.org/fop/graphics.html#packages">FOP Graphics
+ Packages</link>
+ </p>
+ <note>Due to Sun's licensing, we cannot redistribute Jimi or JAI with
+ Forrest.</note>
+ </section><section id="index.html"><title>2.7.
+ The tab link in my site incorrectly assumes that 'index.html' is present in
+ the linked-to directory. How do I fix this?
+ </title>
+ <p>
+ In <code>tabs.xml</code>, use @href instead of @dir, and omit the
+ trailing '/'. Which file to serve is then a concern of the sitemap.
+ For example, if the "User Manual" tab should link to
+ <code>manual/Introduction.html</code> then
+ <code>tabs.xml</code> should contain:
+ </p>
+ <source xml:space="preserve">
+ <tab label="User Manual" href="manual"/></source>
+ <p>
+ and add this rule to the sitemap:
+ </p>
+ <source xml:space="preserve">
+ <map:match pattern="manual">
+ <map:redirect-to uri="manual/Introduction.html"/>
+ </map:match></source>
+ </section><section id="label-entity"><title>2.8.
+ How to use special characters in the labels of the site.xml file?
+ </title>
+ <p>
+ Use the numeric values for character entities.
+ For example, rather than using
+ <code>&ouml;</code> use
+ <code>&#246;</code>
+ </p>
+ <p>
+ See the
+ <link href="http://www.w3.org/TR/xhtml-modularization/dtd_module_defs.html#a_xhtml_character_entities">XHTML Character Entities</link>
+ and see more discussion at
+ <link href="http://issues.cocoondev.org/browse/FOR-244">Issue FOR-244</link>.
+ </p>
+ </section><section id="encoding"><title>2.9. Does Forrest handle accents for non-English languages?</title>
+ <p>Yes, Forrest can process text in any language, so you can include:</p>
+ <ul>
+ <li>accents: á é í ó ú</li>
+ <li>diereses: ä ë ï ö ü</li>
+ <li>tildes: ã ñ ĩ õ ũ</li>
+ </ul>
+ <p>This is because sources for Forrest docs are xml documents, which can include any of these,
+ provided the encoding declared by the xml doc matches the actual encoding used in the file.
+ For example if you declare the default encoding:</p>
+ <source xml:space="preserve"><?xml version="1.0" encoding="UTF-8"?></source>
+ <p>but the file content is actually using ISO-8859-1 then you will
+ receive validation errors, especially if
+ you include some non-ASCII characters.</p>
+ <p>
+ This situation is commonly encountered when you edit the templates
+ created by <code>forrest seed</code> with your favorite
+ (probably localized) editor without paying attention to the encoding,
+ or when you create a new file
+ and simply copy the headers from another file.
+ </p>
+ <p>Although UTF-8 is an encoding well-suited for most languages,
+ it is not usually the default in popular editors or systems.
+ In UNIX-like systems, most popular editors can handle different encodings to
+ write the file in disk. With some editors the encoding of the file is preserved, while with others the default
+ is used regardless of the original encoding. In most cases the encoding used to write files
+ can be controlled by setting the environment variable <code>LANG</code>
+ to an appropriate value, for instance:
+ </p>
+ <source xml:space="preserve">[localhost]$ export LANG=en_US.UTF-8</source>
+ <p>Of course the <em>appropriate</em> way to set the encoding depends on the editor/OS,
+ but ultimately relys on the user preferences. So you can use the encoding you prefer, as long as
+ the <code>encoding</code> attribute of the xml declaration matches the actual encoding of the file.
+ This means
+ that if you are not willing to abandon ISO-8859-1 you can always use the following declaration instead:</p>
+ <source xml:space="preserve"><?xml version="1.0" encoding="ISO-8859-1"?></source>
+ <p>Another option is to use "character entities" such as
+ <code>&ouml;</code> (ö) or the numeric form
+ <code>&#246;</code> (ö).
+ </p>
+ <p>Another related issue is that your webserver needs to send http
+ headers with the matching charset definitions to the html page.
+ </p>
+ <p>Here are some references which explain further:
+ <link href="http://orixo.com/events/gt2004/bios.html#torsten">GT2004 presentation by Torsten Schlabach</link> and
+ <link href="http://www.alanwood.net/unicode/">Alan Wood's Unicode resources</link>.
+ </p>
+ </section></section><section id="technical"><title>3. Technical</title><section id="proxy_config"><title>3.1. I'm behind a proxy and it's preventing Plugins from
+ being downloaded, what should I do?</title>
+ <p>You can configure the proxy in the <code>forrest.properties</code>
+ file. Set the <code>proxy.host</code> and <code>proxy.port</code>
+ accordingly (the port will default to port 80).</p>
+ </section><section id="CVS_revison_tags"><title>3.2. How can I generate html-pages to show the
+ revision tag of cvs?</title>
+ <p>If you have:<code><version>$Revision: 1.30
+ $</version></code>The '1.30' will be extracted and
+ displayed at the bottom of the page as "version 1.30". See for
+ example the bottom of the
+ <link href="site:your-project"> Using Forrest</link> document.</p>
+ <p>This technique could also be used for a modification date with
+ $Date: 2004/01/15 08:52:47 $</p>
+ </section><section id="ignoring_javadocs"><title>3.3.
+ How do I stop Forrest breaking on links to external files that may not
+ exist, like javadocs?
+ </title>
+ <p>
+ This can be done by overriding the <code>cli.xconf</code> config file,
+ and defining patterns for URLs to exclude.
+ </p>
+ <p>
+ This means creating a directory <code>src/documentation/conf</code>
+ (or wherever <code>${forrest.conf-dir}</code> points) and copying
+ <code>$FORREST_HOME/context/WEB-INF/cli.xconf</code> to it. Then edit
+ cli.xconf, and add any exclude sections you require at the end. The
+ default cli.xconf ignores directory links and links containing
+ 'apidocs' or starting with 'api/':
+ </p>
+ <source xml:space="preserve">
+ ....
+ <!-- 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></source>
+ <p>This is just an example, and you should modify it appropriately for
+ your site.</p>
+ <note>
+ Wildcards may be used. These are a powerful feature of Cocoon's
+ <link href="site:sitemap-ref">sitemap</link>.
+ For example, <strong>foo/*</strong> would match
+ <code>foo/bar</code>, but not <code>foo/bar/baz</code>
+ — use <strong>foo/**</strong> to match that.
+ </note>
+ </section><section id="claimed_patterns"><title>3.4. Some of my files are not being processed because they use
+ common filenames.
+ </title>
+ <p>
+ Certain patterns are claimed by the default sitemaps for
+ special processing. These include:
+ <code>site, changes, todo, faq, images, my-images, skinconf,
+ community, howto</code>
+ </p>
+ <p>
+ Sometimes there are workarounds, e.g. faq.html or faq-interview.html
+ would fail, but interview-faq.html would be fine.
+ In future versions of Forrest we will attempt to deal with this issue
+ (<link href="http://issues.cocoondev.org/browse/FOR-217">FOR-217</link>).
+ </p>
+ </section><section id="build_msg_a"><title>3.5. What do the symbols and numbers mean when Forrest lists each
+ document that it has built?
+ </title>
+ <source xml:space="preserve">
+* [56/0] 6.281s 23.0Kb index.html
+* [0/0] 0.0060s 4.0Kb images/project-logo.gif
+^ apidocs/index.html
+* [50/0] 1.582s 18.7Kb todo.html
+X [0] brokenlink.html BROKEN: reason
+* [50/0] 1.222s 20.2Kb dreams.html
+* [0/0] 0.535s 11.1Kb dreams.pdf
+...</source>
+ <p>
+ Column 1 is the page build status (*=okay X=brokenLink ^=pageSkipped).
+ Column 2 is the number of links that were gathered from that page.
+ Column 3 is the time taken.
+ Column 4 is the page size.
+ </p>
+ </section><section id="headless_operation"><title>3.6.
+ When generating PNG images from SVG, I get an error: Can't connect to X11 window server using ':0.0' as the value of the DISPLAY variable.
+ </title>
+ <p>
+ If you are using JDK 1.4.0 or newer, you can enable <em>headless</em>
+ operation by running Forrest with the <code>forrest.jvmarg</code>
+ parameter set to <code>-Djava.awt.headless=true</code>, like this:
+ </p>
+ <source xml:space="preserve">forrest -Dforrest.jvmargs=-Djava.awt.headless=true site</source>
+ <p>
+ See also
+ <link href="http://cocoon.apache.org/2.1/faq/faq-configure-environment.html">Cocoon FAQ</link>.
+ </p>
+ </section><section id="catalog"><title>3.7.
+ How do i configure my favourite XML editor or parser to find the
+ local Forrest DTDs?
+ </title>
+ <p>
+ Notes are provided for various tools at
+ <link href="site:catalog">Using Catalog Entity Resolver for
+ local DTDs</link>.
+ </p>
+ </section><section id="skin"><title>3.8.
+ How to make the site look better and change its skin?
+ </title>
+ <p>
+ There are <link href="site:skins">default skins</link> provided,
+ which are configurable and so should meet the needs of most projects.
+ The aim is to provide many capabilities so that extra skins are not
+ needed.
+ </p>
+ <p>
+ See notes about
+ <link href="site:your-project/skins">configuration</link> of the skins.
+ Some projects may have special needs and can define their
+ <link href="site:your-project/new-skin">own skin</link>.
+ </p>
+ </section><section id="xsp"><title>3.9. How do I enable <acronym title="eXtensible Server Pages">XSP</acronym> processing?</title>
+ <p>First consider whether your needs would be better met by Cocoon itself, rather than Forrest.
+ </p>
+ <p>That said, there are valid reasons for wanting programmatically generated content, so here is how to enable
+ XSP:</p>
+ <ol>
+ <li>Download
+ <link href="http://cvs.apache.org/viewcvs.cgi/*checkout*/cocoon-2.1/lib/optional/jdtcore-2.1.0.jar?rev=1.1&content-type=application/java">jdtcore-2.1.0.jar</link>,
+ and copy it to the $FORREST_HOME/context/WEB-INF/lib directory
+ (or lib/core/ directory in the source
+ distribution).</li>
+ <li><p>Override sitemap.xmap in your local project (copy $FORREST_HOME/context/sitemap.xmap to
+ src/documentation/), and add the following generator definition in the map:generators section:</p>
+ <source xml:space="preserve">
+ <map:generator name="serverpages"
+ pool-grow="2" pool-max="32" pool-min="4"
+ src="org.apache.cocoon.generation.ServerPagesGenerator"/></source>
+ </li>
+ <li><p>Decide how you want to use XSP. For single files, you could just define a *.xml matcher:</p>
+ <source xml:space="preserve">
+<map:match pattern="dynamic.xml">
+ <map:generate src="content/xdocs/dynamic.xsp" type="serverpages"/>
+ ...
+ <map:serialize type="xml"/>
+</map:match></source>
+ <p>You may instead wish to override forrest.xmap to define a general mapping for XSPs.</p>
+ </li>
+ </ol>
+ <p>See also the
+ <link href="http://wiki.apache.org/cocoon/AddingXSPToForrest">AddingXSPToForrest</link> Wiki page.</p>
+ </section><section id="breadcrumbs"><title>3.10. How do breadcrumbs work? Why don't they work locally?</title>
+ <p>Breadcrumbs begin with up to three URLs specified in
+ <code>skinconf.xml</code>. Here is what the Forrest site uses:</p>
+ <source xml:space="preserve">
+ <trail>
+ <link1 name="apache" href="http://www.apache.org/"/>
+ <link2 name="xml.apache" href="http://xml.apache.org/"/>
+ <link3 name="" href=""/>
+ </trail></source>
+ <p>If any links are blank, they are not used. After these first links,
+ JavaScript looks at the URL for the current page and
+ makes a link for each directory after the domain. If you are viewing
+ the site locally, there is no domain and so
+ there will be no extra breadcrumbs, only the ones that are specified
+ in <code>skinconf.xml</code>.
+ </p>
+ </section><section id="run_port"><title>3.11. How do I make <code>forrest run</code> listen on a different port?</title>
+ <p><code>forrest run -Dforrest.jvmargs="-Djetty.port=80"</code></p>
+ <p>Or copy Forrest's src/core/context/jettyconf.xml file to your project's src/documentation
+ directory and set the port number in that file. Then do <code>forrest run</code>
+ </p>
+ </section></section><section id="old_faqs"><title>4. Older version: 0.6</title><section id="old_claimed_patterns"><title>4.1. Some of my files are not being processed because they use
+ common filenames.
+ </title>
+ <p>
+ Certain patterns are claimed by the default sitemaps for
+ special processing. These include:
+ <code>site, changes, todo, faq, images, my-images, skinconf,
+ community, howto</code>
+ </p>
+ <p>
+ Sometimes there are workarounds, e.g. faq.html or faq-interview.html
+ would fail, but interview-faq.html would be fine.
+ In future versions of Forrest we will attempt to deal with this issue
+ (<link href="http://issues.cocoondev.org/browse/FOR-217">FOR-217</link>).
+ </p>
+ </section></section><section id="general"><title>5. General</title><section id="generating_menus"><title>5.1. What is the relationship between <code>site.xml</code> and
+ <code>book.xml</code>?
+ </title>
+ <p>
+ One <code>site.xml</code> file in your project root can replace all the book.xml files
+ (one per directory) in your site. Internally, Forrest uses <code>site.xml</code> to
+ dynamically generate book.xml files. However, Forrest first checks
+ for the existence of a book.xml file, so backwards-compatibility is
+ preserved. If a directory has a book.xml file, the book.xml will be
+ used to generate the menu. This supplement is useful in situations
+ where <code>site.xml</code>-generated menus aren't appropriate.
+ See <link href="site:linking">Menus and Linking</link>.
+ </p>
+ </section><section id="docbook"><title>5.2.
+ How do I use DocBook as the xml documentation format?
+ </title>
+ <p>
+ There are two ways. Forrest has a <code>simplified-docbook</code> plugin
+ which can transform the DocBook format into the
+ Forrest "xdocs" format on-the-fly and then render that as normal
+ Forrest documents.
+ Be aware that the stylesheet that does this transformation is
+ deliberately very limited and does not attempt to deal with all
+ DocBook elements.
+ </p>
+ <p>
+ The other way is to use the full DocBook stylesheets directly. The DocBook
+ DTDs are shipped with Forrest and automatically handled. However, you
+ will need to have the DocBook stylesheets on your system (they are
+ too massive to ship with Forrest) and configure Forrest accordingly.
+ You will need to create a
+ <link href="site:project-sitemap">project sitemap</link>
+ as explained in
+ <link href="site:your-project">Using Forrest</link>
+ and add matches to handle your DocBook documents.
+ Here is an example. Note that you need to change it to suit your
+ situation. The match must be very specific so that only the
+ DocBook documents are matched. The rest of the documents will be
+ handled by Forrest core. Powerful regex capabilities are available.
+ </p>
+ <source xml:space="preserve"><?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="{project: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>
+ </source>
+ <p>
+ You can also use a mixture of the two methods, some handled
+ automatically by Forrest and some directly using DocBook stylesheets.
+ You can also have a mixture of source files as "document-v*" DTD and DocBook.
+ </p>
+ <p>
+ Ensure that the document type declaration in your xml instance is
+ well specified. Use a public identifier. The DTD will then be properly
+ resolved by Forrest. If you need to use different DTDs, then see
+ <link href="site:your-project/new_dtd">Using Forrest</link>
+ for configuration guidance.
+ </p>
+ </section><section id="version"><title>5.3.
+ How to report which version of Forrest is being used and the
+ properties that are set?
+ </title>
+ <p>
+ Do <code>'forrest -projecthelp'</code> or <code>'./build.sh'</code>
+ to find the version number.
+ </p>
+ <p>
+ To list the properties, add "forrest.echo=true" to your
+ forrest.properties file and watch the build messages.
+ Doing <code>'forrest -v'</code> will provide verbose build messages.
+ </p>
+ </section><section id="logs"><title>5.4.
+ Where are the log files to find more infomation about errors?
+ </title>
+ <p>
+ The logfiles are at <code>build/webapp/WEB-INF/logs/</code>
+ </p>
+ <p>
+ The log level can be raised with the <code>logkit.xconf</code>
+ configuration. If you are using Forrest in the interactive webapp
+ mode (which is generally easiest for debugging errors) then see the
+ <code>build/webapp/WEB-INF/logkit.xconf</code> file.
+ If you are generating a static site (with command-line 'forrest')
+ then copy <code>$FORREST_HOME/context/WEB-INF/logkit.xconf</code>
+ to your project at
+ <code>src/documentation/content/conf/logkit.xconf</code>
+ and modify it. See more information and efficiency tips with
+ <link href="http://wiki.apache.org/cocoon/ExploringTheLogs">Cocoon logging</link>.
+ </p>
+ <p>
+ Doing <code>'forrest -v'</code> will provide verbose build messages
+ to the standard output.
+ </p>
+ </section><section id="how_can_I_help"><title>5.5.
+ How to help?
+ </title>
+ <p>
+ Join one of the Forrest project
+ <link href="ext:mail-lists">mailing lists</link>
+ 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>
+ </section><section id="patch"><title>5.6.
+ How to contribute a patch?
+ </title>
+ <p>Please send all contributions via our
+ <link href="site:bugs">issue tracker</link>.
+ Here are notes about
+ <link href="site:contrib/patch">making patches</link>.
+ </p>
+ <p>More info about contributing can be found at the
+ <link href="site:contrib">Contributing to Forrest</link> page.
+ It is always a good idea to check the Forrest
+ <link href="site:bugs">issue tracker</link>
+ before diving in.
+ </p>
+ </section></section></section></body></document>
\ No newline at end of file
Propchange: forrest/site/0.7/docs/faq.xml
------------------------------------------------------------------------------
svn:eol-style = native