Return-Path: Delivered-To: apmail-forrest-svn-archive@www.apache.org Received: (qmail 66726 invoked from network); 10 Apr 2007 03:50:03 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 10 Apr 2007 03:50:03 -0000 Received: (qmail 14101 invoked by uid 500); 10 Apr 2007 03:50:09 -0000 Delivered-To: apmail-forrest-svn-archive@forrest.apache.org Received: (qmail 14043 invoked by uid 500); 10 Apr 2007 03:50:09 -0000 Mailing-List: contact svn-help@forrest.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: List-Post: Reply-To: "Forrest Developers List" List-Id: Delivered-To: mailing list svn@forrest.apache.org Received: (qmail 13956 invoked by uid 99); 10 Apr 2007 03:50:08 -0000 Received: from herse.apache.org (HELO herse.apache.org) (140.211.11.133) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 09 Apr 2007 20:50:08 -0700 X-ASF-Spam-Status: No, hits=-99.5 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO eris.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 09 Apr 2007 20:49:53 -0700 Received: by eris.apache.org (Postfix, from userid 65534) id B0E741A985D; Mon, 9 Apr 2007 20:49:05 -0700 (PDT) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: svn commit: r527010 [10/26] - in /forrest/trunk/site-author/content: ./ skins/ xdocs/ xdocs/docs_0_70/ xdocs/docs_0_70/howto/ xdocs/docs_0_70/howto/bugzilla-patch/ xdocs/docs_0_70/howto/cvs-ssh/ xdocs/docs_0_70/howto/multi/ xdocs/docs_0_80/ xdocs/docs_... Date: Tue, 10 Apr 2007 03:48:57 -0000 To: svn@forrest.apache.org From: crossley@apache.org X-Mailer: svnmailer-1.1.0 Message-Id: <20070410034905.B0E741A985D@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Modified: forrest/trunk/site-author/content/xdocs/docs_0_80/faq.xml URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_80/faq.xml?view=diff&rev=527010&r1=527009&r2=527010 ============================================================================== --- forrest/trunk/site-author/content/xdocs/docs_0_80/faq.xml (original) +++ forrest/trunk/site-author/content/xdocs/docs_0_80/faq.xml Mon Apr 9 20:48:52 2007 @@ -25,78 +25,90 @@ How to use these FAQs?

- There is no particular order to these FAQs. Use your browser's - "Find in this page" facility to search for keywords. + There is no particular order to these FAQs. Use your browser's "Find + in this page" facility to search for keywords.

Where can I read an overview about how to work with Forrest? -

See the Using Forrest guide.

+

+ See the Using Forrest guide. +

Where is all of the documentation?

- You have a local copy of the main documentation with your version of Forrest. - Do 'cd site-author; forrest run' and visit http://localhost:8888/ in your browser. - The most recent documentation is in SVN trunk which creates the forrest.apache.org website. + You have a local copy of the main documentation with your version of + Forrest. Do 'cd site-author; forrest run' and visit + http://localhost:8888/ in your browser. The most recent documentation + is in SVN trunk which creates the forrest.apache.org website.

- Each plugin has its own documentation - and working examples of its techniques. + Each plugin has its own + documentation and working examples of its techniques.

- 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 - testing zone. + 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 testing zone.

What are the system requirements for Forrest? -

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. +

+ 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.

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. + 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.

The old xml-forrest CVS code repository seems to be stale. What happened? -

Forrest switched from a CVS code repository to SVN (Subversion) code repository. The old - CVS repository is closed and not kept current.

+

+ Forrest switched from a CVS code repository to SVN (Subversion) code + repository. The old CVS repository is closed and not kept current. +

How can I use SVN to keep up to date with the latest codebase? -

Follow these Building Forrest notes.

-

The Using Forrest guide provides further - step-by-step assistance in getting started with Forrest for your project.

+

+ Follow these Building Forrest notes. +

+

+ The Using Forrest guide provides + further step-by-step assistance in getting started with Forrest for + your project. +

How to use older versions of specific plugins?

- 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 + 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 documentation.

- In the forrest.properties file, specify the version of the plugin - that you require, e.g. + In the forrest.properties file, specify the version of the plugin that + you require, e.g.

project.required.plugins=org.apache.forrest.plugin.input.PhotoGallery-0.1,...

