forrest-site-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: r1068306 [9/22] - in /forrest/site: docs_0_100/ docs_0_100/howto/ docs_0_100/howto/cvs-ssh/ docs_0_100/howto/multi/ docs_0_100/images/ pluginDocs/plugins_0_100/ trash/ trash/docs_0_50/ trash/docs_0_70/
Date Tue, 08 Feb 2011 09:44:48 GMT
Added: forrest/site/docs_0_100/faq.xml
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_100/faq.xml?rev=1068306&view=auto
==============================================================================
--- forrest/site/docs_0_100/faq.xml (added)
+++ forrest/site/docs_0_100/faq.xml Tue Feb  8 09:44:46 2011
@@ -0,0 +1,1332 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You 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="getting_started"><title>1. Getting Started and Building Forrest</title><section id="faq"><title>1.1.  How to use these FAQs? </title>
+        <p>
+          There is no particular order to these FAQs. Use your browser's "Find
+          in this page" facility to search for keywords.
+        </p>
+      </section><section id="overview"><title>1.2.  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="docs"><title>1.3. Where is all of the documentation?</title>
+        <p>
+          You have a local copy of the main documentation with your version of
+          Forrest. Do 'cd site-author; forrest run' and visit
+          <code>http://localhost:8888/</code> in your browser. The most recent documentation
+          is in SVN trunk which creates the forrest.apache.org website.
+        </p>
+        <p>
+          Each <link href="site:plugins/index">plugin</link> 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 <link href="site:zone">testing zone</link>.
+        </p>
+      </section><section id="requirements"><title>1.4.  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 Apache Ant.
+        </p>
+        <p>
+          Java 1.5 (or newer) is required. If you are only going to use Forrest
+          as-is then you need only the Java Runtime Environment (JRE). If you
+          intend to enhance and rebuild Forrest (or use the Forrest sources with
+          Subversion or use a source snapshot) then you need the full JDK.
+        </p>
+      </section><section id="cvs"><title>1.5.  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 closed and not kept current.
+        </p>
+      </section><section id="svn"><title>1.6.  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="older-plugins"><title>1.7.  How to use older versions of specific plugins? </title>
+        <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
+          <link href="site:plugins/index">documentation</link>.
+        </p>
+        <p>
+          In the forrest.properties file, specify the version of the plugin that
+          you require, e.g.
+        </p>
+        <source xml:space="preserve">project.required.plugins=org.apache.forrest.plugin.input.PhotoGallery-0.1,...</source>
+        <p>
+          Users of Forrest-0.7 will need to do this for the projectInfo plugin
+          if you get the following error ...
+        </p>
+        <source xml:space="preserve">Could not find component for role:
+ [org.apache.cocoon.components.modules.input.InputModule/lm]
+ (Key='org.apache.cocoon.components.modules.input.InputModule/</source>
+        <p>
+          ... then sorry, we mistakenly added new "locationmap" functionality
+          (due in version 0.8). So do this ...
+        </p>
+        <source xml:space="preserve">project.required.plugins=org.apache.forrest.plugin.input.projectInfo-0.1,...</source>
+      </section><section id="single-document"><title>1.8.  What is the best way to generate "standalone documents" using Forrest? </title>
+        <p>
+          There is a trick that can cut down your turnaround time with building.
+          In forrest.properties ...
+        </p>
+        <source xml:space="preserve">
+# The URL to start crawling from
+#project.start-uri=linkmap.html
+        </source>
+        <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>
+        <source xml:space="preserve">
+forrest -Dproject.start-uri=live-sites.html
+        </source>
+        <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 <link href="#cli-xconf">Cocoon
+          cli.xconf</link> 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
+          <code>'wget http://localhost:8888/index.pdf'</code>
+        </p>
+      </section><section id="cygwin_mutex_error"><title>1.9.  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.apache.org/jira/browse/FOR-10">appears
+          to be a bug in cygwin</link>. Please use the .bat script instead.
+        </p>
+      </section><section id="oldjing"><title>1.10. On Java 6 fails validate-sitemap task. Missing the RELAX NG datatype library.</title>
+        <source xml:space="preserve">
+validate-sitemap:
+apache-forrest-0.8/main/webapp/resources/schema/relaxng/sitemap-v06.rng:72:31:
+error: datatype library "http://www.w3.org/2001/XMLSchema-datatypes" not recognized
+</source>
+        <p>
+          The version of Jing needs to be updated. 
+        </p>
+        <p>
+          This is fixed in Forrest-0.9-dev version.
+          See <link href="http://issues.apache.org/jira/browse/FOR-984">FOR-984</link>.
+        </p>
+        <p>
+          One workaround is to update your copy of the
+          <link href="http://code.google.com/p/jing-trang/">Jing</link> jar at
+          <code>$FORREST_HOME/lib/core/</code>
+        </p>
+        <p>
+          Another workaround is to edit the forrest.properties configuration file
+          to expose the "forrest.validate.sitemap" property and set it to "false".
+          Might need to do the same for the "forrest.validate.stylesheets" property.
+        </p>
+      </section><section id="winjava"><title>1.11. Windows gets confused about which Java version to use.</title>
+        <p>
+          Cough, yes!. See this
+          <link href="http://mail-archives.apache.org/mod_mbox/forrest-user/200704.mbox/%3c462CA40F.5020400@rblasch.org%3e">explanation</link>
+          on the Forrest mail lists.
+        </p>
+      </section><section id="maxmemory"><title>1.12.  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>main/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 id="debug"><title>1.13.  How can I start forrest in Java debug mode? </title>
+        <p>
+          The <code>forrest.jvmargs</code> property in the
+          <code>forrest.properties</code> file can be used to start forrest in
+          debug mode on a specific port. <code>forrest.jvmargs=-Xdebug
+          -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n</code>
+        </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="site-xml"><title>2.2. 
+        How to use the <code>site.xml</code> configuration file for menus and linking.
+      </title>
+        <p>
+          The <code>site.xml</code> 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 <link href="site:linking">Menus and Linking</link>.
+          Here is a precis:
+        </p>
+        <p>
+          The labels can be whatever text you want.
+        </p>
+        <source xml:space="preserve">
+&lt;faq label="FAQs" href="faq.html"&gt;
+  &lt;tech label="Technical" href="faq-tech.html"&gt;
+    &lt;docbook href="#docbook"/&gt;
+    &lt;ignoring_javadocs href="#ignoring_javadocs"/&gt;
+  &lt;/tech&gt;
+  &lt;user label="User" href="faq-user.html"&gt;
+&lt;/faq&gt;
+        </source>
+        <p>
+          That will create a menu like this with three links:
+        </p>
+        <source xml:space="preserve">FAQs
+   Technical
+   User</source>
+        <p>
+          These documents can be linked to from other documents, like this:
+        </p>
+        <source xml:space="preserve">
+&lt;a href="site:faq/tech"&gt; link to the top of the Tech FAQs
+&lt;a href="site:faq/tech/docbook"&gt; link to the DocBook FAQ in the Tech FAQs
+        </source>
+        <p>
+          If that "docbook" entry was a unique name in your site.xml then you
+          can shorten that latter link:
+        </p>
+        <source xml:space="preserve">
+&lt;a href="site:docbook"&gt; link to the DocBook FAQ in the Tech FAQs
+        </source>
+      </section><section id="examples"><title>2.3. 
+        Where are examples of documents and site.xml and tabs.xml files?
+      </title>
+        <p>
+          There are examples in the 'forrest seed site' and also the Forrest
+          website documents are included with the distribution (<code>cd
+          forrest/site-author; forrest run</code>).
+        </p>
+      </section><section id="crawler"><title>2.4. 
+        Help, one of my documents is not being rendered.
+      </title>
+        <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>
+      </section><section id="PDF-output"><title>2.5. 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.
+          Note that the href must be exactly "wholesite" or "site" which triggers
+          a special match in the sitemap to aggregate all documents.
+        </p>
+        <source xml:space="preserve">
+
+  &lt;about tab="home" label="About" href=""&gt;
+ 	  ...
+    &lt;all_site label="Full HTML" href="wholesite.html"/&gt;    
+    &lt;all_sitePDF label="Full PDF" href="wholesite.pdf"/&gt;  
+     ...
+  &lt;/about&gt;
+        </source>
+        <p>
+          In this case the menu labeled "About" will have 2 new items: "Full
+          PDF" and "Full HTML".
+        </p>
+        <p>
+          See also <link href="site: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>
+        <warning>
+          There are many issues with the "wholesite" aggregation. Search the
+          issue tracker and mail lists.
+        </warning>
+      </section><section id="pageBreaks"><title>2.6. 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> 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 <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.7. How can I generate html-pages to show a 'clickable' email-address (of the
+        author-element)?</title>
+        <p>
+          You would override <code>
+          $FORREST_HOME/main/webapp/skins/common/xslt/html/document-to-html.xsl</code>
+          and edit the "headers/authors" template.
+        </p>
+      </section><section id="link_raw"><title>2.8. How do I link to raw files such as config.txt and brochure.pdf? </title>
+        <p>
+          Handling of raw files was significantly changed in Forrest 0.7. See
+          <link href="site:upgrading_07/raw">Upgrading to Apache Forrest
+          0.7</link> for all the details.
+        </p>
+      </section><section id="pdf_images"><title>2.9. 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
+          <code>http://java.sun.com/products/java-media/jai</code>). 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="tab-index"><title>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? </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">
+
+  &lt;tab label="User Manual" href="manual"/&gt;
+        </source>
+        <p>
+          and add this rule to the sitemap:
+        </p>
+        <source xml:space="preserve">
+
+  &lt;map:match pattern="manual"&gt;
+    &lt;map:redirect-to uri="manual/Introduction.html"/&gt;
+  &lt;/map:match&gt;
+        </source>
+      </section><section id="tab-site"><title>2.11. I need help with the interaction between tabs.xml and site.xml </title>
+        <p>
+          See the <link href="site:linking/tab-site">tips</link>.
+        </p>
+      </section><section id="defaultFileName"><title>2.12.  How can I change the default file name that Forrest will look for when I request a
+        URL like <code>http://myserver</code> or <code>http://myserver/mydir/</code> ? </title>
+        <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 '<link href="#cli-xconf">cli.xconf</link>' file for your project </li>
+          <li> Edit that file to replace 'index.html' in
+            &lt;default-filename&gt;index.html&lt;/default-filename&gt;
+            with 'overview.html'. </li>
+          <li> Edit your project's <link href="site:project-sitemap">sitemap.xmap</link> file. </li>
+          <li> Add the following code just before the end of the pipelines-element:<source xml:space="preserve">
+
+  &lt;map:pipeline&gt;
+    &lt;map:match type="regexp" pattern="^.+/$"&gt;
+       &lt;map:redirect-to uri="overview.html"/&gt;
+    &lt;/map:match&gt;
+  &lt;/map:pipeline&gt;
+          
+            </source></li>
+        </ol>
+      </section><section id="defaultStartPage"><title>2.13.  How can I use a start-up-page other than index.html? </title>
+        <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 <link href="site:project-sitemap">sitemap.xmap</link> file.</li>
+          <li>Add the following code just before the end of the pipelines-element:<source xml:space="preserve">
+
+  &lt;map:pipeline&gt;
+    &lt;map:match pattern=""&gt;
+      &lt;map:redirect-to uri="start.html" /&gt;
+    &lt;/map:match&gt;
+  &lt;/map:pipeline&gt;
+          
+            </source></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>
+      </section><section id="output-filename-extension"><title>2.14. How to use a different filename extension for output, e.g. *.php? </title>
+        <p>
+          Use the power of the Cocoon sitemaps. There is default handling for *.php (see main/webapp/sitemap.xmap) to map the 'php' extension to an internal request for "html". See more about <link href="#php">PHP</link> below.
+        </p>
+        <p>
+          Use the same internal re-direction technique for your special needs, e.g. copy that php match to your project sitemap and use ".htm" instead.
+        </p>
+      </section><section id="php"><title>2.15.  How to generate pages ready for serving via PHP? </title>
+        <p>
+          Use the *.php filename extension (see <link href="#output-filename-extension">above</link>)
+          for the output html links in site.xml navigation. Add your php processing instructions to the source documents.
+        </p>
+        <p>
+          However, beware <link href="http://issues.apache.org/jira/browse/FOR-999">FOR-999</link>
+          "processing-instruction nodes in source are not always passed through to html output"
+          whereby only PIs in certain body elements are handled.
+        </p>
+      </section><section id="label-entity"><title>2.16.  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>
+&amp;ouml;
+          </code> use <code>
+&amp;#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.apache.org/jira/browse/FOR-244">Issue
+          FOR-244</link>.
+        </p>
+      </section><section id="encoding"><title>2.17. 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: ã ñ &#297; õ &#361;</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">
+&lt;?xml version="1.0" encoding="UTF-8"?&gt;
+        </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">
+&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
+        </source>
+        <p>
+          Another option is to use "character entities" such as <code>
+&amp;ouml;
+          </code> (ö) or the numeric form <code>
+&amp;#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 id="xml-entities"><title>2.18. How to use XML entities, for example string
+        replacement?</title>
+        <p>
+          A set of symbols is available. See the demonstration in a fresh
+          'forrest seed' site (at
+          <link href="http://forrest.zones.apache.org/ft/build/forrest-seed/samples-b/xml-entities.html">samples-b/xml-entities.html</link>).
+          For example, use
+          "<code>&amp;myp-t;</code>" to represent the project name together with
+          trademark symbol "My Project Name&#8482;". Avoid lengthy typing and
+          potential spelling errors.
+        </p>
+      </section><section id="cleanSite"><title>2.19.  How to make Forrest clean up the project build directories? </title>
+        <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>
+      </section><section id="i18n"><title>2.20. How can I internationalise (i18n) my content?</title>
+        <p>
+          For example, navigation
+          menus can be internationalized and different content can be served.
+        </p>
+        <p>
+          There is an example to demonstrate and explain the facilities.
+          See a 'forrest seed-sample' site.
+        </p>
+        <p>
+          All internationalisation of tokens is carried out by the
+          <link href="http://cocoon.apache.org/2.1/userdocs/i18nTransformer.html">Cocoon
+          i18n Transformer</link>.
+        </p>
+      </section><section id="rawHTML"><title>2.21. How can I include HTML content that is not to be skinned by Forrest?</title>
+        <p>
+          To serve, for example a legacy HTML site, add something like the
+          following to your project's sitemap and place the source content in a
+          <code>src/documentation/content/old_site/</code> directory.
+        </p>
+        <source xml:space="preserve">
+
+      &lt;map:match pattern="old_site/**.html"&gt;
+        &lt;map:select type="exists"&gt;
+          &lt;map:when test="{properties:content}{0}"&gt;
+            &lt;map:read src="{properties:content}{0}" mime-type="text/html"/&gt;
+&lt;!--
+            If you want JTidy to clean up your HTML source, then use a
+            generator/serializer instead of the reader. However see FOR-679.
+            &lt;map:generate type="html" src="{properties:content}{0}" /&gt;
+            &lt;map:serialize type="html"/&gt;
+            --&gt;
+          &lt;/map:when&gt;
+        &lt;/map:select&gt;
+      &lt;/map:match&gt;
+     </source>
+        <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
+          <link href="site:sitemap-ref">Cocoon sitemap</link> docs.
+        </p>
+        <p>
+          There is a more detailed discussion of this topic in the samples of a
+          freshly seeded site. To see this documentation do the following:
+        </p>
+        <ol>
+          <li>mkdir seed</li>
+          <li>cd seed</li>
+          <li>forrest seed-sample</li>
+          <li>forrest run</li>
+          <li><code>http://localhost:8888/samples-b/linking.html#no-decoration</code></li>
+        </ol>
+      </section><section id="javascript"><title>2.22. How to include additional Javascript and CSS files?</title>
+        <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 &lt;map:resource name="skin-read"&gt; section.
+        </p>
+      </section><section id="linkmap"><title>2.23. How to show a Table Of Contents for the whole site?</title>
+        <p>
+          Every site has an automatically generated document at
+          <code>/linkmap.html</code> 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 <link href="site:linkmap">Site
+          Linkmap Table of Contents</link>.
+        </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>
+      </section></section><section id="technical"><title>3. Technical</title><section id="java-code"><title>3.1. Where is the Java code?</title>
+        <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>
+      </section><section id="populate-cache"><title>3.2. How to enhance the responsiveness of the cache?</title>
+        <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
+          <link href="http://cocoon.apache.org/2.1/performancetips.html">Cocoon
+          Performance Tips</link> and
+          <link href="http://wiki.apache.org/cocoon/CocoonPerformance">CocoonPerformance</link>
+          and the "Object Stores" section of
+          main/webapp/WEB-INF/cocoon.xconf
+        </p>
+        <p>
+          Responsiveness can be further enhanced by utilising a transparent
+          proxy server, e.g. Apache HTTP Server as a frontend. See
+          <link href="http://wiki.apache.org/cocoon/ApacheModProxy">CocoonAndApacheModProxy</link>.
+        </p>
+      </section><section id="proxy_config"><title>3.3. 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.
+        </p>
+        <p>
+          You can also cross an authenticated proxy by setting the
+          <code>proxy.user</code> and <code>proxy.password</code> accordingly.
+        </p>
+        <note label="Generalise the proxy configuration">
+          You certainly need to cross your proxy for every Forrest projects you
+          have. To avoid to edit every project <code>forrest.properties</code>
+          files, you can do once in your
+          <code>${user.home}/forrest.properties</code> !
+        </note>
+      </section><section id="CVS_revison_tags"><title>3.4. How can I generate html-pages to show the Revision tag of CVS or SVN?</title>
+        <p>
+          If you have:<code>&lt;version&gt;$Revision: 1.30
+          $&lt;/version&gt;</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>
+        <p>
+          When using Subversion, remember to set the relevant svn:keywords
+          properties.
+        </p>
+      </section><section id="cli-xconf"><title>3.5.  How to control the processing of URIs by Cocoon, e.g. exclude certain URIs, include
+        other additional ones. </title>
+        <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 <code>cli.xconf</code> and define
+          patterns for URIs to exclude. There are also other powerful
+          configuration features.
+        </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/main/webapp/WEB-INF/cli.xconf</code> to it.
+          Declare the location of this file in the forrest.properties
+          configuration, e.g.
+          <code>project.configfile=${project.home}/src/documentation/conf/cli.xconf</code>
+        </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>
+        <source xml:space="preserve">
+
+   ....
+   &lt;!-- Includes and excludes can be used to limit which URLs are rendered --&gt;
+   <strong>
+
+   &lt;exclude pattern="**/"/&gt;
+   &lt;exclude pattern="**apidocs**"/&gt;
+   &lt;exclude pattern="api/**"/&gt;
+   </strong>
+
+   &lt;uri src="favicon.ico"/&gt;
+&lt;/cocoon&gt;
+        </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> &#8212; use <strong>foo/**</strong> to match
+          that.
+        </note>
+        <p>
+          See the example "<link href="site:howto/asf-mirror">HowTo Generate an ASF mirrors page</link>"
+          which explains how to include non-linked extra documents to the processing
+          using the Cocoon CLI.
+        </p>
+      </section><section id="ignoring_javadocs"><title>3.6.  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 <link href="#cli-xconf">
+          <code>cli.xconf</code> </link> Cocoon config file, and defining
+          patterns for URLs to exclude.
+        </p>
+      </section><section id="claimed_patterns"><title>3.7. 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 reserved words include: <code>site, wholesite, 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.apache.org/jira/browse/FOR-217">FOR-217</link>).
+        </p>
+      </section><section id="build_msg_a"><title>3.8. What do the symbols and numbers mean when Forrest lists each document that it has
+        built? </title>
+        <p>
+          Each time that Cocoon processes a link, it will report the status
+          messages ...
+        </p>
+        <source xml:space="preserve">
+...
+* [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
+...
+        </source>
+        <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>
+      </section><section id="headless_operation"><title>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. </title>
+        <p>
+          If you are using JDK 1.5 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="project-logo-svg"><title>3.10.  
+        The project logo that is generated from SVG is truncating my project name.
+      </title>
+        <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
+          <code>&lt;project-name&gt;</code> and <code>&lt;group-name&gt;</code>
+          elements of the <code>skinconf.xml</code> 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
+          <code>src/documentation/content/xdocs/images/project.svg</code> and
+          adjust the "width" attribute of the &lt;svg&gt; element. For further
+          details see <link href="http://www.w3.org/Graphics/SVG/">SVG</link>
+          resources.
+        </p>
+      </section><section id="catalog"><title>3.11.  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="project-dtd"><title>3.12. How to configure the Catalog Entity Resolver to use my own local project DTDs?</title>
+        <p>
+          See <link href="site:your-project/new_dtd">Using Forrest</link> for
+          configuration guidance.
+        </p>
+      </section><section id="local-catalog"><title>3.13. We need an additional system-wide catalog to share DTDs between projects</title>
+        <p>
+          See <link href="site:validation/catalog">Using Forrest</link> for
+          configuration guidance.
+        </p>
+      </section><section id="debug-catalog"><title>3.14. How to debug the Catalog Entity Resolver and local DTDs?</title>
+        <p>
+          See <link href="site:validation/debug-catalog">XML validation</link>.
+        </p>
+      </section><section id="skin"><title>3.15.  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.16. 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://svn.apache.org/repos/asf/cocoon/trunk/lib/optional/">jdtcore-*.jar</link> 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
+              <link href="site:project-sitemap">project
+              sitemap</link>
+            </p>
+            <source xml:space="preserve">
+
+  &lt;map:generator name="serverpages"
+     pool-grow="2" pool-max="32" pool-min="4"
+     src="org.apache.cocoon.generation.ServerPagesGenerator"/&gt;
+            </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">
+
+&lt;map:match pattern="dynamic.xml"&gt;
+  &lt;map:generate src="content/xdocs/dynamic.xsp" type="serverpages"/&gt;
+  ...
+  &lt;map:serialize type="xml"/&gt;
+&lt;/map:match&gt;
+            </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.17. 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">
+
+  &lt;trail&gt;
+    &lt;link1 name="Apache Software Foundation" href="http://www.apache.org/"/&gt;
+    &lt;link2 name="Apache Forrest" href="http://forrest.apache.org/"/&gt;
+    &lt;link3 name="" href=""/&gt;
+  &lt;/trail&gt;
+        </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.18. 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 main/webapp/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 id="debugging"><title>3.19. Can I run Forrest with Java debugging turned on?</title>
+        <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 <code>-Xdebug
+          -Xrunjdwp:transport=dt_socket,address=8000,server=y,susp end=n</code>
+          to the <code>forrest.jvmargs</code> property in the
+          <code>forrest.properties</code> file. Don't forget to ensure the
+          property is uncommented in that file.
+        </p>
+      </section><section id="checksums"><title>3.20. How do I enable Cocoon's document checksum feature?</title>
+        <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:
+          <link href="http://marc.theaimsgroup.com/?l=forrest-dev&amp;s=cocoon+checksum">Cocoon
+          Checksum</link> 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 <code>checksums-uri</code> 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:
+          <link href="#cli-xconf">Cocoon cli.xconf</link>) or use the default
+          installation-wide cli.xconf file.
+        </p>
+      </section><section id="sitemap-entities"><title>3.21. How to configure some Cocoon sitemap components, e.g. output html encoding or doctype?</title>
+        <p>
+          The core Cocoon components are defined in the
+          <code>main/webapp/sitemap.xmap</code> file. Normally the default
+          settings are suitable. There are some things that you might like to
+          change per project. For example, change the html encoding for output
+          html files from the default UTF-8 or configure a different document
+          type declaration for the Dispatcher.
+        </p>
+        <p>
+          Create a fresh site with 'forrest seed' and see the set of symbols at the 
+          <code>src/documentation/resources/schema/symbols-project-v10.ent</code> file.
+          Copy that file to your own projects at the same location. Also add the
+          entry to your project xml catalog as shown in the seed site at
+          <code>src/documentation/resources/schema/catalog.xcat</code> file.
+        </p>
+        <p>
+          Now copy the particular entity that you wish to re-define from
+          <code>main/webapp/resources/schema/entity/symbols-core-v10.ent</code>
+          file into your project symbols file and edit the entity declaration.
+          Re-start Forrest.
+        </p>
+      </section><section id="svn-eol-style"><title>3.22. Why are there SVN diffs for some documents, even though they have not changed?</title>
+        <p>
+          These un-necessary differences happen because the comitter who did 'svn add' for those files
+          did not have their Subversion client configured properly for the "svn:eol-style" setting.
+          See some <link href="site:tasks/subversion-monitoring">notes</link>
+          about rectifying this issue.
+        </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.apache.org/jira/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>simplifiedDocbook</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">
+&lt;?xml version="1.0"?&gt;
+&lt;map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0"&gt;
+ &lt;map:pipelines&gt;
+  &lt;map:pipeline&gt;
+   &lt;map:match pattern="resolver-*.html"&gt;
+    &lt;map:generate src="{properties:content.xdocs}resolver-{1}.xml"/&gt;
+    &lt;map:transform
+      src="file:///usr/share/sgml/docbook/xsl-stylesheets/xhtml/docbook.xsl"/&gt;
+    &lt;map:serialize type="xhtml"/&gt;
+   &lt;/map:match&gt;
+  &lt;/map:pipeline&gt;
+ &lt;/map:pipelines&gt;
+&lt;/map:sitemap&gt;
+        </source>
+        <p>
+          You need to define the xhtml serializer used in &lt;map:serialize
+          type="xhtml"/&gt; in the components section of the sitemap. See the
+          <link href="http://cocoon.apache.org/2.1/userdocs/serializers/xhtml-serializer.html">Cocoon
+          docs</link> for the elements you need to add to define this component.
+          You can see examples of other components being added in the
+          <code>FORREST_HOME/main/webapp/sitemap.xmap</code> file. Alternatively
+          use the "html" DocBook stylesheets and the default Cocoon serializer,
+          i.e. &lt;map:serialize type="html"/&gt;
+        </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
+          (<link href="site:cap">SourceTypeAction</link>) 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>
+        <source xml:space="preserve">
+&lt;?xml version="1.0"?&gt;
+&lt;map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0"&gt;
+ &lt;map:components&gt;
+  &lt;map:actions&gt;
+   &lt;map:action logger="sitemap.action.sourcetype"
+      name="sourcetype"src="org.apache.forrest.sourcetype.SourceTypeAction"&gt;
+    &lt;sourcetype name="docbook-v4.2"&gt;
+     &lt;document-declaration public-id="-//OASIS//DTD DocBook XML V4.2//EN"/&gt;
+    &lt;/sourcetype&gt;
+   &lt;/map:action&gt;
+  &lt;/map:actions&gt;
+  &lt;map:selectors default="parameter"&gt;
+   &lt;map:selector logger="sitemap.selector.parameter"
+      name="parameter" src="org.apache.cocoon.selection.ParameterSelector"/&gt;
+  &lt;/map:selectors&gt;
+ &lt;/map:components&gt;
+ &lt;map:pipelines&gt;
+  &lt;map:pipeline&gt;
+   &lt;map:match pattern="**.xml"&gt;
+    &lt;map:act type="sourcetype" src="{properties:content.xdocs}{1}.xml"&gt;
+     &lt;map:select type="parameter"&gt;
+      &lt;map:parameter name="parameter-selector-test" value="{sourcetype}"/&gt;
+      &lt;map:when test="docbook-v4.2"&gt;
+       &lt;map:generate src="{properties:content.xdocs}{../1}.xml"/&gt;
+       &lt;map:transform
+          src="file:///usr/share/sgml/docbook/xsl-stylesheets/html/docbook.xsl"/&gt;
+       &lt;map:transform src="{forrest:forrest.stylesheets}/html-to-document.xsl"/&gt;
+       &lt;map:transform type="idgen"/&gt;
+       &lt;map:serialize type="xml-document"/&gt;
+      &lt;/map:when&gt;
+     &lt;/map:select&gt;
+    &lt;/map:act&gt;
+   &lt;/map:match&gt;
+  &lt;/map:pipeline&gt;
+ &lt;/map:pipelines&gt;
+&lt;/map:sitemap&gt;
+        </source>
+        <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
+          <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.
+          Also when starting <code>'forrest'</code> or <code>'forrest run'</code> 
+          the versions are reported for forrest, java, and ant.
+        </p>
+        <p>
+          To list the properties and other stuff, add "forrest.echo=true" to your
+          forrest.properties file and watch the build messages. Doing
+          <code>'forrest -v'</code> will provide verbose build messages and other useful
+          information.
+        </p>
+        <p>
+          In <code>'forrest run'</code> mode, use the
+          <link href="site:forrestbar">Forrestbar</link> to see the build-info
+          and properties, or access them directly:
+        </p>
+        <ul>
+          <li><code>http://localhost:8888/build-info</code></li>
+          <li><code>http://localhost:8888/module.properties.properties</code></li>
+        </ul>
+        <p>
+          See the documentation about the new <link href="site:properties">Properties</link>
+          system.
+        </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>main/webapp/WEB-INF/logkit.xconf</code> file. If you are
+          generating a static site (with command-line 'forrest') then copy
+          <code>$FORREST_HOME/main/webapp/WEB-INF/logkit.xconf</code> to your
+          project at <code>src/documentation/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="verbose-ant"><title>5.5.  How to filter or reduce the standard output messages? </title>
+        <p>
+          Where normally you would do 
+          <code>'forrest'</code> or <code>'forrest run'</code> etc. instead use
+          the "quiet" option, and do 
+          <code>'forrest -q'</code> or <code>'forrest -q run'</code> etc.
+          If errors are reported, then drop the "quiet" option and run again to
+          get the context for the error.
+        </p>
+        <p>
+          Doing <code>'forrest -v'</code> will provide very verbose build messages to
+          the standard output.
+        </p>
+      </section><section id="coloured-ant"><title>5.6.  How to enabled coloured standard output messages? </title>
+        <p>
+          Adding colour to the forrest output messages will greatly assist
+          readability.
+        </p>
+        <p>
+          Set the ANT_ARGS environment variable like so:<br/>
+          <code>export ANT_ARGS="$ANT_ARGS -logger org.apache.tools.ant.listener.AnsiColorLogger"</code>
+        </p>
+        <p>
+          To change the default colours, set the ANT_OPTS environment variable
+          like so:<br/>
+          <code>export ANT_OPTS="$ANT_OPTS -Dant.logger.defaults=$FORREST_HOME/etc/AnsiColorLogger.properties"</code><br/>
+          and create that configuration file as
+          <link href="http://ant.apache.org/manual/listeners.html#AnsiColorLogger">explained</link>
+          in the Apache Ant Manual.
+          That is required on Mac OS X and the "Attribute" for each colour needs
+          to be "0" rather than the default "2".
+        </p>
+        <p>
+          Note that not all terminals support ANSI color codes.
+        </p>
+      </section><section id="how_can_I_help"><title>5.7.  How to help? </title>
+        <p>
+          Join one of the Forrest project <link href="site:mail-lists">mailing
+          lists</link> and tell us what you would like to see improved. We
+          regard all feedback as valuable, particularly from
+          newcomers&#8212;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.8.  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 id="jobs"><title>5.9.  How can job positions be advertised? </title>
+        <p>
+          Employers can send notices about employment opportunities. There is a
+          special jobs&lt;AT&gt;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 <link href="site:mail-lists">mailing
+          lists</link>).
+        </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
+          (<link href="http://www.apache.org/licenses/">CCLA</link>) with The
+          Apache Software Foundation.
+        </p>
+      </section><section id="press"><title>5.10. Is there a press kit? Who can journalists contact?</title>
+        <p>
+         Press enquiries should be co-ordinated through the ASF Public Relations Committee (PRC).
+         See <link href="http://www.apache.org/foundation/contact.html">contact</link> information.
+         The PRC also provides guidelines and handles particular usage of ASF
+         trademarks and logos (see also
+         <link href="http://www.apache.org/foundation/licence-FAQ.html#Marks">FAQ</link>
+         and
+         <link href="http://www.apache.org/foundation/marks/">Guidelines</link>).
+        </p>
+        <p>
+          The Apache Forrest logo
+          (<link href="/images/project-logo.png">PNG</link>)
+          and banner (<link href="http://svn.apache.org/repos/asf/forrest/trunk/site-author/resources/images/apache-forrest-original.svg">SVG</link>
+          | <link href="/images/apache-forrest.png">PNG</link>)
+          are available.
+          Unfortunately the logo is only available as PNG.
+        </p>
+      </section><section id="security"><title>5.11. How to report a security issue?</title>
+        <p>
+         Security and vulnerability issues are co-ordinated through the
+         <link href="http://www.apache.org/security/">ASF Security Team</link>.
+         This is only for reporting undisclosed security vulnerabilities in
+         Apache products. For other issues, use the Forrest project
+         <link href="site:bugs">Issue tracker</link>.
+        </p>
+      </section></section></body></document>
\ No newline at end of file

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



Mime
View raw message