| <?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="Questions"><title>Questions</title><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:v0.70//your-project">Using Forrest</link> guide. </p> |
| </section><section id="requirements"><title>1.3. 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.4 (or newer) is required. If you are only going to use Forrest |
| as-is then you need only the Java Runtime Environment (JRE). |
| If you intend to enhance and rebuild Forrest (or use the Forrest sources |
| with Subversion or use a source snapshot) then you need the full JDK. |
| </p> |
| </section><section id="cvs"><title>1.4. 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.5. How can I use SVN to keep up to date with the latest codebase? </title> |
| <p> Follow these <link href="site:v0.70//build">Building Forrest</link> notes. </p> |
| <p> The <link href="site:v0.70//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.6. 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:v0.70//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.7. 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:v0.70//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.8. 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/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.9. 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:v0.70//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:v0.70//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 left-hand 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:v0.70//linking">Menus and Linking</link>. Here is a precis: |
| </p> |
| <p> |
| The labels can be whatever text you want. |
| </p> |
| <source xml:space="preserve"><faq label="FAQs" href="faq.html"> |
| <tech label="Technical" href="faq-tech.html"> |
| <docbook href="#docbook"/> |
| <ignoring_javadocs href="#ignoring_javadocs"/> |
| </tech> |
| <user label="User" href="faq-user.html"> |
| </faq></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"><a href="site:v0.70//faq/tech"> link to the top of the Tech FAQs |
| <a href="site:v0.70//faq/tech/docbook"> 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"><a href="site:v0.70//docbook"> 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 (cd forrest/site-author; forrest run). |
| </p> |
| </section><section id="PDF-output"><title>2.4. 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:v0.70//howto/pdf-tab">How to create a PDF document for each |
| tab</link>.) </p> |
| <p> This assumes that you use the <link href="site:v0.70//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.5. 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.6. 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/document2html.xsl</code> and edit the |
| "headers/authors" template. </p> |
| </section><section id="link_raw"><title>2.7. 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:v0.70//upgrading_07/raw">Upgrading to Apache Forrest 0.7</link> for |
| all the details.</p> |
| </section><section id="pdf_images"><title>2.8. 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="tab-index"><title>2.9. The tab link in my site incorrectly assumes that 'index.html' is present in the |
| linked-to directory. How do I fix this? </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="tab-site"><title>2.10. I need help with the interaction between tabs.xml and site.xml </title> |
| <p> |
| See the <link href="site:v0.70//linking/tab-site">tips</link>. |
| </p> |
| </section><section id="defaultFileName"><title>2.11. 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 |
| <default-filename>index.html</default-filename> |
| with 'overview.html'. </li> |
| <li> Edit your project's <link href="site:v0.70//project-sitemap">sitemap.xmap</link> file. </li> |
| <li> Add the following code just before the end of the pipelines-element:<source xml:space="preserve"> |
| <map:pipeline> |
| <map:match type="regexp" pattern="^.+/$"> |
| <map:redirect-to uri="overview.html"/> |
| </map:match> |
| </map:pipeline> |
| </source></li> |
| </ol> |
| </section><section id="defaultStartPage"><title>2.12. 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:v0.70//project-sitemap">sitemap.xmap</link> file.</li> |
| <li>Add the following code just before the end of the pipelines-element:<source xml:space="preserve"> |
| <map:pipeline> |
| <map:match pattern=""> |
| <map:redirect-to uri="start.html" /> |
| </map:match> |
| </map:pipeline> |
| </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="label-entity"><title>2.13. 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.apache.org/jira/browse/FOR-244">Issue FOR-244</link>. </p> |
| </section><section id="encoding"><title>2.14. 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 id="cleanSite"><title>2.15. 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.16. How can I internationalise (i18n) my content?</title> |
| <p>The i18n features of Forrest are still under development (as of 0.7) however there are |
| some features available. For example, navigation menus can be i18n'd (see fresh-site for an |
| example). Currently, <link href="http://issues.apache.org/jira/browse/FOR-506">work is underway</link> to |
| i18n skins</p> |
| |
| <p>All internationalistation of tokens in, for example, the skins and the menus, is carried out |
| by the <link href="http://cocoon.apache.org/2.1/userdocs/transformers/i18n-transformer.html">Cocoon i18n |
| Transformer</link>. You can see an example of how it works in the above linked issue.</p> |
| </section><section id="rawTML"><title>2.17. How can I include HTML content that is not to be skinned by Forrest?</title> |
| <p>To server, for example, a legacy HTML site add something like the following |
| to your projects sitemap:</p> |
| <source xml:space="preserve"> |
| <map:match pattern="old_site/**.html"> |
| <map:select type="exists"> |
| <map:when test="{properties:content}{0}"> |
| <map:read src="{properties:content}/{0}" mime-type="text/html"/> |
| <!-- |
| Use this instead if you want JTidy to clean up your HTML |
| <map:generate type="html" src="{properties:content}/{0}" /> |
| <map:serialize type="html"/> |
| --> |
| </map:when> |
| </map:match> |
| </source> |
| <p>There is a more detailed discussion of this topic in the samples |
| of a freshly seeded site. To see this documentation do the following:</p> |
| <ol> |
| <li>mkdir seed</li> |
| <li>cd seed</li> |
| <li>forrest seed</li> |
| <li>forrest</li> |
| <li><link href="http://localhost:8888/samples/linking.html#Serving+%28X%29HTML+content+without+Skinning">Read the doc</link></li> |
| </ol> |
| </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.</p> |
| <p>You can also cross an authenticated proxy by setting the <code>proxy.user</code> and <code>proxy.password</code> accordingly.</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:v0.70//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="cli-xconf"><title>3.3. 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"> |
| .... |
| <!-- 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:v0.70//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="ignoring_javadocs"><title>3.4. 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.5. 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 id="build_msg_a"><title>3.6. What do the symbols and numbers mean when Forrest lists each document that it has |
| built? </title><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 - the number of pages processed and the number remaining. The latter will change because during processing one page, Cocoon will discover more.</li> |
| <li>Column 3 is the number of links that were gathered from that page.</li> |
| <li>Column 4 is the time taken.</li> |
| <li>Column 5 is the page size.</li> |
| </ul> |
| </p></section><section id="headless_operation"><title>3.7. When generating PNG images from SVG, I get an error: Can't connect to X11 window |
| server using ':0.0' as the value of the DISPLAY variable. </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="project-logo-svg"><title>3.8. |
| 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><project-name></code> and |
| <code><group-name></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 <svg> element. For further details see |
| <link href="http://www.w3.org/Graphics/SVG/">SVG</link> resources. |
| </p> |
| </section><section id="catalog"><title>3.9. 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:v0.70//catalog">Using Catalog Entity |
| Resolver for local DTDs</link>. </p> |
| </section><section id="skin"><title>3.10. How to make the site look better and change its skin? </title> |
| <p> There are <link href="site:v0.70//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:v0.70//your-project/skins">configuration</link> of the skins. |
| Some projects may have special needs and can define their <link href="site:v0.70//your-project/new-skin">own skin</link>. </p> |
| </section><section id="xsp"><title>3.11. 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/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:v0.70//project-sitemap">project sitemap</link> |
| </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.12. 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.13. 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><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:v0.70//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:v0.70//project-sitemap">project |
| sitemap</link> as explained in <link href="site:v0.70//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="{properties:content.xdocs}resolver-{1}.xml"/> |
| <map:transform |
| src="file:///usr/share/sgml/docbook/xsl-stylesheets/xhtml/docbook.xsl"/> |
| <map:serialize type="xhtml"/> |
| </map:match> |
| </map:pipeline> |
| </map:pipelines> |
| </map:sitemap></source> |
| <p>You need to define the xhtml serializer used in <map:serialize type="xhtml"/> |
| 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.</p> |
| <p> You can also use a mixture of the two methods, some handled automatically by Forrest and |
| some directly using DocBook stylesheets. You can also have a mixture of source files as |
| "document-v*" DTD and DocBook. </p> |
| <p> Ensure that the document type declaration in your xml instance is well specified. Use a |
| public identifier. The DTD will then be properly resolved by Forrest. If you need to use |
| different DTDs, then see <link href="site:v0.70//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/main/webapp/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="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—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> |