@@ -117,24 +129,20 @@ What is the best way to generate "standalone documents" using Forrest?

- There is a trick that can cut down your turnaround time - with building. In forrest.properties ... + There is a trick that can cut down your turnaround time with building. + In forrest.properties ...

- # The URL to start crawling from #project.start-uri=linkmap.html -

- 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 + 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.

-

It is probably easiest to make this change temporarily as a command-line parameter, e.g. @@ -142,28 +150,25 @@ forrest -Dproject.start-uri=live-sites.html -

- You can terminate forrest with 'kill' or Ctrl-C after it - has built your pages of interest. + You can terminate forrest with 'kill' or Ctrl-C after it has built + your pages of interest.

-

- Cocoon can be instructed via the - Cocoon cli.xconf 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. + Cocoon can be instructed via the Cocoon + cli.xconf 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.

-

- Cocoon can also be instructed to not process certain URIs - if you need to temporarily exclude then. + Cocoon can also be instructed to not process certain URIs if you need + to temporarily exclude then.

- Another useful technique is to use 'wget' or Apache Ant's Get task - to retrieve individual files, e.g. - Do 'forrest run' and then 'wget http://localhost:8888/index.pdf'. + Another useful technique is to use 'wget' or Apache Ant's Get task to + retrieve individual files, e.g. Do 'forrest run' and then 'wget + http://localhost:8888/index.pdf'.

@@ -171,31 +176,43 @@ When running ./build.sh in cygwin, I get an error: cygpath.exe: *** can't create title mutex, Win32 error 6. -

This appears - to be a bug in cygwin. Please use the .bat script instead.

+

+ This + appears + to be a bug in cygwin. Please use the .bat script instead. +

How can I specify the amount of memory to be used by Java? -

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.

-

The maxmemory property in the forrest.properties file controls - how much memory Cocoon uses. Like many other properties you can copy them from the default +

+ 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. +

+

+ The maxmemory property in the + forrest.properties file controls how much memory Cocoon + uses. Like many other properties you can copy them from the default configuration at main/fresh-site/forrest.properties

-

Set the ANT_OPTS environment variable before you run forrest. The exact - value you set it to is dependant on your JVM, but something like - ANT_OPTS=-Xmx500M will probably work.

+

+ Set the ANT_OPTS environment variable before you run + forrest. The exact value you set it to is dependant on your JVM, but + something like ANT_OPTS=-Xmx500M will probably work. +

How can I start forrest in Java debug mode? -

The forrest.jvmargs property in the forrest.properties file - can be used to start forrest in debug mode on a specific port. - forrest.jvmargs=-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n +

+ The forrest.jvmargs property in the + forrest.properties file can be used to start forrest in + debug mode on a specific port. forrest.jvmargs=-Xdebug + -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n

@@ -205,16 +222,27 @@ What tools can be used to edit the content? -

If you are using the Apache Forrest XML document format - 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 configuration notes for various editors.

-

There are content management systems like Apache Lenya.

-

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.

+

+ If you are using the Apache Forrest XML + document format 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 + configuration notes for + various editors. +

+

+ There are content management systems like + Apache Lenya. +

+

+ 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. +

@@ -223,40 +251,44 @@

- The site.xml 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 - Menus and Linking. Here is a precis: + The site.xml 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 Menus and Linking. + Here is a precis:

The labels can be whatever text you want.

- + + -]]> +]]> +

That will create a menu like this with three links:

FAQs Technical User -

These documents can be linked to from other documents, like this:

- link to the top of the Tech FAQs - link to the DocBook FAQ in the Tech FAQs]]> - + + link to the top of the Tech FAQs + link to the DocBook FAQ in the Tech FAQs]]> +

If that "docbook" entry was a unique name in your site.xml then you can shorten that latter link:

- link to the DocBook FAQ in the Tech FAQs]]> + + link to the DocBook FAQ in the Tech FAQs]]> + @@ -265,9 +297,9 @@

- 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). + 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).

@@ -282,49 +314,63 @@ document and crawls the links to find other documents to process.

- 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. + 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.

- 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. - + 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.

How can I generate one pdf-file out of the whole site or selected pages of the site? -

Add the following entries to your site.xml file:

- + Add the following entries to your site.xml file: +

