Forrest now has partial support for documentation in JSPWiki format, th= anks to the Chaperon= parser. Wiki is a simple text format that can be learned in minutes. T= his page provides an overview of the syntax that Forrest supports, namely a= subset of that used by the JSPWiki. There is also a <= a class=3D"external" href=3D"http://www.jspwiki.org/Wiki.jsp?page=3DChapero= nTestPage">ChaperonTestPagewhich might provide some more hints (view it= s source).

+ +

Important Note

It is very easy to create broken documents by using this loose wiki syn= tax. Be sure to follow it explicitly.

+ +

Quick reference

+----       =3D Make a horizontal ruler. Extra '-' is ignored.
+\\         =3D force a line break, \\\=3Dforce line break and clear.
+
+[link]     =3D creates a hyperlink to an internal WikiPage called 'Link'.
+[this is also a link] =3D creates a hyperlink to an internal WikiPage call=
ed
+'ThisIsAlsoALink'.
+[click here|link] =3D creates a hyperlink to an internal WikiPage called
+'Link', but displays the text 'click here' to the
+user instead of 'Link'.
+[1]        =3D Makes a reference to a footnote numbered 1.
+[#1]       =3D Marks the footnote number 1.
+[[link]    =3D creates text '[link]'
+
+!heading   =3D small heading with text 'heading'
+!!heading  =3D medium heading with text 'heading'
+!!!heading =3D large heading with text 'heading'
+Note: Be careful with the hierarchy of headings,
+e.g. do not jump from level-3 to level-1.
+
+''text''   =3D prints 'text' in italic.
+__text__   =3D prints 'text' in bold.
+{{text}}   =3D prints 'text' in monospaced font.
+
+* text     =3D makes a bulleted list item with 'text'
+# text     =3D makes a numbered list item with 'text'
+;term:ex   =3D makes a definition for 'term' with the explanation 'ex'
+

+ +

Limitations +

These are the known limitations of the Forrest JSPWiki capability ... <= /p> +

The "definition" syntax (;term:ex) is not supported.
[[link] =3D creates text '[link]' (is not working).

+ +

Samples +

The following sections are samples. View the source to see their use (n= o, not the source of this HTML page, but the actual wiki source from which = this page was generated).

+ +

Writing text

You don't need to know anything about the Wiki text formatting rules to= use Wiki. Just write normal text, and then use an empty line to mark a pa= ragraph. It is just like writing an email. Add more fancy items as you beco= me more comfortable.

+ +

Hyperlinks +

The link can also be a direct URL starting with http:, ftp:, mailto:, h= ttps:, or news:, in which case the link points to an external entity. For e= xample, to point at the java.sun.com home page, use

[http://java.sun.com/]

which becomes http= ://java.sun.com/ +

[Java home page|http://java.sun.com/]

which becomes Java= home page +

Almost any kind of characters can be used inside a

[WikiName]

as long as they are letters or numbers.

+ +

Adding pictures

For security reasons uploading images is not permitted, but you can emb= ed any image in the wiki code by putting the image available somewhere on t= he web in one of the allowed formats, and then just linking to it. For exam= ple, this is an inlined PNG image: 3D"http://forrest.apache.org/s=

If you specify a link text e.g.

[this one here|http://example.com/example.png]

then it becomes the ALT text for those who either can't or don't want t= o view images.

+ +

Bulleted lists +

Use an asterisk (*) in the first column to make bulleted lists. Use mor= e asterisks for deeper indentation. For example:

+* One
+* Two
+* Three
+** Three.One
+

creates

One
Two
Three

Three.One

+ +

Numbered lists +

Just like with bulleted lists, but use a hash (#) instead of the asteri= sk. Like this:

+# One
+# Two
+# Three
+## Three.One
+

creates

One
Two
Three

Three.One

If you want to write the list item on multiple lines, just add one or m= ore spaces on the next line and the line will be automatically added to the= previous item. If this sounds complicated, edit this page for an example,= below.

This is a single-line item.
This is actually a multi-line item. We continue the second sentence on= a line on a line of its own. We might as well do a third line while we're = at it... Notice, however, as all these sentences get rendered inside a sing= le item!
The third line is again a single-line item.

+ +

Definition lists and comments

A simple way to make definition lists is to use the ';:' -construct: +

; Construct : Something you use to do something wi= th=20 +

Another nice use for the ';:' is that you can use it to comment shortly= on other people's text, by having an empty 'term' in the definition, like = this:

+;:''Comment here.''
+

Which would be seen as ;: Comment here.=20 +

+ +

Text effects

You may use bold text or italic text, by us= ing two underscores (_) and two single quotes ('), respectively. If you're = on a Windows computer, make sure that you are using the correct quote sign,= as there is one that looks the same, but really isn't.

+ +

Preformatted text

If you want to add preformatted text (like code) just use three consecu= tive braces ({) to open a block, and three consecutive braces (}) to close = a block. See the Tables example below.

+ +

Tables

You can do simple tables by using using pipe symbols ('|'). Use double= pipe symbols to start the heading of a table, and single pipe symbols to t= hen write the rows of the table. End with a line that is not a table.

For example:

+|| Heading 1 || Heading 2
+| ''Italic Text'' | Plain Text
+| [Forrest Home Page|http://forrest.apache.org/] | [http://forrest.apache.=
org/]
+

renders the following table. Note how you can use links also inside ta= bles.

+ + + + + + + + + + +

Heading 1	Heading 2
Italic Text	Plain Text
Forrest Home Page	<= a href=3D"http://forrest.apache.org/">http://forrest.apache.org/

+ +

+Core | <= a class=3D"base-selected" href=3D"../docs/forrestbot.html">ForrestBot |= ForrestBar +

+ + +

+ +

+ =20 + +

+ + +

Documentation

+Index +

Using Forrest

+XML Validation +

+Menus and Linking +

+Searching +

+Default Skins +

+Skin Packages +

+Our Contract +

+Standards Compliance +

Advanced Topics

+Using DTD Catalogs +

+Project sitemap +

Upgrading

SubProjects

+ForrestBar +

+Forrestbot +

+Forrestbot We= bapp +

Reference docs

DTD documentation

+Overview +

+document-v20 +

+howto-v20 +

+faq-v20 +

+document-v13 +

+howto-v13 +

+faq-v13 +

Doc samples

+document-v13 +

+document-v20 +

+JSPWiki Reference +

+OpenOffice.Org Writer +

Older Docs

+Forrest Primer +

+Libre +

+Dream list +

+ This is documentation for past release v0.6 + (More ...)

+ +

+ + +

+ PDF +

+ Font size:=20 + = =20 + + +

Using Forrest

A tutorial on how to use Forrest in your own projects

+ This is documentation for past release v0.6 + (More ...)

+Introduction +
+Installing Forrest +
+Seeding a new project +
+Seeding an existing project +
+Customizing your project +
- +Configuring the Forrest skin: skinconf.xml +
- +Changing the layout: forrest.properties +
+

+Adding content +
- +site.xml +
- +tabs.xml +
- +Images +
+
+Advanced customizations: sitemap.xmap +
- +Example: Adding a new content type +
  - +Registering a new DTD +
  +
- +Example: Adding a new content type = (advanced) +
- +Example: integrating external RSS content +
+
+Forrest skins +
- +Configuration of skins +
- +Defining a new skin +
+
+Interactive Forrest: faster turnaround when developing= your docs +
- +Running as a webapp +
  - +Using the webapp +
  +
+
+Invoking Forrest from Ant +

+ =20 + +

Introduction

+ This tutorial will lead you through the process of installing Forr= est, and using + it to create a new project, or add Forrest-based docs to an existi= ng project. +

+ + =20 + +

Installing Forrest

+ =20 +Download the latest = release + of Forrest, or + if you want to try the development version, + build Forrest from source. +

+ After downloading and extracting forrest, you need to add environment= variables. +

In Unix/Linux:

+~/apache-forrest-0.6$ export FORREST_HOME=3D`pwd`/src/core
+~/apache-forrest-0.6$ export PATH=3D$PATH:$FORREST_HOME/bin
+

In Windows:

+Go to "My Computer", "Properties", "Advanced", "Environment Variables"
+and add:
+FORREST_HOME as C=
:\full\path\to\apache-forrest-0.6\src\core
+PATH as %PATH%;%F=
ORREST_HOME%\bin
+    =20
+

+ To see what the 'forrest' command can do, type 'forrest -projecthel= p'. + The build targets that are marked with * are the commonly used ones. +

+Apache Forrest.  Run 'forrest -projecthelp' to list options
+
+Buildfile: /usr/local/svn/forrest/src/core/bin/../forrest.build.xml
+
+    *=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D*
+    |                 Forrest Site Builder                  |
+    |                        0.6-dev                        |
+    *=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D*
+ =20
+             Call this through the 'forrest' command
+ =20
+Main targets:
+
+ available-skins       What skins are available?
+ clean                 * Clean all directories and files generated during
+                        the build
+ install-skin          Install the needed skin from the remote repository
+ package-skin          Make a package of an existing skin
+ run                   * Run Jetty (instant live webapp)
+ run_custom_jetty      Run Jetty with configuration file found in the proj=
ect
+ run_default_jetty     Run Jetty with configuration file found in Forrest
+ seed                  * Seeds a directory with a template project doc str=
ucture
+ site                  * Generates a static HTML website for this project
+ validate              Validate all: xdocs, skins, sitemap, etc
+ validate-sitemap      Validate the project sitemaps
+ validate-skinchoice   Validate skin choice
+ validate-skinconf     Validate skinconf
+ validate-skins        Validate skins
+ validate-stylesheets  Validate XSL files
+ validate-xdocs        Validate the project xdocs
+ war                   * Generates a dynamic servlet-based website
+                         (a packaged .war file)
+ webapp                Generates a dynamic servlet-based website
+                         (an unpackaged webapp).
+ webapp-local          Generates a dynamic servlet-based website
+                         (an unpackaged webapp). Note this webapp is suita=
ble
+                         for local execution only, use the 'war' or 'webap=
p'
+                         target if you wish to deploy remotely.
+Default target: site
+

+ As 'site' is the default target, just running 'forrest' without op= tions will + generate a "static HTML website". For example, typing 'forrest' in= the + top-level "forrest" directory would build Forrest's own website. + But we're going to be building a new site for your project, so read= on. +

+ + =20 + +

Seeding a new project

+ 'Seeding' a project is our own arborial term for adding a template + documentation set to your project, which you can then customize. +

+ To try this out, create a completely new directory, change directo= ry + to it, and do 'forrest seed': +

+[/home/me/forrest/my-test]$ forrest seed
+
+Apache Forrest.  Run 'forrest -projecthelp' to list options
+
+Buildfile: /usr/local/svn/forrest/src/core/bin/../forrest.build.xml
+
+init-props:
+Loading project specific properties from
+ /home/me/forrest/my-test/forrest.properties
+=2E..
+echo-settings:
+
+check-contentdir:
+
+ensure-nocontent:
+
+seed:
+Copying 41 files to /home/me/forrest/my-test
+
+-------------------------------
+~~ Template project created! ~~
+
+Here is an outline of the generated files:
+
+/                        # /home/me/forrest/my-test
+/status.xml              # List of project developers, todo list and chang=
e log
+/forrest.properties      # Optional file describing your site layout
+/src/documentation/      # Doc-specific files
+/src/documentation/skinconf.xml    # Info about your project used by the s=
kin
+/src/documentation/content/        # Site content.
+/src/documentation/content/xdocs   # XML content.
+/src/documentation/content/xdocs/index.xml # Home page
+/src/documentation/content/xdocs/site.xml  # Navigation file for site stru=
cture
+/src/documentation/content/xdocs/tabs.xml  # Skin-specific 'tabs' file.
+/src/documentation/content/*.html,pdf # Static content files, may have sub=
dirs
+/src/documentation/resources/images   # Project images (logos, etc)
+# you can create other directories as needed (see forrest.properties)
+
+
+What to do now?
+
+- Render this template to static HTML by typing 'forrest'.
+  View the generated HTML in a browser to make sure everything works.
+- Alternatively 'forrest run' and browse to http://localhost:8888/ live de=
mo.
+- Edit status.xml and src/documentation/skinconf.xml
+  to customize for your project.
+- Start adding content in xdocs/ remembering to declare new files in site.=
xml
+- Follow the document http://forrest.apache.org/docs/your-project.html
+- Provide any feedback to dev@forrest.apache.org
+
+Thanks for using Apache Forrest
+-------------------------------
+
+BUILD SUCCESSFUL
+Total time: 5 seconds
+

Note

+ As you have probably noticed, we like to document things right in = the + script, on the theory that people only read online docs when despe= rate :) +

+ You now have a template documentation structure all set up: +

+[/home/me/forrest/my-test]$ tree
+=2E
+|-- build
+|   `-- tmp
+|       `-- projfilters.properties
+|-- forrest.properties
+|-- src
+|   `-- documentation
+|       |-- README.txt
+|       |-- classes
+|       |   `-- CatalogManager.properties
+|       |-- content
+|       |   |-- hello.pdf
+|       |   |-- test1.html
+|       |   |-- test2.html
+|       |   `-- xdocs
+|       |       |-- images
+|       |       |   |-- group-logo.gif
+|       |       |   |-- group.svg
+|       |       |   |-- icon.png
+|       |       |   |-- project-logo.gif
+|       |       |   `-- project.svg
+|       |       |-- index.xml
+|       |       |-- samples
+|       |       |   |-- ascii-art.xml
+|       |       |   |-- cocoon-pyramid.aart
+|       |       |   |-- faq.xml
+|       |       |   |-- ihtml-sample.ihtml
+|       |       |   |-- index.xml
+|       |       |   |-- openoffice-writer.sxw
+|       |       |   |-- sample.xml
+|       |       |   |-- sample2.xml
+|       |       |   |-- sdocbook.xml
+|       |       |   |-- subdir
+|       |       |   |   |-- book-sample.xml
+|       |       |   |   `-- index.xml
+|       |       |   `-- wiki-sample.cwiki
+|       |       |-- site.xml
+|       |       `-- tabs.xml
+|       |-- skinconf.xml
+|       `-- translations
+|           |-- langcode.xml
+|           |-- languages_en.xml
+|           |-- languages_es.xml
+|           |-- menu.xml
+|           |-- menu_af.xml
+|           |-- menu_de.xml
+|           |-- menu_es.xml
+|           |-- menu_it.xml
+|           |-- menu_no.xml
+|           |-- menu_ru.xml
+|           |-- menu_sk.xml
+|           |-- tabs.xml
+|           `-- tabs_es.xml
+|-- status.xml
+

+ To render this to HTML, type 'forrest'. You should have a HTML sit= e rendered + into the build/site directory: +

+ Practise with adding new content. Change to the directory + src/documentation/content/xdocs an= d copy the file + index.xml to create my-new-file.xml as a + new document. Edit it to change some text. Add an entry to=20 + site.xml by copying one of the oth= er entries and + changing it to suit. Now do 'forrest' to see the result. +

+ =20 + +

Seeding an existing project

+ In the section above, we have run 'forrest seed' in an empty direc= tory + to create a new project. If you have an existing codebase to which= you + want to add Forrest docs, then run 'forrest seed' in your project = base + directory, and the Forrest doc structure will be grafted onto your + project. This procedure only needs to be done once. +

+ If your project already has XML documentation, it may be easier to= tell + Forrest where the XML sources are, rather than rearrange your proj= ect + directories to accommodate Forrest. This can be done by editing + forrest.properties (consult + the Changing the layout + section for more details). +

+ =20 + +

Customizing your project

+ Having seeded a project with template docs, you will now want to c= ustomize it + to your project's needs. Here we will deal with configuring the sk= in, and + changing the project layout. +

+ +

Configuring the Forrest skin: skinconf.xml

+ Most Forrest skins can be customized through a single XML file, + src/documentation/skinconf.xml, = which looks like this: +

+<!--
+Skin configuration file. This file contains details of your project,
+which will be used to configure the chosen Forrest skin.
+-->
+
+ <!DOCTYPE skinconfig PUBLIC
+        "-//APACHE//DTD Skin Configuration V0.6-2//EN"
+        "skinconfig-v06-2.dtd">
+
+<skinconfig>
+  <!-- To enable lucene search add provider=3D"lucene"
+    Add box-location=3D"alt" to move the search box to an alternate locati=
on
+    (if the skin supports it) and box-location=3D"all" to show it in all
+    available locations on the page.  Remove the <search> element to=
 show
+    no search box.
+  -->
+  <search name=3D"MyProject" domain=3D"mydomain"/>
+
+  <!-- Disable the print link? If enabled, invalid HTML 4.0.1 -->
+  <disable-print-link>true</disable-print-link> =20
+  <!-- Disable the PDF link? -->
+  <disable-pdf-link>false</disable-pdf-link>
+  <!-- Disable the xml source link? -->
+  <!-- The xml source link makes it possible to access the xml rendition
+    of the source frim the html page, and to have it generated statically.
+    This can be used to enable other sites and services to reuse the
+    xml format for their uses. Keep this disabled if you don't want other
+    sites to easily reuse your pages.-->
+  <disable-xml-link>true</disable-xml-link>
+ =20
+  <!-- Disable navigation icons on all external links? -->
+  <disable-external-link-image>false</disable-external-link-image=
>
+ =20
+  <!-- Disable w3c compliance links? -->
+  <disable-compliance-links>false</disable-compliance-links>
+  <!-- Render mailto: links unrecognisable by spam harvesters? -->
+  <obfuscate-mail-links>true</obfuscate-mail-links>
+
+  <!-- mandatory project logo
+       skin: forrest-site renders it at the top -->
+  <project-name>MyProject</project-name>
+  <project-description>MyProject Description</project-description=
>
+  <project-url>http://myproj.mygroup.org/</project-url>
+  <project-logo>images/project.png</project-logo>
+  <!-- Alternative static image:
+  <project-logo>images/project-logo.gif</project-logo> -->
+
+  <!-- optional group logo
+       skin: forrest-site renders it at the top-left corner -->
+  <group-name>MyGroup</group-name>
+  <group-description>MyGroup Description</group-description>
+  <group-url>http://mygroup.org</group-url>
+  <group-logo>images/group.png</group-logo>
+  <!-- Alternative static image:
+  <group-logo>images/group-logo.gif</group-logo> -->
+
+  <!-- optional host logo (e.g. sourceforge logo)
+       skin: forrest-site renders it at the bottom-left corner -->
+  <host-url></host-url>
+  <host-logo></host-logo>
+ =20
+  <!-- relative url of a favicon file, normally favicon.ico -->
+  <favicon-url></favicon-url>
+
+  <!-- The following are used to construct a copyright statement -->
+  <year>2004</year>
+  <vendor>The Acme Software Foundation.</vendor>
+  <!-- The optional copyright-link URL will used as a link in the
+    copyright statement
+  <copyright-link>http://www.apache.org/licenses/</copyright-link=
>
+  -->
+
+  <!-- Some skins use this to form a 'breadcrumb trail' of links.
+    If you don't want these, then set the attributes to blank.
+    The DTD purposefully requires them.
+    Use location=3D"alt" to move the trail to an alternate location
+    (if the skin supports it).
+  -->
+  <trail>
+    <link1 name=3D"myGroup" href=3D"http://www.apache.org/"/>
+    <link2 name=3D"myProject" href=3D"http://forrest.apache.org/"/>
+    <link3 name=3D"" href=3D""/>
+  </trail>
+
+  <!-- Configure the TOC, i.e. the Table of Contents.
+  @max-depth
+   how many "section" levels need to be included in the
+   generated Table of Contents (TOC).=20
+  @min-sections
+   Minimum required to create a TOC.
+  @location ("page","menu","page,menu")
+   Where to show the TOC.
+  -->
+  <toc max-depth=3D"2" min-sections=3D"1" location=3D"page"/>
+
+  <!-- Heading types can be clean|underlined|boxed  -->
+  <headings type=3D"boxed"/>
+
+  <extra-css>
+    <!-- A sample to show how the class attribute can be used -->
+    p.quote {
+      margin-left: 2em;
+      padding: .5em;
+      background-color: #f0f0f0;
+      font-family: monospace;
+    }
+  </extra-css>
+
+  <colors>
+  <!-- CSS coloring examples omitted for brevity -->
+  </colors>
+=20
+  <!-- Settings specific to PDF output.  -->
+  <pdf>
+    <!--=20
+       Supported page sizes are a0, a1, a2, a3, a4, a5, executive,
+       folio, legal, ledger, letter, quarto, tabloid (default letter).
+       Supported page orientations are portrait, landscape (default
+       portrait).
+       Supported text alignments are left, right, justify (default left).
+    -->
+    <page size=3D"letter" orientation=3D"portrait" text-align=3D"left"/=
>
+
+    <!--
+       Margins can be specified for top, bottom, inner, and outer
+       edges. If double-sided=3D"false", the inner edge is always left
+       and the outer is always right. If double-sided=3D"true", the
+       inner edge will be left on odd pages, right on even pages,
+       the outer edge vice versa.
+       Specified below are the default settings.
+    -->
+    <margins double-sided=3D"false">
+      <top>1in</top>
+      <bottom>1in</bottom>
+      <inner>1.25in</inner>
+      <outer>1in</outer>
+    </margins>
+
+    <!--
+      Print the URL text next to all links going outside the file
+    -->
+    <show-external-urls>false</show-external-urls>
+  </pdf>
+
+  <!-- Credits are typically rendered as a set of small clickable
+    images in the page footer -->
+  <credits>
+    <credit>
+      <name>Built with Apache Forrest</name>
+      <url>http://forrest.apache.org/</url>
+      <image>images/built-with-forrest-button.png</image>
+      <width>88</width>
+      <height>31</height>
+    </credit>
+    <!-- A credit with @role=3D'pdf' will have its name and url
+      displayed in the PDF page's footer. -->
+  </credits>
+
+</skinconfig>
+

+ Customise this file for your project. The images/ directory + mentioned in 'project-logo' and 'group-logo' elements correspond= s to the + src/documentation/resources/images directory + (this mapping is done automatically by the sitemap). +

+ Having edited this file (and ensured it is valid XML), re-run th= e 'forrest' + command in the site root, and the site would be updated. +

+ +

Changing the layout: forrest.properties

+ Forrest allows you to place files anywhere you want in your + project, so long as you tell Forrest where you have placed the + major file types. +

+ The forrest.properties file maps= from your directory + layout to Forrest's. If you generated your site with 'forrest se= ed', you + will have one pre-written, with all the entries commented out. +

Note

+ You only need to un-comment entries if you are going to change th= em + to something different. + If you keep in synchronisation with the 'forrest seed' defaults, + then it is easy to diff each time that you update. +

+ The main entries (with default values) are: +

+# Properties that must be set to override the default locations
+#
+# Parent properties must be set. This usually means uncommenting
+# project.content-dir if any other property using it is uncommented
+
+#project.status=3Dstatus.xml
+#project.content-dir=3Dsrc/documentation
+#project.conf-dir=3D${project.content-dir}/conf
+#project.sitemap-dir=3D${project.content-dir}
+#project.xdocs-dir=3D${project.content-dir}/content/xdocs
+#project.resources-dir=3D${project.content-dir}/resources
+#project.stylesheets-dir=3D${project.resources-dir}/stylesheets
+#project.images-dir=3D${project.resources-dir}/images
+#project.schema-dir=3D${project.resources-dir}/schema
+#project.skins-dir=3D${project.content-dir}/skins
+#project.skinconf=3D${project.content-dir}/skinconf.xml
+#project.lib-dir=3D${project.content-dir}/lib
+#project.classes-dir=3D${project.content-dir}/classes
+

+ For example, if you wish to keep XML documentation in src/xdocs r= ather than + src/documentation/content/xdocs s= imply change the + definition for project.xdocs-dir +

project.xdocs-dir=3Dsrc/xdocs

+ For example, to emulate the simple=20 + Maven= format: +

+ /xdocs + /xdocs/images + /xdocs/stylesheets +

Here are the required property definitions:

+project.content-dir=3Dxdocs
+project.sitemap-dir=3D${project.content-dir}
+project.xdocs-dir=3D${project.content-dir}
+project.stylesheets-dir=3D${project.content-dir}/stylesheets
+project.images-dir=3D${project.content-dir}/images
+project.skinconf=3D${project.content-dir}/skinconf.xml
+

Note

+ Internally, Forrest rearranges the specified directory into the= default + src/documentation/content/xdocs= structure. In the layout above, we have + overlapping directories, so you will end up with duplicate file= s=2E This small + glitch doesn't usually cause problems; just always remember tha= t all links + are resolved through the sitemap. +

+ + =20 + +

Adding content

+ Now you can start adding content of your own, in + src/documentation/content/xdocs + =20 +

+ +

site.xml

+ When adding a new xml document, you would add an entry to the pr= oject's + site.xml file. This site.xml is = like a site index, and is rendered as + the vertical column of links in the default skin. Look at Forre= st's own + xdocs for an example. More detailed info about site.xml is prov= ided in=20 + the document Menus and Linking<= /a>. +

+ +

tabs.xml

+ The tabs.xml file is used to pro= duce the 'tabs'. + which enable users to quickly jump to sections of your site. + See the + menu generation= documentation + for more details, and again, consult Forrest's own docs for a us= age + example. +

You can have one or two levels of tabs. The images above show a=20 + single level. However, you can create a second level that + will only be displayed when its parent tab is selected. For exampl= e, + the tabs.xml snippet below will di= splay either one or + two rows of tabs, depending on which of the top level tabs is sele= cted. + The first row will have two tabs: one labelled How-Tos + and the other labelled Apache XML Project= s. When the=20 + How-Tos tab is selected there will + be no second row of tabs. However, when the Apache XML + Projects tab is selected, a second row of tabs will be disp= layed + below the first.

+  <tab label=3D"How-Tos" dir=3D"community/howto/"/>
+  <tab label=3D"Apache XML Projects" href=3D"http://xml.apache.org">
+    <tab label=3D"Forrest" href=3D"http://forrest.apache.org/"/>
+    <tab label=3D"Xerces" href=3D"http://xml.apache.org/xerces"/>
+  </tab>
+

+ +

Images

+ Images usually go in src/documentation/= resources/images/ + The default sitemap + maps this directory to images/, = so image tags will typically look + like <figure src=3D"images/project-logo.png" alt=3D"Project L= ogo"/>=20 +

+ + =20 + +

Advanced customizations: sitemap.xmap

+ The Cocoon sitemap is a set of rules for generating content (HTML,= PDFs etc) + from XML sources. Forrest has a default sitemap, which is adequate= for + everyday sites. For example, the + Forrest website itself uses the + default sitemap. +

+ Sometimes, one needs to go beyond the default set of rules. This i= s where + Forrest really shines, because its Cocoon backend allows virtually= any + processing pipeline to be defined. For example, one can: +

Transform custom XML content types with XSLT stylesheets.
Generate PNG or JPEG images from=20 + SVG X= ML files. + (Note: Forrest's sitemap now does this natively= .)
Integrate external XML feeds (e.g. RSS) into your site's content. + (Note: See issues.xmap for an example.)
Merge XML sources via aggregation, or make content from large XML + sources available as "virtual" files. + (Note: Forrest makes extensive use of aggregati= on + in the default sitemaps. It also defines a whole-site HTML + and PDF, available as the standard names wholesite.html + and wholesite.pdf.)
Read content from exotic sources like + XML + databases.
Integrate any of Cocoon's vast array + of capabilities. The possibilities are best appreciated by + downloading the latest Cocoon distribution and playing with the + samples.

+ The Forrest sitemaps are at + forrest/src/core/context/*.xmap + =20 +

+ You can add pre-processing sitemaps to your project + src/documentation directory (or wh= erever + ${project.sitemap-dir} points to).= Any match that + is not handled, passes through to be handled by the default Forrest + sitemaps - obviously extremely powerful. The capability is describ= ed + in=20 + "Using project sitemaps" + and some worked examples are shown in the following sections here. +

Note

+ We advise you to spend time to understand the Apache Cocoon sitema= p=2E + See Cocoon sitemap + and Cocoon concepts + and related component documentation. + The Forrest sitemap is broken into multiple files. The main one is + sitemap.xmap which delegates to others. See the + Sitemap Reference for a = tour of the + default sitemap. +

+ +

Example: Adding a new content type

+ Follow this worked example. In a fresh directory do 'forrest see= d' + then follow the steps described in this section. +

+ An example scenario is that we have a specialised list of downlo= ads + for a certain software package. It would be best to represent the + download information in a custom XML format. This means that it + will have its own document type declaration. We will need + to detect this new document type via our project sitemap + and also provide a mapping to a local copy of this DTD. +

<?xml version=3D"1.0" encoding=3D"utf-8"?>
+<!DOCTYPE document PUBLIC "-//Acme//DTD Download Documentation V1.0//EN"
+  "dtd/download-v10.dtd">
+<document>=20
+  <header>
+    <title>Downloading Binaries</title>
+  </header>
+  <body>
+    <section id=3D"download">
+      <title>Downloading binaries</title>
+      <p>
+        Here are the binaries for FooProject
+      </p>
+      <release version=3D"0.9.13" date=3D"2002-10-11">
+        <downloads>
+          <file
+            url=3D"http://prdownloads.sf.net/aft/fooproj-0.9.13-bin.zip?do=
wnload"
+            name=3D"fooproj-0.9.13-bin.zip"
+            size=3D"5738322"/>
+          <file
+            url=3D"http://prdownloads.sf.net/aft/fooproj-0.9.13-src.zip?do=
wnload"
+            name=3D"fooproj-0.9.13-src.zip"
+            size=3D"10239777"/>
+        </downloads>
+      </release>
+      <release version=3D"0.9.12" date=3D"2002-10-08">
+        <downloads>
+          <file
+            url=3D"http://prdownloads.sf.net/aft/fooproj-0.9.12-src.zip?do=
wnload"
+            name=3D"fooproj-0.9.12-src.zip"
+            size=3D"10022737"/>
+         </downloads>
+       </release>
+    </section>
+    <section id=3D"cvs">
+      <title>Getting FooProject from CVS</title>
+      <p>....</p>
+    </section>
+  </body>
+</document>

This file called "download.xml" would b= e placed in + your content directory (typically + src/documentation/content/xdocs)= and an entry added to + site.xml +

+ To handle these special tags, one would write a stylesheet to co= nvert + them to the intermediate Forrest xdocs structure. Here is such a= stylesheet, + called "download2document.xsl" .= .=2E +

<?xml version=3D"1.0" encoding=3D"utf-8"?>
+<xsl:stylesheet
+  version=3D"1.0"
+  xmlns:xsl=3D"http://www.w3.org/1999/XSL/Transform">
+
+  <xsl:template match=3D"release">
+    <section id=3D"{@version}">
+      <title>Version <xsl:value-of select=3D"@version"/> (rele=
ased
+          <xsl:value-of select=3D"@date"/>)</title>
+      <table>
+        <tr><th>File</th><th>Size</th></t=
r>
+        <xsl:apply-templates select=3D"downloads/*"/>
+      </table>
+    </section>
+  </xsl:template>
+
+  <xsl:template match=3D"file">
+    <tr>
+      <td><link href=3D"{@url}"><xsl:value-of select=3D"@na=
me"/></link></td>
+      <td><xsl:value-of
+           select=3D"format-number(@size div (1024*1024), '##.##')"/> M=
B</td>
+    </tr>
+  </xsl:template>
+
+  <xsl:template match=3D"@* | node() | comment()">
+    <xsl:copy>
+      <xsl:apply-templates select=3D"@*"/>
+      <xsl:apply-templates/>
+    </xsl:copy>
+  </xsl:template>
+
+</xsl:stylesheet>
+

+ Place this file in the default stylesheets directory, + src/documentation/resources/styleshee= ts (or wherever + ${project.stylesheets-dir} points). +

+ Now we will create a project sitemap to control the + transformation of our custom xml + structure into the Forrest intermediate xdocs structure. +

Note

+ The Sitemap + Reference provides details about how the sitemap works. +

+ Add the following as the file + src/documentation/sitemap.xmap= =2E.. +

<?xml version=3D"1.0"?>
+<map:sitemap xmlns:map=3D"http://apache.org/cocoon/sitemap/1.0">
+ <map:pipelines>
+  <map:pipeline>
+   <map:match pattern=3D"**download.xml">
+    <map:generate src=3D"{project:content.xdocs}{1}download.xml" />
+    <map:transform src=3D"{project:resources.stylesheets}/download2docu=
ment.xsl" />
+    <map:serialize type=3D"xml"/>
+   </map:match>
+  </map:pipeline>
+ </map:pipelines>
+</map:sitemap>
+

+ That will intercept the request for the body content, for only + this specific "download" document, and will transform it into = the + intermediate Forrest "document" format. The normal Forrest mac= hinery + will handle the aggregation with navigation menus etc. and will + apply the normal skin. +

+ +

Registering a new DTD

+ By default, Forrest requires that all XML files be valid,= i.e. + they must have a DOCTYPE declaration and associated DTD, = and + validate against it. Our new 'downloads' document type i= s no + exception. The XML + Validation document continues this example, showing= how + to register a new document type. Briefly, this involves: +

Create a new DTD or (in our case) extend an existing + one.
Place the new DTD in the + ${project.schema-dir}/dtd directory.
Add an XML Catalog to enable a mapping from the + DOCTYPE public id to the relevant DTD file.
Tell the system about your catalog.

Note

+ Please see XML Valida= tion + for the complete description for those steps. +

+ +

Example: Adding a new content type (advanced) +

+ The simple user sitemap in the previous example is fine for + simple situations. For a complete solution to the "Download = DTD" + issue we need a more advanced sitemap which will do different + processing depending on the version of the document type + declaration. Let us show the sitemap and then explain it. +

<?xml version=3D"1.0"?>
+<map:sitemap xmlns:map=3D"http://apache.org/cocoon/sitemap/1.0">
+
+ <map:components>
+  <map:selectors default=3D"parameter">
+   <map:selector logger=3D"sitemap.selector.parameter"
+       name=3D"parameter" src=3D"org.apache.cocoon.selection.ParameterSele=
ctor" />
+  </map:selectors>
+  <map:actions>
+   <map:action logger=3D"sitemap.action.sourcetype" name=3D"sourcetype"
+       src=3D"org.apache.cocoon.acting.sourcetype.SourceTypeAction">
+    <sourcetype name=3D"download-v1.0">
+     <document-declaration
+        public-id=3D"-//Acme//DTD Download Documentation V1.0//EN" />
+    </sourcetype>     =20
+    <sourcetype name=3D"download-v1.1">
+     <document-declaration
+        public-id=3D"-//Acme//DTD Download Documentation V1.1//EN" />
+    </sourcetype>     =20
+   </map:action>
+  </map:actions>
+ </map:components>
+
+ <map:pipelines>
+  <map:pipeline>
+   <map:match pattern=3D"**download.xml">
+    <map:generate src=3D"{project:content.xdocs}{1}download.xml" />
+    <map:act type=3D"sourcetype" src=3D"{project:content.xdocs}{1}downl=
oad.xml">
+     <map:select type=3D"parameter">
+      <map:parameter name=3D"parameter-selector-test" value=3D"{sourcet=
ype}" />
+      <map:when test=3D"download-v1.0">
+       <map:transform
+          src=3D"{project:resources.stylesheets}/download2document.xsl" /&=
gt;
+      </map:when>
+      <map:when test=3D"download-v1.1">
+       <map:transform
+          src=3D"{project:resources.stylesheets}/download-v11-2document.xs=
l" />
+      </map:when>
+     </map:select>
+    </map:act>
+    <map:serialize type=3D"xml"/>
+   </map:match>
+  </map:pipeline>
+ </map:pipelines>
+</map:sitemap>
+

+ This is the type of processing that happens in the main + src/core/context/forrest.xmap sitemap. We have + added similar handling to our project sitemap. Basically, th= is + uses the SourceTypeAction (cont= ent aware pipelines) + to detect the doctype. The new document-v11.dtd needs to be = also + added to your project Catalog. +

+ Note that any sitemap component must be declared before it + can be used, because the project sitemap is the first sitemap + to be consulted. +

+ +

Example: integrating external RSS content

Similar to the previous example, we can integrate RSS into our + site simply by providing a match in our project sitemap.xmap= =2E.. +

<?xml version=3D"1.0"?>
+<map:sitemap xmlns:map=3D"http://apache.org/cocoon/sitemap/1.0">
+ <map:pipelines>
+  <map:pipeline>
+  
+   <map:match pattern=3D"**weblog.xml">
+    <map:generate src=3D"http://blogs.cocoondev.org/stevenn/index.rss"/=
>
+    <map:transform src=3D"{forrest:stylesheets}/rss2document.xsl"/>
+    <map:serialize type=3D"xml"/>
+   </map:match>
+
+   <map:match pattern=3D".......">
+    <!-- handle other project-specific matches -->
+   </map:match>
+  </map:pipeline>
+ </map:pipelines>
+</map:sitemap>
+

You will probably want to copy the core Forrest=20 + rss2document.xsl to your pro= ject, + customise it to your needs, and refer to it with + src=3D"{project:resources.styleshee= ts}/rss2document.xsl". + Then of course you would add an entry to site.xml to link + to weblog.html +

+ + =20 + +

Forrest skins

+ As Forrest separates content from presentation, we can plug in d= ifferent + "skins" to instantly change a site's look and feel. Forrest pro= vides one + primary skin, pelt, and some oth= ers in various + states of development. + To change the skin, edit the forrest.pr= operties file + to set project.skin=3Dleather-dev or some other skin name. +

Note

+ Forrest supplies a collection of=20 + default skins which are confi= gurable + and so should meet the needs of most projects. The aim is to pro= vide + many capabilities so that extra skins are not needed. +

+ +

Configuration of skins

+ All configuration is done via your project + src/documentation/skinconf.xml f= ile. + It contains many comments to describe each capability. + Please read those, there is no point repeating here. +

+ +

Defining a new skin

Consider discussing your needs on the mailing lists. There may + be planned enhancements to the core skins. Also consider contrib= uting + your extensions to the core skins, rather than write your own sk= in. + Bear in mind that you could be creating an update and management + issue. Anyway, ... +

+ Projects can define their own skin in the + src/documentation/skins direct= ory (or wherever + ${project.skins-dir} points). = The default sitemap assumes a + certain skin layout, so the easiest way to create a new skin i= s by + copying an existing Forrest skin. For example, copy + forrest/src/core/context/skins/pelt + to your project area at + src/documentation/skins/my-fancy-skin= and add + project.skin=3Dmy-fancy-skin t= o forrest.properties +

+ The two most interesting XSLT stylesheets involved are: +

+xslt/html/document2html.xsl +: + This stylesheet is applied to individual Forrest xdocs XML f= iles, and + converts them to HTML suitable for embedding in a larger HTM= L page. +
+xslt/html/site2xhtml.xsl +: + This stylesheet generates the final HTML file from an interm= ediate + 'site' structure produced by the other stylesheets. It defin= es the general + layout, and adds the header and footer. +

+ Typically there is a lot of commonality between skins. XSLT + provides an 'import' mechanism whereby one XSLT can extend ano= ther. + Forrest XSLTs typically 'import' from a common base: +

+<xsl:stylesheet version=3D"1.0" xmlns:xsl=3D"http://www.w3.org/1999/XSL=
/Transform">
+
+  <xsl:import href=3D"../../../common/xslt/html/document2html.xsl"/>
+
+  ... overrides of default templates ...=20
+</xsl:stylesheet>

In order to use this feature in your custom skins you must copy + the common skin from the forrest distribution into your custom s= kins=20 + directory (from forrest/src/core/contex= t/skins/common). + This will protect your skin from changes in the Forrest common s= kin, + but you must remember to update this skin in order to take advan= tage + of new features added over time by the Forrest team.

This is particularly relevant for menu rendering (book2menu.xsl), + where the common stylesheet does the 'logic' of which item is + selected, and over-riding stylesheets define the presentation.=

+ + =20 + +

Interactive Forrest: faster turnaround when de= veloping your docs

+ In comparison to simpler tools (like=20 + Anakia) the Cocoon command-line mode + (and hence Forrest command-line mode) is slow. + As the dream list notes, Forre= st was + originally intended to be used for + dynamic sites, and the Cocoon crawler used only to create static + snapshots for mirroring. This section describes how, by using + a "live" Forrest webapp instance, the Forrest-based documentation + development can be faster and easier than with comparable tools. +

+ +

Running as a webapp

+ Type 'forrest run' in your proje= ct root to start Forrest's + built-in Jetty web server. Once it has started, point your brow= ser at + http://loc= alhost:8888/, which + will show your website, rendered on demand as each link is follo= wed. +

(Alternatively, if you wish to run Forrest from within an existing + servlet container, type forrest webapp<= /span> to build an open + webapp in build/webapp/) +

+ +

Using the webapp

+ You can now edit the XML content in + build/webapp/content/xdocs and= see the changes + immediately in the browser. +

+ =20 + +

Invoking Forrest from Ant

+ Ant has an + <import> + task which can be used to invoke Forrest from Ant. All targets an= d properties + are imported and can be used in your project build. Here is a sim= ple example: +

+<project name=3D"myproject" default=3D"hello">
+     <!-- FORREST_HOME must be set as an environment variable -->
+     <property environment=3D"env"/>
+     <property name=3D"forrest.home" value=3D"${env.FORREST_HOME}"/>
+     <import file=3D"${env.FORREST_HOME}/forrest.build.xml"/>
+
+     <!-- 'site' is a target imported from forrest.build.xml -->
+     <target name=3D"post-build" depends=3D"site">
+       <echo>something here</echo>
+     </target>
+</project>
+

Because you are using your own version + of Ant to do Forrest's work, you will need to provide the + supporting catalog entity resolver: + 'cp forrest/lib/core/xml-commons-resolver-1= .1.jar $ANT_HOME/lib' +

(Note: The technique described above requires Ant 1.6+ otherwise the &l= t;import> + task will not be available for you to use. Forrest + bundles the latest version of Ant, so you can invoke your project + like this: forrest -f myproject.xml=2E + This will not run forrest; it will just use Forrest's Ant to execu= te + your buildfile.) +

+ Another option is to use the Forrest Antlet from the Krysalis Proj= ect's Antworks Importer. +

+ The Forrestbot provides wo= rkstages + to get source, build, deploy, and notify. This is very useful for + automating builds; you may want to consider using the Forrestbot. +

+ =20 +

+ +

Apache Document Type Definitions

+ That said, you can find the relevant DTDs using the naming convention + "forrest.apache.org/dtd/document-v13.dtd" etc. +

Apache Document Type Definitions

+ That said, you can find the relevant DTDs using the naming convention + "forrest.apache.org/dtd/document-v13.dtd" etc. +