+ + ... ... - ]]> -

In this case the menu labeled "About" will have 2 new items: "Full PDF" and "Full HTML". - (See also How to create a PDF document for each - tab.)

-

This assumes that you use the site.xml method for your - site structure and navigation, rather than the old book.xml method.

+ ]]> + +

+ In this case the menu labeled "About" will have 2 new items: "Full + PDF" and "Full HTML". (See also How to + create a PDF document for each tab.) +

+

+ This assumes that you use the + site.xml method for your site + structure and navigation, rather than the old book.xml method. +

How do I insert page breaks into documents? -

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.

-

To insert a page break in a PDF document simply add pageBreakBefore and/or - pageBreakAfter 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.

-

If you want these classes to be processed in your HTML documents as well you should add - the following to the extra-css element in your projects - skinconf.xml +

+ 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. +

+

+ To insert a page break in a PDF document simply add + pageBreakBefore and/or pageBreakAfter 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. +

+

+ If you want these classes to be processed in your HTML documents as + well you should add the following to the extra-css + element in your projects skinconf.xml

.pageBreakBefore { @@ -341,58 +387,83 @@ How can I generate html-pages to show a 'clickable' email-address (of the author-element)? -

You would override - $FORREST_HOME/main/webapp/skins/common/xslt/html/document-to-html.xsl and edit the - "headers/authors" template.

+

+ You would override + $FORREST_HOME/main/webapp/skins/common/xslt/html/document-to-html.xsl + and edit the "headers/authors" template. +

How do I link to raw files such as config.txt and brochure.pdf? -

Handling of raw files was significantly changed in Forrest 0.7. See - Upgrading to Apache Forrest 0.7 for - all the details.

+

+ Handling of raw files was significantly changed in Forrest 0.7. See + Upgrading to Apache Forrest + 0.7 for all the details. +

Images don't display in PDFs. How do I fix this? -

Forrest uses Apache FOP 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 FOP Graphics formats +

+ Forrest uses Apache FOP + 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 + FOP + Graphics formats +

+

+ To get PNGs working in PDFs with Jimi:

-

To get PNGs working in PDFs with Jimi:

  1. Download Jimi from http://java.sun.com/products/jimi/ -
    2. + >http://java.sun.com/products/jimi/
  2. Unpack the Jimi distribution and copy JimiProClasses.zip to $FORREST/lib/optional/jimi-1.0.jar.
-

Alternatively you can use JAI (Java Advanced Imaging API at - http://java.sun.com/products/java-media/jai). For more info, see FOP Graphics Packages -

- Due to Sun's licensing, we cannot redistribute Jimi or JAI with Forrest. +

+ Alternatively you can use JAI (Java Advanced Imaging API at + http://java.sun.com/products/java-media/jai). For more + info, see + FOP + Graphics Packages +

+ + Due to Sun's licensing, we cannot redistribute Jimi or JAI with + Forrest. + The tab link in my site incorrectly assumes that 'index.html' is present in the linked-to directory. How do I fix this? -

In tabs.xml, 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 manual/Introduction.html then tabs.xml should - contain:

- ]]> -

and add this rule to the sitemap:

- + In tabs.xml, 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 + manual/Introduction.html then tabs.xml + should contain: +

+ +]]> + +

+ and add this rule to the sitemap: +

+ + - ]]> + ]]> + @@ -407,42 +478,56 @@ How can I change the default file name that Forrest will look for when I request a URL like http://myserver or http://myserver/mydir/ ? -

To change the default file name from 'index.html' (default) to 'overview.html' you need to - make the following changes:

+

+ To change the default file name from 'index.html' (default) to + 'overview.html' you need to make the following changes: +

  1. Create a 'cli.xconf' file for your project
  2. Edit that file to replace 'index.html' in index.html]]> with 'overview.html'.
  3. Edit your project's sitemap.xmap file.
    4. -
  4. Add the following code just before the end of the pipelines-element: Add the following code just before the end of the pipelines-element: + - ]]>
    5. + ]]> +
How can I use a start-up-page other than index.html? -

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

-

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'.

-

To change the start page of a site:

+

+ 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 +

+

+ 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'. +

+

+ To change the start page of a site: +

  1. Edit your project's sitemap.xmap file.
    2. -
  2. Add the following code just before the end of the pipelines-element:Add the following code just before the end of the pipelines-element: + - ]]>
    3. + ]]> +
  3. Name the uri-attribute whatever you'd like your start page to be.
  4. Don't forget to create that page and refer to it in your site.xml
@@ -451,55 +536,98 @@ How to use special characters in the labels of the site.xml file? -

Use the numeric values for character entities. For example, rather than using - use +

+ Use the numeric values for character entities. For example, rather + than using + + use + +

-

See the + See the + XHTML Character Entities and see more discussion at Issue FOR-244.

+ >XHTML + Character Entities and see more discussion at + Issue + FOR-244. +

Does Forrest handle accents for non-English languages? -

Yes, Forrest can process text in any language, so you can include:

+

+ Yes, Forrest can process text in any language, so you can include: +

  • accents: á é í ó ú
  • diereses: ä ë ï ö ü
  • tildes: ã ñ Ä© õ Å©
-

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:

- ]]> -

but the file content is actually using ISO-8859-1 then you will receive validation - errors, especially if you include some non-ASCII characters.

-

This situation is commonly encountered when you edit the templates created by - forrest seed 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.

-

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 LANG to an appropriate value, for instance:

+

+ 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: +

+ +]]> + +

+ but the file content is actually using ISO-8859-1 then you will + receive validation errors, especially if you include some non-ASCII + characters. +

+

+ This situation is commonly encountered when you edit the templates + created by forrest seed 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. +

+

+ 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 LANG to + an appropriate value, for instance: +

[localhost]$ export LANG=en_US.UTF-8 -

Of course the appropriate 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 encoding 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:

- ]]> -

Another option is to use "character entities" such as - (ö) or the numeric form (ö).

-

Another related issue is that your webserver needs to send http headers with the matching - charset definitions to the html page.

-

Here are some references which explain further: GT2004 presentation by Torsten - Schlabach and Alan Wood's Unicode - resources.

+

+ Of course the appropriate 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 encoding + 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: +

+ +]]> + +

+ Another option is to use "character entities" such as + + (ö) or the numeric form + + (ö). +

+

+ Another related issue is that your webserver needs to send http + headers with the matching charset definitions to the html page. +

+

+ Here are some references which explain further: + GT2004 + presentation by Torsten Schlabach and + Alan Wood's Unicode + resources. +

@@ -507,12 +635,11 @@ replacement?

- A set of symbols is available. See the demonstration - in a fresh 'forrest seed' site (at samples/xml-entities.html). - For example, use "&myp-t;" to represent the - project name together with trademark symbol - "My Project Name™". - Avoid lengthy typing and potential spelling errors. + A set of symbols is available. See the demonstration in a fresh + 'forrest seed' site (at samples/xml-entities.html). For example, use + "&myp-t;" to represent the project name together with + trademark symbol "My Project Name™". Avoid lengthy typing and + potential spelling errors.

@@ -525,33 +652,41 @@ successive runs of forrest.

- 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. + 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.

How can I internationalise (i18n) my content? -

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, work is underway to - i18n skins

- -

All internationalistation of tokens in, for example, the skins and the menus, is carried out - by the Cocoon i18n - Transformer. You can see an example of how it works in the above linked issue.

+

+ 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, + work is + underway to i18n skins +

+

+ All internationalistation of tokens in, for example, the skins and the + menus, is carried out by the + Cocoon + i18n Transformer. You can see an example of how it works in the + above linked issue. +

How can I include HTML content that is not to be skinned by Forrest? -

To serve, for example a legacy HTML site, add something like the following - to your project's sitemap and place the source content at the - src/documentation/content/xdocs/old_site/ directory.

+

+ To serve, for example a legacy HTML site, add something like the + following to your project's sitemap and place the source content at + the src/documentation/content/xdocs/old_site/ directory. +

<map:match pattern="old_site/**.html"> <map:select type="exists"> @@ -566,14 +701,16 @@ </map:select> </map:match> - -

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 - Cocoon sitemap docs.

- -

There is a more detailed discussion of this topic in the samples - of a freshly seeded site. To see this documentation do the following:

+

+ 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 + Cocoon sitemap docs. +

+

+ There is a more detailed discussion of this topic in the samples of a + freshly seeded site. To see this documentation do the following: +

  1. mkdir seed
  2. cd seed
    3. @@ -583,47 +720,44 @@
- How to include additional Javascript and CSS files?

- 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. + 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.

- Then refer to those from your source documents with - URIs like /skin/blah.js and /skin/foo.css + Then refer to those from your source documents with URIs like + /skin/blah.js and /skin/foo.css

- See how this is handled in the core sitemap - called forrest/main/webapp/resources.xmap - Search for "javascript" then follow to the - <map:resource name="skin-read"> section. + See how this is handled in the core sitemap called + forrest/main/webapp/resources.xmap Search for "javascript" then follow + to the <map:resource name="skin-read"> section.

- How to show a Table Of Contents for the whole site?

Every site has an automatically generated document at - /linkmap.html - 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. + /linkmap.html 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.

- For example, the Forrest project's Site Linkmap Table of Contents. + For example, the Forrest project's Site + Linkmap Table of Contents.

- The document is also useful when developing your documentation and linking - to other docs. The element names (column #2) e.g. - href="site:mail-lists" or href="site:howto/overview" + The document is also useful when developing your documentation and + linking to other docs. The element names (column #2) e.g. + href="site:mail-lists" or + href="site:howto/overview"

This is also the document that 'forrest site' uses to kick-start the @@ -640,13 +774,14 @@

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. + 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.

- 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. + 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.

That said, you will find some Java code in Forrest at main/java/... @@ -660,23 +795,27 @@ How to enhance the responsiveness of the cache?

- 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. + 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.

The Cocoon cache and sitemaps can be tuned. See - Cocoon Performance Tips - and + Cocoon + Performance Tips and CocoonPerformance - and the "Object Stores" section of main/webapp/WEB-INF/forrest-core.xconf + and the "Object Stores" section of + main/webapp/WEB-INF/forrest-core.xconf

-

Responsiveness can be further enhanced by utilising a transparent proxy server, e.g. Apache HTTP Server as a frontend. See CocoonAndApacheModProxy. +

+ Responsiveness can be further enhanced by utilising a transparent + proxy server, e.g. Apache HTTP Server as a frontend. See + CocoonAndApacheModProxy.

@@ -684,24 +823,40 @@ I'm behind a proxy and it's preventing Plugins from being downloaded, what should I do? -

You can configure the proxy in the forrest.properties file. Set the - proxy.host and proxy.port accordingly.

-

You can also cross an authenticated proxy by setting the proxy.user and proxy.password accordingly.

- You certainly need to cross your proxy for every Forrest projects you have. - To avoid to edit every project forrest.properties files, you can do once in your ${user.home}/forrest.properties ! +

+ You can configure the proxy in the forrest.properties + file. Set the proxy.host and proxy.port + accordingly. +

+

+ You can also cross an authenticated proxy by setting the + proxy.user and proxy.password accordingly. +

+ + You certainly need to cross your proxy for every Forrest projects you + have. To avoid to edit every project forrest.properties + files, you can do once in your + ${user.home}/forrest.properties ! + How can I generate html-pages to show the Revision tag of CVS or SVN? -

If you have:<version>$Revision: 1.30 +

+ If you have:<version>$Revision: 1.30 $</version>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 Using Forrest document.

-

This technique could also be used for a modification date with $Date: 2004/01/15 08:52:47 - $

+ displayed at the bottom of the page as "version 1.30". See for + example the bottom of the Using + Forrest document. +

- When using Subversion, remember to set the relevant svn:keywords properties. + This technique could also be used for a modification date with $Date: + 2004/01/15 08:52:47 $ +

+

+ When using Subversion, remember to set the relevant svn:keywords + properties.

@@ -709,54 +864,80 @@ How to control the processing of URIs by Cocoon, e.g. exclude certain URIs, include other additional ones. -

Forrest uses a configuration file to control the processing done by the Apache Cocoon - command-line called cli.xconf

-

Your project can supply its own cli.xconf and define patterns for URIs to - exclude. There are also other powerful configuration features.

-

This means creating a directory src/documentation/conf (or wherever - ${forrest.conf-dir} points) and copying - $FORREST_HOME/main/webapp/WEB-INF/cli.xconf to it. Declare the location of - this file in the forrest.properties configuration, e.g. - project.configfile=${project.home}/src/documentation/conf/cli.xconf -

-

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/':

- + Forrest uses a configuration file to control the processing done by + the Apache Cocoon command-line called cli.xconf +

+

+ Your project can supply its own cli.xconf and define + patterns for URIs to exclude. There are also other powerful + configuration features. +

+

+ This means creating a directory src/documentation/conf + (or wherever ${forrest.conf-dir} points) and copying + $FORREST_HOME/main/webapp/WEB-INF/cli.xconf to it. + Declare the location of this file in the forrest.properties + configuration, e.g. + project.configfile=${project.home}/src/documentation/conf/cli.xconf +

+

+ 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/': +

+ + - ]]> + - ]]> + -]]> -

This is just an example, and you should modify it appropriately for your site.

- Wildcards may be used. These are a powerful feature of Cocoon's sitemap. For example, foo/* would match - foo/bar, but not foo/bar/baz — use - foo/** to match that. +]]> + +

+ This is just an example, and you should modify it appropriately for + your site. +

+ + Wildcards may be used. These are a powerful feature of Cocoon's + sitemap. For example, + foo/* would match foo/bar, but not + foo/bar/baz — use foo/** to match + that. + How do I stop Forrest breaking on links to external files that may not exist, like javadocs? -

This can be done by overriding the - cli.xconf - Cocoon config file, and defining patterns for URLs to exclude.

+

+ This can be done by overriding the + cli.xconf Cocoon config file, and defining + patterns for URLs to exclude. +

Some of my files are not being processed because they use common filenames. -

Certain patterns are claimed by the default sitemaps for special processing. These reserved words - include: site, changes, todo, faq, images, my-images, skinconf, community, - howto -

-

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 (FOR-217). +

+ Certain patterns are claimed by the default sitemaps for special + processing. These reserved words include: site, changes, todo, + faq, images, my-images, skinconf, community, howto +

+

+ 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 + (FOR-217).

@@ -765,15 +946,18 @@ built?

- Each time that Cocoon processes a link, it will report the status messages ... + Each time that Cocoon processes a link, it will report the status + messages ...

- + +...]]> +
  • Column 1 is the page build status (*=okay X=brokenLink ^=pageSkipped).
  • Column 2 is the page count (pagesComplete/pagesRemaining). The latter will change because during processing one page, Cocoon will discover more.
    • @@ -787,12 +971,18 @@ 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. -

    If you are using JDK 1.4.0 or newer, you can enable headless operation by - running Forrest with the forrest.jvmarg parameter set to - -Djava.awt.headless=true, like this:

    +

    + If you are using JDK 1.4.0 or newer, you can enable headless + operation by running Forrest with the forrest.jvmarg + parameter set to -Djava.awt.headless=true, like this: +

    forrest -Dforrest.jvmargs=-Djava.awt.headless=true site -

    See also Cocoon FAQ.

    +

    + See also + Cocoon + FAQ. +

    @@ -801,15 +991,16 @@

    - 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 - <project-name> and - <group-name> elements of the skinconf.xml file. - If you have a long project-name then you may need to adjust the width of the image. + 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 + <project-name> and <group-name> + elements of the skinconf.xml 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 - src/documentation/content/xdocs/images/project.svg and adjust the "width" - attribute of the <svg> element. For further details see - SVG resources. + src/documentation/content/xdocs/images/project.svg and + adjust the "width" attribute of the <svg> element. For further + details see SVG + resources.

    @@ -817,8 +1008,11 @@ How do i configure my favourite XML editor or parser to find the local Forrest DTDs? -

    Notes are provided for various tools at Using Catalog Entity - Resolver for local DTDs.

    +

    + Notes are provided for various tools at + Using Catalog Entity Resolver for local + DTDs. +

    @@ -850,67 +1044,97 @@ How to make the site look better and change its skin? -

    There are default skins 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.

    -

    See notes about configuration of the skins. - Some projects may have special needs and can define their own skin.

    +

    + There are default skins 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. +

    +

    + See notes about + configuration of the + skins. Some projects may have special needs and can define their + own skin. +

    How do I enable XSP processing? -

    First consider whether your needs would be better met by Cocoon itself, rather than - Forrest.

    -

    That said, there are valid reasons for wanting programmatically generated content, so - here is how to enable XSP:

    +

    + First consider whether your needs would be better met by Cocoon + itself, rather than Forrest. +

    +

    + That said, there are valid reasons for wanting programmatically + generated content, so here is how to enable XSP: +

    1. Download jdtcore-*.jar 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).
      2. -
    2. -

      Add the following generator definition in the map:generators section of your project sitemap +

    3. + Add the following generator definition in the map:generators + section of your + project + sitemap

      - +]]> -
      4. -
    4. -

      Decide how you want to use XSP. For single files, you could just define a *.xml - matcher:

      - ]]> +
      5. +

    5. + Decide how you want to use XSP. For single files, you could just + define a *.xml matcher: +

      + + ... -]]> -

      You may instead wish to override forrest.xmap to define a general mapping for - XSPs.

      -
      6. +]]> + +

      + You may instead wish to override forrest.xmap to define a general + mapping for XSPs. +

    -

    See also the AddingXSPToForrest Wiki page.

    +

    + See also the + AddingXSPToForrest + Wiki page. +

    How do breadcrumbs work? Why don't they work locally? -

    Breadcrumbs begin with up to three URLs specified in skinconf.xml. Here is - what the Forrest site uses:

    - + Breadcrumbs begin with up to three URLs specified in + skinconf.xml. Here is what the Forrest site uses: +

    + + - ]]> -

    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 skinconf.xml.

    + ]]> + +

    + 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 skinconf.xml. +

    @@ -919,49 +1143,55 @@

    forrest run -Dforrest.jvmargs="-Djetty.port=80"

    -

    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 forrest run +

    + 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 forrest run

    Can I run Forrest with Java debugging turned on? -

    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 -Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,susp end=n - to the forrest.jvmargs property in the forrest.properties - file. Don't forget to ensure the property is uncommented in that file.

    +

    + 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 -Xdebug + -Xrunjdwp:transport=dt_socket,address=8000,server=y,susp end=n + to the forrest.jvmargs property in the + forrest.properties file. Don't forget to ensure the + property is uncommented in that file. +

    How do I enable Cocoon's document checksum feature?

    - 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. -

    -

    - Some tools depend on the "date-last-modified" timestamp of the generated files. - For example, the Forrestbot will then deploy only the modified files. -

    -

    - There was some discussion about this on the Forrest developer mailing - list: - Cocoon Checksum - 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. -

    -

    - Locate the checksums-uri 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: - Cocoon cli.xconf) or use the default - installation-wide cli.xconf file. + 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. +

    +

    + Some tools depend on the "date-last-modified" timestamp of the + generated files. For example, the Forrestbot will then deploy only the + modified files. +

    +

    + There was some discussion about this on the Forrest developer mailing + list: + Cocoon + Checksum 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. +

    +

    + Locate the checksums-uri 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: + Cocoon cli.xconf) or use the default + installation-wide cli.xconf file.

    @@ -971,13 +1201,16 @@ Some of my files are not being processed because they use common filenames. -

    Certain patterns are claimed by the default sitemaps for special processing. These - include: site, changes, todo, faq, images, my-images, skinconf, community, - howto -

    -

    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 (FOR-217). +

    + Certain patterns are claimed by the default sitemaps for special + processing. These include: site, changes, todo, faq, images, + my-images, skinconf, community, howto +

    +

    + 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 + (FOR-217).

    @@ -987,33 +1220,45 @@ What is the relationship between &s; and book.xml? -

    One &s; file in your project root can replace all the book.xml files (one per - directory) in your site. Internally, Forrest uses &s; 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 - &s;-generated menus aren't appropriate. See Menus and - Linking.

    +

    + One &s; file in your project root can replace all the book.xml files + (one per directory) in your site. Internally, Forrest uses &s; 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 &s;-generated menus aren't appropriate. See + Menus and Linking. +

    How do I use DocBook as the XML documentation format? -

    There are two ways. Forrest has a simplifiedDocbook 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.

    -

    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 project - sitemap as explained in Using Forrest 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.

    - +

    + There are two ways. Forrest has a simplifiedDocbook + 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. +

    +

    + 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 + project sitemap as explained + in Using Forrest 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. +

    + + @@ -1025,27 +1270,31 @@ -]]> -

    You need to define the xhtml serializer used in <map:serialize type="xhtml"/> - in the components section of the sitemap. See the - Cocoon - docs for the elements you need to add to define this component. You can see examples - of other components being added in the FORREST_HOME/main/webapp/sitemap.xmap file. - Alternatively use the "html" DocBook stylesheets and the default Cocoon serializer, - i.e. <map:serialize type="html"/> -

    -

    - 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 - (SourceTypeAction) - 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. +]]> + +

    + You need to define the xhtml serializer used in <map:serialize + type="xhtml"/> in the components section of the sitemap. See the + Cocoon + docs for the elements you need to add to define this component. + You can see examples of other components being added in the + FORREST_HOME/main/webapp/sitemap.xmap file. Alternatively + use the "html" DocBook stylesheets and the default Cocoon serializer, + i.e. <map:serialize type="html"/> +

    +

    + 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 + (SourceTypeAction) 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.

    - + + @@ -1080,82 +1329,111 @@ -]]> -

    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.

    -

    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 Using Forrest for - configuration guidance.

    +]]> + +

    + 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. +

    +

    + 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 + Using Forrest for + configuration guidance. +

    How to report which version of Forrest is being used and the properties that are set? -

    Do 'forrest -projecthelp' or './build.sh' to find the version - number.

    -

    To list the properties, add "forrest.echo=true" to your forrest.properties file and - watch the build messages. Doing 'forrest -v' will provide verbose build - messages.

    +

    + Do 'forrest -projecthelp' or './build.sh' to + find the version number. +

    +

    + To list the properties, add "forrest.echo=true" to your + forrest.properties file and watch the build messages. Doing + 'forrest -v' will provide verbose build messages. +

    Where are the log files to find more infomation about errors? -

    The logfiles are at build/webapp/WEB-INF/logs/ +

    + The logfiles are at build/webapp/WEB-INF/logs/

    -

    The log level can be raised with the logkit.xconf configuration. If you are - using Forrest in the interactive webapp mode (which is generally easiest for debugging - errors) then see the main/webapp/WEB-INF/logkit.xconf file. If you are +

    + The log level can be raised with the logkit.xconf + configuration. If you are using Forrest in the interactive webapp mode + (which is generally easiest for debugging errors) then see the + main/webapp/WEB-INF/logkit.xconf file. If you are generating a static site (with command-line 'forrest') then copy - $FORREST_HOME/main/webapp/WEB-INF/logkit.xconf to your project at - src/documentation/conf/logkit.xconf and modify it. See more - information and efficiency tips with Cocoon logging.

    -

    Doing 'forrest -v' will provide verbose build messages to the standard - output.

    + $FORREST_HOME/main/webapp/WEB-INF/logkit.xconf to your + project at src/documentation/conf/logkit.xconf and modify + it. See more information and efficiency tips with + Cocoon + logging. +

    +

    + Doing 'forrest -v' will provide verbose build messages to + the standard output. +

    How to help? -

    Join one of the Forrest project mailing lists 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!

    +

    + Join one of the Forrest project mailing + lists 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! +

    How to contribute a patch? -

    Please send all contributions via our issue tracker. Here - are notes about making patches.

    -

    More info about contributing can be found at the Contributing - to Forrest page. It is always a good idea to check the Forrest issue tracker before diving in.

    +

    + Please send all contributions via our issue + tracker. Here are notes about + making patches. +

    +

    + More info about contributing can be found at the + Contributing to Forrest page. It is + always a good idea to check the Forrest + issue tracker before diving + in. +

    How can job positions be advertised?

    - Employers can send notices about employment opportunities. - There is a special jobs<AT>apache.org mailing list. - You can also send these notices to the project mailing lists, - e.g. dev list at Forrest or Cocoon (add [jobs] to the subject line). - You can also approach particular developers off-list. However only - genuine jobs, not pleas for free support (see - mailing lists). + Employers can send notices about employment opportunities. There is a + special jobs<AT>apache.org mailing list. You can also send these + notices to the project mailing lists, e.g. dev list at Forrest or + Cocoon (add [jobs] to the subject line). You can also approach + particular developers off-list. However only genuine jobs, not pleas + for free support (see mailing + lists).

    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 - (CCLA) - with The Apache Software Foundation. + (CCLA) with The + Apache Software Foundation.