You are viewing a plain text version of this content. The canonical link for it is here.
Posted to svn@forrest.apache.org by cr...@apache.org on 2005/04/11 17:12:22 UTC
svn commit: r160902 [23/28] - in forrest/site/0.6: ./ docs/ docs/images/
dtd/ entity/ howto/ images/ skin/ skin/css/ skin/images/ skin/scripts/ skins/
Added: forrest/site/0.6/docs/wiki-sample.html
URL: http://svn.apache.org/viewcvs/forrest/site/0.6/docs/wiki-sample.html?view=auto&rev=160902
==============================================================================
--- forrest/site/0.6/docs/wiki-sample.html (added)
+++ forrest/site/0.6/docs/wiki-sample.html Mon Apr 11 08:11:56 2005
@@ -0,0 +1,495 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta content="Apache Forrest" name="Generator">
+<meta name="Forrest-version" content="0.7-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<meta-data></meta-data>
+<title>wiki-sample (v0.6)</title>
+<link type="text/css" href="../skin/basic.css" rel="stylesheet">
+<link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet">
+<link media="print" type="text/css" href="../skin/print.css" rel="stylesheet">
+<link type="text/css" href="../skin/profile.css" rel="stylesheet">
+<script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script>
+<link rel="shortcut icon" href="../favicon.ico">
+</head>
+<body onload="init()">
+<script type="text/javascript">ndeSetTextSize();</script>
+<div id="top">
+<!--+
+ |breadtrail
+ +-->
+<div class="breadtrail">
+<a href="http://www.apache.org/">apache</a> > <a href="http://forrest.apache.org/">forrest</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+<!--+
+ |header
+ +-->
+<div class="header">
+<!--+
+ |start group logo
+ +-->
+<div class="grouplogo">
+<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../images/apache-forrest.png" title="The Apache Software Foundation"></a>
+</div>
+<!--+
+ |end group logo
+ +-->
+<!--+
+ |start Project Logo
+ +-->
+<div class="projectlogo">
+<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../images/project-logo.gif" title="Apache Forrest"></a>
+</div>
+<!--+
+ |end Project Logo
+ +-->
+<!--+
+ |start Search
+ +-->
+<div class="searchbox">
+<form action="http://www.google.com/search" method="get" class="roundtopsmall">
+<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google:');" value="Search the site with google:" size="25" name="q" id="query" type="text">
+ <input name="Search" value="Search" type="submit">
+</form>
+</div>
+<!--+
+ |end search
+ +-->
+<!--+
+ |start Tabs
+ +-->
+<ul id="tabs">
+<li>
+<a class="base-not-selected" href="../index.html">Welcome</a>
+</li>
+<li>
+<a class="base-not-selected" href="../contrib.html">Project</a>
+</li>
+<li class="current">
+<a class="base-selected" href="../docs/index.html">O.6 Docs</a>
+</li>
+<li>
+<a class="base-not-selected" href="../howto/index.html">0.6 How-To</a>
+</li>
+</ul>
+<!--+
+ |end Tabs
+ +-->
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<!--+
+ |start Subtabs
+ +-->
+<div id="level2tabs">
+<a class="base-selected" href="../docs/your-project.html">Core</a> | <a class="base-selected" href="../docs/forrestbot.html">ForrestBot</a> | <a class="base-selected" href="../docs/forrestbar.html">ForrestBar</a>
+</div>
+<!--+
+ |end Endtabs
+ +-->
+<script type="text/javascript" language="JavaScript"><!--
+ document.write("Published: " + document.lastModified);
+ // --></script>
+</div>
+<!--+
+ |breadtrail
+ +-->
+<div class="breadtrail">
+
+
+ </div>
+<!--+
+ |start Menu, mainarea
+ +-->
+<!--+
+ |start Menu
+ +-->
+<div id="menu">
+<div onclick="SwitchMenu('menu_1.1', '../skin/')" id="menu_1.1Title" class="menutitle">Documentation</div>
+<div id="menu_1.1" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/index.html">Index</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/your-project.html">Using Forrest</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/validation.html">XML Validation</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/linking.html">Menus and Linking</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/searching.html">Searching</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/skins.html">Default Skins</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/skin-package.html">Skin Packages</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrest-contract.html">Our Contract</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/compliance.html">Standards Compliance</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.10', '../skin/')" id="menu_1.1.10Title" class="menutitle">Advanced Topics</div>
+<div id="menu_1.1.10" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/catalog.html">Using DTD Catalogs</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/sitemap-ref.html">Sitemap Reference</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/project-sitemap.html">Project sitemap</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/cap.html">Sourcetype Action</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.11', '../skin/')" id="menu_1.1.11Title" class="menutitle">Upgrading</div>
+<div id="menu_1.1.11" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/upgrading_06.html">Upgrading to 0.6</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/upgrading_05.html">Upgrading to 0.5</a>
+</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.2', '../skin/')" id="menu_1.2Title" class="menutitle">SubProjects</div>
+<div id="menu_1.2" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/forrestbar.html">ForrestBar</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrestbot.html">Forrestbot</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrestbot-web-interface.html">Forrestbot Webapp</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_selected_1.3', '../skin/')" id="menu_selected_1.3Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Reference docs</div>
+<div id="menu_selected_1.3" class="selectedmenuitemgroup" style="display: block;">
+<div onclick="SwitchMenu('menu_1.3.1', '../skin/')" id="menu_1.3.1Title" class="menutitle">DTD documentation</div>
+<div id="menu_1.3.1" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/dtd-docs.html">Overview</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v20.dtdx.html">document-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/howto-v20.dtdx.html">howto-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/faq-v20.dtdx.html">faq-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v13.dtdx.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/howto-v13.dtdx.html">howto-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/faq-v13.dtdx.html">faq-v13</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_selected_1.3.2', '../skin/')" id="menu_selected_1.3.2Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Doc samples</div>
+<div id="menu_selected_1.3.2" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a title="" href="../docs/document-v13.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v20.html">document-v20</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">JSPWiki Reference</div>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/oowriter.html">OpenOffice.Org Writer</a>
+</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.4', '../skin/')" id="menu_1.4Title" class="menutitle">Older Docs</div>
+<div id="menu_1.4" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/primer.html">Forrest Primer</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/libre-intro.html">Libre</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/dreams.html">Dream list</a>
+</div>
+</div>
+<div id="credit">
+<hr>
+ This is documentation for past release v0.6
+ (<a href="http://forrest.apache.org/docs.html">More</a> ...)</div>
+<div id="roundbottom">
+<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
+<!--+
+ |alternative credits
+ +-->
+</div>
+<!--+
+ |end Menu
+ +-->
+<!--+
+ |start content
+ +-->
+<div id="content">
+<div title="Portable Document Format" class="pdflink">
+<a class="dida" href="wiki-sample.pdf"><img alt="PDF -icon" src="../skin/images/pdfdoc.gif" class="skin"><br>
+ PDF</a>
+</div>
+<div class="trail">
+ Font size:
+ <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
+ <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+ <input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
+</div>
+<h1>wiki-sample</h1>
+<div id="motd-area">
+ This is documentation for past release v0.6
+ (<a href="http://forrest.apache.org/docs.html">More</a> ...)</div>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#Forrest%27s+JSPWiki+Support">Forrest's JSPWiki Support</a>
+<ul class="minitoc">
+<li>
+<a href="#Important+Note">Important Note</a>
+</li>
+<li>
+<a href="#Quick+reference">Quick reference</a>
+</li>
+<li>
+<a href="#Limitations">Limitations
+</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#Samples">Samples
+</a>
+<ul class="minitoc">
+<li>
+<a href="#Writing+text">Writing text</a>
+</li>
+<li>
+<a href="#Hyperlinks">Hyperlinks
+</a>
+</li>
+<li>
+<a href="#Adding+pictures">Adding pictures</a>
+</li>
+<li>
+<a href="#Bulleted+lists">Bulleted lists
+</a>
+</li>
+<li>
+<a href="#Numbered+lists">Numbered lists
+</a>
+</li>
+<li>
+<a href="#Definition+lists+and+comments">Definition lists and comments</a>
+</li>
+<li>
+<a href="#Text+effects">Text effects</a>
+</li>
+<li>
+<a href="#Preformatted+text">Preformatted text</a>
+</li>
+<li>
+<a href="#Tables">Tables</a>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+<a name="N10007"></a><a name="Forrest%27s+JSPWiki+Support"></a>
+<h2 class="underlined_10">Forrest's JSPWiki Support</h2>
+<div class="section">
+<p>Forrest now has partial support for documentation in JSPWiki format, thanks to the <a class="external" href="http://chaperon.sf.net/">Chaperon parser</a>. Wiki is a simple text format that can be learned in minutes. This page provides an overview of the syntax that Forrest supports, namely a subset of that used by the <a class="external" href="http://www.jspwiki.org/Wiki.jsp?page=TextFormattingRules">JSPWiki</a>. There is also a <a class="external" href="http://www.jspwiki.org/Wiki.jsp?page=ChaperonTestPage">ChaperonTestPage</a>which might provide some more hints (view its source). </p>
+<a name="N10019"></a><a name="Important+Note"></a>
+<h3 class="underlined_5">Important Note</h3>
+<p>It is very easy to create broken documents by using this loose wiki syntax. Be sure to follow it explicitly. </p>
+<a name="N1001F"></a><a name="Quick+reference"></a>
+<h3 class="underlined_5">Quick reference</h3>
+<pre class="code">
+---- = Make a horizontal ruler. Extra '-' is ignored.
+\\ = force a line break, \\\=force line break and clear.
+
+[link] = creates a hyperlink to an internal WikiPage called 'Link'.
+[this is also a link] = creates a hyperlink to an internal WikiPage called
+'ThisIsAlsoALink'.
+[click here|link] = creates a hyperlink to an internal WikiPage called
+'Link', but displays the text 'click here' to the
+user instead of 'Link'.
+[1] = Makes a reference to a footnote numbered 1.
+[#1] = Marks the footnote number 1.
+[[link] = creates text '[link]'
+
+!heading = small heading with text 'heading'
+!!heading = medium heading with text 'heading'
+!!!heading = 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'' = prints 'text' in italic.
+__text__ = prints 'text' in bold.
+{{text}} = prints 'text' in monospaced font.
+
+* text = makes a bulleted list item with 'text'
+# text = makes a numbered list item with 'text'
+;term:ex = makes a definition for 'term' with the explanation 'ex'
+</pre>
+<a name="N10025"></a><a name="Limitations"></a>
+<h3 class="underlined_5">Limitations
+</h3>
+<p>These are the known limitations of the Forrest JSPWiki capability ... </p>
+<ul>
+<li>The "definition" syntax (;term:ex) is not supported. </li>
+<li>[[link] = creates text '[link]' (is not working). </li>
+</ul>
+</div>
+<a name="N10030"></a><a name="Samples"></a>
+<h2 class="underlined_10">Samples
+</h2>
+<div class="section">
+<p>The following sections are samples. View the source to see their use (no, not the source of this HTML page, but the actual wiki source from which this page was generated). </p>
+<a name="N10036"></a><a name="Writing+text"></a>
+<h3 class="underlined_5">Writing text</h3>
+<p>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 paragraph. It is just like writing an email. Add more fancy items as you become more comfortable. </p>
+<a name="N1003C"></a><a name="Hyperlinks"></a>
+<h3 class="underlined_5">Hyperlinks
+</h3>
+<p>The link can also be a direct URL starting with http:, ftp:, mailto:, https:, or news:, in which case the link points to an external entity. For example, to point at the java.sun.com home page, use </p>
+<pre class="code">[http://java.sun.com/]</pre>
+<p>which becomes <a class="external" href="http://java.sun.com/">http://java.sun.com/</a>
+</p>
+<pre class="code">[Java home page|http://java.sun.com/]</pre>
+<p>which becomes <a class="external" href="http://java.sun.com/">Java home page</a>
+</p>
+<p>Almost any kind of characters can be used inside a </p>
+<pre class="code">[WikiName]</pre>
+<p>as long as they are letters or numbers. </p>
+<a name="N10058"></a><a name="Adding+pictures"></a>
+<h3 class="underlined_5">Adding pictures</h3>
+<p>For security reasons uploading images is not permitted, but you can embed any image in the wiki code by putting the image available somewhere on the web in one of the allowed formats, and then just linking to it. For example, this is an inlined PNG image: <img alt="http://forrest.apache.org/skin/images/built-with-forrest-button.png" src="http://forrest.apache.org/skin/images/built-with-forrest-button.png"></p>
+<p>If you specify a link text e.g. </p>
+<pre class="code">[this one here|http://example.com/example.png]</pre>
+<p>then it becomes the ALT text for those who either can't or don't want to view images. </p>
+<a name="N10067"></a><a name="Bulleted+lists"></a>
+<h3 class="underlined_5">Bulleted lists
+</h3>
+<p>Use an asterisk (*) in the first column to make bulleted lists. Use more asterisks for deeper indentation. For example: </p>
+<pre class="code">
+* One
+* Two
+* Three
+** Three.One
+</pre>
+<p>creates </p>
+<ul>
+<li>One </li>
+<li>Two </li>
+<li>Three </li>
+<ul>
+<li>Three.One </li>
+</ul>
+</ul>
+<a name="N1007B"></a><a name="Numbered+lists"></a>
+<h3 class="underlined_5">Numbered lists
+</h3>
+<p>Just like with bulleted lists, but use a hash (#) instead of the asterisk. Like this: </p>
+<pre class="code">
+# One
+# Two
+# Three
+## Three.One
+</pre>
+<p>creates </p>
+<ol>
+<li>One </li>
+<li>Two </li>
+<li>Three </li>
+<ol>
+<li>Three.One </li>
+</ol>
+</ol>
+<p>If you want to write the list item on multiple lines, just add one or more 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. </p>
+<ul>
+<li>This is a single-line item. </li>
+<li>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 single item! </li>
+<li>The third line is again a single-line item. </li>
+</ul>
+<a name="N10098"></a><a name="Definition+lists+and+comments"></a>
+<h3 class="underlined_5">Definition lists and comments</h3>
+<p>A simple way to make definition lists is to use the ';:' -construct: </p>
+<p>; <strong>Construct</strong> : <em>Something you use to do something with</em>
+</p>
+<p>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: </p>
+<pre class="code">
+;:''Comment here.''
+</pre>
+<p>Which would be seen as ;: <em>Comment here.</em>
+</p>
+<a name="N100B0"></a><a name="Text+effects"></a>
+<h3 class="underlined_5">Text effects</h3>
+<p>You may use <strong>bold</strong> text or <em>italic</em> text, by using 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. </p>
+<a name="N100BC"></a><a name="Preformatted+text"></a>
+<h3 class="underlined_5">Preformatted text</h3>
+<p>If you want to add preformatted text (like code) just use three consecutive braces ({) to open a block, and three consecutive braces (}) to close a block. See the Tables example below. </p>
+<a name="N100C2"></a><a name="Tables"></a>
+<h3 class="underlined_5">Tables</h3>
+<p>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 then write the rows of the table. End with a line that is not a table. </p>
+<p>For example: </p>
+<pre class="code">
+|| Heading 1 || Heading 2
+| ''Italic Text'' | Plain Text
+| [Forrest Home Page|http://forrest.apache.org/] | [http://forrest.apache.org/]
+</pre>
+<p>renders the following table. Note how you can use links also inside tables. </p>
+<table class="ForrestTable" cellspacing="1" cellpadding="4">
+<tr>
+<th>Heading 1 </th><th>Heading 2 </th>
+</tr>
+<tr>
+<td><em>Italic Text</em> </td><td>Plain Text </td>
+</tr>
+<tr>
+<td><a href="http://forrest.apache.org/">Forrest Home Page</a></td><td><a href="http://forrest.apache.org/">http://forrest.apache.org/</a></td>
+</tr>
+</table>
+</div>
+</div>
+<!--+
+ |end content
+ +-->
+<div class="clearboth"> </div>
+</div>
+<div id="footer">
+<!--+
+ |start bottomstrip
+ +-->
+<div class="lastmodified">
+<script type="text/javascript"><!--
+document.write("Last Published: " + document.lastModified);
+// --></script>
+</div>
+<div class="copyright">
+ Copyright © 2002-2004 The Apache Software Foundation.</div>
+<!--+
+ |end bottomstrip
+ +-->
+</div>
+</body>
+</html>
Propchange: forrest/site/0.6/docs/wiki-sample.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/0.6/docs/wiki-sample.pdf
URL: http://svn.apache.org/viewcvs/forrest/site/0.6/docs/wiki-sample.pdf?view=auto&rev=160902
==============================================================================
Binary file - no diff available.
Propchange: forrest/site/0.6/docs/wiki-sample.pdf
------------------------------------------------------------------------------
svn:mime-type = application/pdf
Added: forrest/site/0.6/docs/your-project.html
URL: http://svn.apache.org/viewcvs/forrest/site/0.6/docs/your-project.html?view=auto&rev=160902
==============================================================================
--- forrest/site/0.6/docs/your-project.html (added)
+++ forrest/site/0.6/docs/your-project.html Mon Apr 11 08:11:56 2005
@@ -0,0 +1,1474 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta content="Apache Forrest" name="Generator">
+<meta name="Forrest-version" content="0.7-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<meta-data></meta-data>
+<title>Using Forrest (v0.6)</title>
+<link type="text/css" href="../skin/basic.css" rel="stylesheet">
+<link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet">
+<link media="print" type="text/css" href="../skin/print.css" rel="stylesheet">
+<link type="text/css" href="../skin/profile.css" rel="stylesheet">
+<script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script>
+<link rel="shortcut icon" href="../favicon.ico">
+</head>
+<body onload="init()">
+<script type="text/javascript">ndeSetTextSize();</script>
+<div id="top">
+<!--+
+ |breadtrail
+ +-->
+<div class="breadtrail">
+<a href="http://www.apache.org/">apache</a> > <a href="http://forrest.apache.org/">forrest</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+<!--+
+ |header
+ +-->
+<div class="header">
+<!--+
+ |start group logo
+ +-->
+<div class="grouplogo">
+<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../images/apache-forrest.png" title="The Apache Software Foundation"></a>
+</div>
+<!--+
+ |end group logo
+ +-->
+<!--+
+ |start Project Logo
+ +-->
+<div class="projectlogo">
+<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../images/project-logo.gif" title="Apache Forrest"></a>
+</div>
+<!--+
+ |end Project Logo
+ +-->
+<!--+
+ |start Search
+ +-->
+<div class="searchbox">
+<form action="http://www.google.com/search" method="get" class="roundtopsmall">
+<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google:');" value="Search the site with google:" size="25" name="q" id="query" type="text">
+ <input name="Search" value="Search" type="submit">
+</form>
+</div>
+<!--+
+ |end search
+ +-->
+<!--+
+ |start Tabs
+ +-->
+<ul id="tabs">
+<li>
+<a class="base-not-selected" href="../index.html">Welcome</a>
+</li>
+<li>
+<a class="base-not-selected" href="../contrib.html">Project</a>
+</li>
+<li class="current">
+<a class="base-selected" href="../docs/index.html">O.6 Docs</a>
+</li>
+<li>
+<a class="base-not-selected" href="../howto/index.html">0.6 How-To</a>
+</li>
+</ul>
+<!--+
+ |end Tabs
+ +-->
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<!--+
+ |start Subtabs
+ +-->
+<div id="level2tabs">
+<a class="base-selected" href="../docs/your-project.html">Core</a> | <a class="base-selected" href="../docs/forrestbot.html">ForrestBot</a> | <a class="base-selected" href="../docs/forrestbar.html">ForrestBar</a>
+</div>
+<!--+
+ |end Endtabs
+ +-->
+<script type="text/javascript" language="JavaScript"><!--
+ document.write("Published: " + document.lastModified);
+ // --></script>
+</div>
+<!--+
+ |breadtrail
+ +-->
+<div class="breadtrail">
+
+
+ </div>
+<!--+
+ |start Menu, mainarea
+ +-->
+<!--+
+ |start Menu
+ +-->
+<div id="menu">
+<div onclick="SwitchMenu('menu_selected_1.1', '../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Documentation</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a title="" href="../docs/index.html">Index</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">Using Forrest</div>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/validation.html">XML Validation</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/linking.html">Menus and Linking</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/searching.html">Searching</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/skins.html">Default Skins</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/skin-package.html">Skin Packages</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrest-contract.html">Our Contract</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/compliance.html">Standards Compliance</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.10', '../skin/')" id="menu_1.1.10Title" class="menutitle">Advanced Topics</div>
+<div id="menu_1.1.10" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/catalog.html">Using DTD Catalogs</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/sitemap-ref.html">Sitemap Reference</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/project-sitemap.html">Project sitemap</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/cap.html">Sourcetype Action</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.11', '../skin/')" id="menu_1.1.11Title" class="menutitle">Upgrading</div>
+<div id="menu_1.1.11" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/upgrading_06.html">Upgrading to 0.6</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/upgrading_05.html">Upgrading to 0.5</a>
+</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.2', '../skin/')" id="menu_1.2Title" class="menutitle">SubProjects</div>
+<div id="menu_1.2" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/forrestbar.html">ForrestBar</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrestbot.html">Forrestbot</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrestbot-web-interface.html">Forrestbot Webapp</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.3', '../skin/')" id="menu_1.3Title" class="menutitle">Reference docs</div>
+<div id="menu_1.3" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.3.1', '../skin/')" id="menu_1.3.1Title" class="menutitle">DTD documentation</div>
+<div id="menu_1.3.1" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/dtd-docs.html">Overview</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v20.dtdx.html">document-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/howto-v20.dtdx.html">howto-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/faq-v20.dtdx.html">faq-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v13.dtdx.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/howto-v13.dtdx.html">howto-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/faq-v13.dtdx.html">faq-v13</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.3.2', '../skin/')" id="menu_1.3.2Title" class="menutitle">Doc samples</div>
+<div id="menu_1.3.2" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/document-v13.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v20.html">document-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/wiki-sample.html">JSPWiki Reference</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/oowriter.html">OpenOffice.Org Writer</a>
+</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.4', '../skin/')" id="menu_1.4Title" class="menutitle">Older Docs</div>
+<div id="menu_1.4" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/primer.html">Forrest Primer</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/libre-intro.html">Libre</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/dreams.html">Dream list</a>
+</div>
+</div>
+<div id="credit">
+<hr>
+ This is documentation for past release v0.6
+ (<a href="http://forrest.apache.org/docs.html">More</a> ...)</div>
+<div id="roundbottom">
+<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
+<!--+
+ |alternative credits
+ +-->
+</div>
+<!--+
+ |end Menu
+ +-->
+<!--+
+ |start content
+ +-->
+<div id="content">
+<div title="Portable Document Format" class="pdflink">
+<a class="dida" href="your-project.pdf"><img alt="PDF -icon" src="../skin/images/pdfdoc.gif" class="skin"><br>
+ PDF</a>
+</div>
+<div class="trail">
+ Font size:
+ <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
+ <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+ <input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
+</div>
+<h1>Using Forrest</h1>
+<h3>A tutorial on how to use Forrest in your own projects</h3>
+<div id="motd-area">
+ This is documentation for past release v0.6
+ (<a href="http://forrest.apache.org/docs.html">More</a> ...)</div>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#intro">Introduction</a>
+</li>
+<li>
+<a href="#installing">Installing Forrest</a>
+</li>
+<li>
+<a href="#seeding_new">Seeding a new project</a>
+</li>
+<li>
+<a href="#seeding_existing">Seeding an existing project</a>
+</li>
+<li>
+<a href="#customizing">Customizing your project</a>
+<ul class="minitoc">
+<li>
+<a href="#skinconf.xml">Configuring the Forrest skin: skinconf.xml</a>
+</li>
+<li>
+<a href="#Changing_the_layout">Changing the layout: forrest.properties</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#adding_content">Adding content</a>
+<ul class="minitoc">
+<li>
+<a href="#site.xml">site.xml</a>
+</li>
+<li>
+<a href="#tabs.xml">tabs.xml</a>
+</li>
+<li>
+<a href="#images">Images</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#sitemap.xmap">Advanced customizations: sitemap.xmap</a>
+<ul class="minitoc">
+<li>
+<a href="#adding_new_content_type">Example: Adding a new content type</a>
+<ul class="minitoc">
+<li>
+<a href="#new_dtd">Registering a new DTD</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#adding_new_content_type_2">Example: Adding a new content type (advanced)</a>
+</li>
+<li>
+<a href="#integrating_rss">Example: integrating external RSS content</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#skins">Forrest skins</a>
+<ul class="minitoc">
+<li>
+<a href="#skin-configuration">Configuration of skins</a>
+</li>
+<li>
+<a href="#new_skin">Defining a new skin</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#webapp">Interactive Forrest: faster turnaround when developing your docs</a>
+<ul class="minitoc">
+<li>
+<a href="#forrest_run">Running as a webapp</a>
+<ul class="minitoc">
+<li>
+<a href="#using_webapp">Using the webapp</a>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li>
+<a href="#invoking_from_ant">Invoking Forrest from Ant</a>
+</li>
+</ul>
+</div>
+
+<a name="N10010"></a><a name="intro"></a>
+<h2 class="underlined_10">Introduction</h2>
+<div class="section">
+<p>
+ This tutorial will lead you through the process of installing Forrest, and using
+ it to create a new project, or add Forrest-based docs to an existing project.
+ </p>
+</div>
+
+
+<a name="N1001A"></a><a name="installing"></a>
+<h2 class="underlined_10">Installing Forrest</h2>
+<div class="section">
+<p>
+
+<a href="http://forrest.apache.org/mirrors.cgi">Download</a> the latest release
+ of Forrest, or
+ if you want to try the development version,
+ <a href="../build.html">build Forrest</a> from source.
+ </p>
+<p>
+ After downloading and extracting forrest, you need to add environment variables.
+ </p>
+<p>In Unix/Linux:</p>
+<pre class="code">
+~/apache-forrest-0.6$ export FORREST_HOME=`pwd`/src/core
+~/apache-forrest-0.6$ export PATH=$PATH:$FORREST_HOME/bin
+ </pre>
+<p>In Windows:</p>
+<pre class="code">
+Go to "My Computer", "Properties", "Advanced", "Environment Variables"
+and add:
+<span class="codefrag">FORREST_HOME</span> as <span class="codefrag">C:\full\path\to\apache-forrest-0.6\src\core</span>
+<span class="codefrag">PATH</span> as <span class="codefrag">%PATH%;%FORREST_HOME%\bin</span>
+
+</pre>
+<p>
+ To see what the 'forrest' command can do, type 'forrest -projecthelp'.
+ The build targets that are marked with * are the commonly used ones.
+ </p>
+<pre class="code">
+Apache Forrest. Run 'forrest -projecthelp' to list options
+
+Buildfile: /usr/local/svn/forrest/src/core/bin/../forrest.build.xml
+
+ *=======================================================*
+ | Forrest Site Builder |
+ | 0.6-dev |
+ *=======================================================*
+
+ Call this through the 'forrest' command
+
+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 project
+ run_default_jetty Run Jetty with configuration file found in Forrest
+ seed * Seeds a directory with a template project doc structure
+ 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 suitable
+ for local execution only, use the 'war' or 'webapp'
+ target if you wish to deploy remotely.
+Default target: site
+ </pre>
+<p>
+ As 'site' is the default target, just running 'forrest' without options 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.
+ </p>
+</div>
+
+
+<a name="N10053"></a><a name="seeding_new"></a>
+<h2 class="underlined_10">Seeding a new project</h2>
+<div class="section">
+<p>
+ 'Seeding' a project is our own arborial term for adding a template
+ documentation set to your project, which you can then customize.
+ </p>
+<p>
+ To try this out, create a completely new directory, change directory
+ to it, and do 'forrest seed':
+ </p>
+<pre class="code">
+[/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
+...
+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 change 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 skin
+/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 structure
+/src/documentation/content/xdocs/tabs.xml # Skin-specific 'tabs' file.
+/src/documentation/content/*.html,pdf # Static content files, may have subdirs
+/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 demo.
+- 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
+ </pre>
+<div class="frame note">
+<div class="label">Note</div>
+<div class="content">
+ As you have probably noticed, we like to document things right in the
+ script, on the theory that people only read online docs when desperate :)
+ </div>
+</div>
+<p>
+ You now have a template documentation structure all set up:
+ </p>
+<pre class="code">
+[/home/me/forrest/my-test]$ tree
+.
+|-- 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
+ </pre>
+<p>
+ To render this to HTML, type 'forrest'. You should have a HTML site rendered
+ into the <span class="codefrag">build/site</span> directory:
+ </p>
+<div style="text-align: center;">
+<img class="figure" alt="New project" src="images/new-project.png" height="356" width="500"></div>
+<p>
+ Practise with adding new content. Change to the directory
+ <span class="codefrag">src/documentation/content/xdocs</span> and copy the file
+ <span class="codefrag">index.xml</span> to create <span class="codefrag">my-new-file.xml</span> as a
+ new document. Edit it to change some text. Add an entry to
+ <span class="codefrag">site.xml</span> by copying one of the other entries and
+ changing it to suit. Now do 'forrest' to see the result.
+ </p>
+</div>
+
+<a name="N10089"></a><a name="seeding_existing"></a>
+<h2 class="underlined_10">Seeding an existing project</h2>
+<div class="section">
+<p>
+ In the section above, we have run 'forrest seed' in an empty directory
+ 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.
+ </p>
+<p>
+ If your project already has XML documentation, it may be easier to tell
+ Forrest where the XML sources are, rather than rearrange your project
+ directories to accommodate Forrest. This can be done by editing
+ <span class="codefrag">forrest.properties</span> (consult
+ the <a href="#Changing_the_layout">Changing the layout</a>
+ section for more details).
+ </p>
+</div>
+
+<a name="N1009D"></a><a name="customizing"></a>
+<h2 class="underlined_10">Customizing your project</h2>
+<div class="section">
+<p>
+ Having seeded a project with template docs, you will now want to customize it
+ to your project's needs. Here we will deal with configuring the skin, and
+ changing the project layout.
+ </p>
+<a name="N100A6"></a><a name="skinconf.xml"></a>
+<h3 class="underlined_5">Configuring the Forrest skin: skinconf.xml</h3>
+<p>
+ Most Forrest skins can be customized through a single XML file,
+ <span class="codefrag">src/documentation/skinconf.xml</span>, which looks like this:
+ </p>
+<pre class="code">
+<!--
+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="lucene"
+ Add box-location="alt" to move the search box to an alternate location
+ (if the skin supports it) and box-location="all" to show it in all
+ available locations on the page. Remove the <search> element to show
+ no search box.
+ -->
+ <search name="MyProject" domain="mydomain"/>
+
+ <!-- Disable the print link? If enabled, invalid HTML 4.0.1 -->
+ <disable-print-link>true</disable-print-link>
+ <!-- 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>
+
+ <!-- Disable navigation icons on all external links? -->
+ <disable-external-link-image>false</disable-external-link-image>
+
+ <!-- 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>
+
+ <!-- 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="alt" to move the trail to an alternate location
+ (if the skin supports it).
+ -->
+ <trail>
+ <link1 name="myGroup" href="http://www.apache.org/"/>
+ <link2 name="myProject" href="http://forrest.apache.org/"/>
+ <link3 name="" href=""/>
+ </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).
+ @min-sections
+ Minimum required to create a TOC.
+ @location ("page","menu","page,menu")
+ Where to show the TOC.
+ -->
+ <toc max-depth="2" min-sections="1" location="page"/>
+
+ <!-- Heading types can be clean|underlined|boxed -->
+ <headings type="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>
+
+ <!-- Settings specific to PDF output. -->
+ <pdf>
+ <!--
+ 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="letter" orientation="portrait" text-align="left"/>
+
+ <!--
+ Margins can be specified for top, bottom, inner, and outer
+ edges. If double-sided="false", the inner edge is always left
+ and the outer is always right. If double-sided="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="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='pdf' will have its name and url
+ displayed in the PDF page's footer. -->
+ </credits>
+
+</skinconfig>
+</pre>
+<p>
+ Customise this file for your project. The <span class="codefrag">images/</span> directory
+ mentioned in 'project-logo' and 'group-logo' elements corresponds to the
+ <span class="codefrag">src/documentation/resources/images</span> directory
+ (this mapping is done automatically by the sitemap).
+ </p>
+<p>
+ Having edited this file (and ensured it is valid XML), re-run the 'forrest'
+ command in the site root, and the site would be updated.
+ </p>
+<a name="N100C3"></a><a name="Changing_the_layout"></a>
+<h3 class="underlined_5">Changing the layout: forrest.properties</h3>
+<p>
+ 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.
+ </p>
+<p>
+ The <span class="codefrag">forrest.properties</span> file maps from your directory
+ layout to Forrest's. If you generated your site with 'forrest seed', you
+ will have one pre-written, with all the entries commented out.
+ </p>
+<div class="frame note">
+<div class="label">Note</div>
+<div class="content">
+ You only need to un-comment entries if you are going to change them
+ to something different.
+ If you keep in synchronisation with the 'forrest seed' defaults,
+ then it is easy to diff each time that you update.
+ </div>
+</div>
+<p>
+ The main entries (with default values) are:
+ </p>
+<pre class="code">
+# 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=status.xml
+#project.content-dir=src/documentation
+#project.conf-dir=${project.content-dir}/conf
+#project.sitemap-dir=${project.content-dir}
+#project.xdocs-dir=${project.content-dir}/content/xdocs
+#project.resources-dir=${project.content-dir}/resources
+#project.stylesheets-dir=${project.resources-dir}/stylesheets
+#project.images-dir=${project.resources-dir}/images
+#project.schema-dir=${project.resources-dir}/schema
+#project.skins-dir=${project.content-dir}/skins
+#project.skinconf=${project.content-dir}/skinconf.xml
+#project.lib-dir=${project.content-dir}/lib
+#project.classes-dir=${project.content-dir}/classes
+ </pre>
+<p>
+ For example, if you wish to keep XML documentation in src/xdocs rather than
+ <span class="codefrag">src/documentation/content/xdocs</span> simply change the
+ definition for project.xdocs-dir
+ </p>
+<pre class="code">project.xdocs-dir=src/xdocs</pre>
+<p>
+ For example, to emulate the simple
+ <a class="external" href="http://maven.apache.org/">Maven</a> format:
+ </p>
+<div class="pre">
+ /xdocs
+ /xdocs/images
+ /xdocs/stylesheets
+ </div>
+<p>Here are the required property definitions:</p>
+<pre class="code">
+project.content-dir=xdocs
+project.sitemap-dir=${project.content-dir}
+project.xdocs-dir=${project.content-dir}
+project.stylesheets-dir=${project.content-dir}/stylesheets
+project.images-dir=${project.content-dir}/images
+project.skinconf=${project.content-dir}/skinconf.xml
+ </pre>
+<div class="frame note">
+<div class="label">Note</div>
+<div class="content">
+ Internally, Forrest rearranges the specified directory into the default
+ <span class="codefrag">src/documentation/content/xdocs</span> structure. In the layout above, we have
+ overlapping directories, so you will end up with duplicate files. This small
+ glitch doesn't usually cause problems; just always remember that all links
+ are resolved through the sitemap.
+ </div>
+</div>
+</div>
+
+
+<a name="N10102"></a><a name="adding_content"></a>
+<h2 class="underlined_10">Adding content</h2>
+<div class="section">
+<p>
+ Now you can start adding content of your own, in
+ <span class="codefrag">src/documentation/content/xdocs</span>
+
+</p>
+<a name="N1010E"></a><a name="site.xml"></a>
+<h3 class="underlined_5">site.xml</h3>
+<p>
+ When adding a new xml document, you would add an entry to the project's
+ <span class="codefrag">site.xml</span> file. This site.xml is like a site index, and is rendered as
+ the vertical column of links in the default skin. Look at Forrest's own
+ xdocs for an example. More detailed info about site.xml is provided in
+ the document <a href="../docs/linking.html">Menus and Linking</a>.
+ </p>
+<a name="N1011F"></a><a name="tabs.xml"></a>
+<h3 class="underlined_5">tabs.xml</h3>
+<p>
+ The <span class="codefrag">tabs.xml</span> file is used to produce the 'tabs'.
+ which enable users to quickly jump to sections of your site.
+ See the
+ <a href="../docs/linking.html#menu_generation">menu generation</a> documentation
+ for more details, and again, consult Forrest's own docs for a usage
+ example.
+ </p>
+<div style="text-align: center;">
+<img class="figure" alt="Tabs" src="images/tabs.png"></div>
+<p>You can have one or two levels of tabs. The images above show a
+ single level. However, you can create a second level that
+ will only be displayed when its parent tab is selected. For example,
+ the <span class="codefrag">tabs.xml</span> snippet below will display either one or
+ two rows of tabs, depending on which of the top level tabs is selected.
+ The first row will have two tabs: one labelled <span class="codefrag">How-Tos</span>
+ and the other labelled <span class="codefrag">Apache XML Projects</span>. When the
+ <span class="codefrag">How-Tos</span> tab is selected there will
+ be no second row of tabs. However, when the <span class="codefrag">Apache XML
+ Projects</span> tab is selected, a second row of tabs will be displayed
+ below the first.</p>
+<pre class="code">
+ <tab label="How-Tos" dir="community/howto/"/>
+ <tab label="Apache XML Projects" href="http://xml.apache.org">
+ <tab label="Forrest" href="http://forrest.apache.org/"/>
+ <tab label="Xerces" href="http://xml.apache.org/xerces"/>
+ </tab>
+</pre>
+<a name="N1014A"></a><a name="images"></a>
+<h3 class="underlined_5">Images</h3>
+<p>
+ Images usually go in <span class="codefrag">src/documentation/resources/images/</span>
+ The default sitemap
+ maps this directory to <span class="codefrag">images/</span>, so image tags will typically look
+ like <figure src="images/project-logo.png" alt="Project Logo"/>
+ </p>
+</div>
+
+
+<a name="N1015B"></a><a name="sitemap.xmap"></a>
+<h2 class="underlined_10">Advanced customizations: sitemap.xmap</h2>
+<div class="section">
+<p>
+ 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
+ <a href="..//">Forrest website</a> itself uses the
+ default sitemap.
+ </p>
+<p>
+ Sometimes, one needs to go beyond the default set of rules. This is where
+ Forrest really shines, because its Cocoon backend allows virtually any
+ processing pipeline to be defined. For example, one can:
+ </p>
+<ul>
+
+<li>Transform custom XML content types with XSLT stylesheets.</li>
+
+<li>Generate PNG or JPEG images from
+ <a class="external" href="http://www.w3.org/TR/SVG/">SVG</a> XML files.
+ (<strong>Note:</strong> Forrest's sitemap now does this natively.)</li>
+
+<li>Integrate external XML feeds (e.g. RSS) into your site's content.
+ (<strong>Note:</strong> See issues.xmap for an example.)</li>
+
+<li>Merge XML sources via aggregation, or make content from large XML
+ sources available as "virtual" files.
+ (<strong>Note:</strong> Forrest makes extensive use of aggregation
+ in the default sitemaps. It also defines a whole-site HTML
+ and PDF, available as the standard names <span class="codefrag">wholesite.html</span>
+ and <span class="codefrag">wholesite.pdf</span>.)</li>
+
+<li>Read content from exotic sources like
+ <a class="external" href="http://www.rpbourret.com/xml/XMLDBLinks.htm">XML
+ databases</a>.</li>
+
+<li>Integrate any of <a class="external" href="http://cocoon.apache.org/2.1/">Cocoon's</a> vast array
+ of capabilities. The possibilities are best appreciated by
+ downloading the latest Cocoon distribution and playing with the
+ samples.</li>
+
+</ul>
+<p>
+ The Forrest sitemaps are at
+ <span class="codefrag">forrest/src/core/context/*.xmap</span>
+
+</p>
+<p>
+ You can add pre-processing sitemaps to your project
+ <span class="codefrag">src/documentation</span> directory (or wherever
+ <span class="codefrag">${project.sitemap-dir}</span> points to). Any match that
+ is not handled, passes through to be handled by the default Forrest
+ sitemaps - obviously extremely powerful. The capability is described
+ in
+ "<a href="../docs/project-sitemap.html">Using project sitemaps</a>"
+ and some worked examples are shown in the following sections here.
+ </p>
+<div class="frame note">
+<div class="label">Note</div>
+<div class="content">
+ We advise you to spend time to understand the Apache Cocoon sitemap.
+ See <a class="external" href="http://cocoon.apache.org/2.1/userdocs/concepts/sitemap.html">Cocoon sitemap</a>
+ and <a class="external" href="http://cocoon.apache.org/2.1/userdocs/concepts/">Cocoon concepts</a>
+ and related component documentation.
+ The Forrest sitemap is broken into multiple files. The main one is
+ <strong>sitemap.xmap</strong> which delegates to others. See the
+ <a href="../docs/sitemap-ref.html">Sitemap Reference</a> for a tour of the
+ default sitemap.
+ </div>
+</div>
+<a name="N101C0"></a><a name="adding_new_content_type"></a>
+<h3 class="underlined_5">Example: Adding a new content type</h3>
+<p>
+ Follow this worked example. In a fresh directory do 'forrest seed'
+ then follow the steps described in this section.
+ </p>
+<p>
+ An example scenario is that we have a specialised list of downloads
+ 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.
+ </p>
+<pre class="code"><?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE document PUBLIC "-//Acme//DTD Download Documentation V1.0//EN"
+ "dtd/download-v10.dtd">
+<document>
+ <header>
+ <title>Downloading Binaries</title>
+ </header>
+ <body>
+ <section id="download">
+ <title>Downloading binaries</title>
+ <p>
+ Here are the binaries for FooProject
+ </p>
+ <release version="0.9.13" date="2002-10-11">
+ <downloads>
+ <file
+ url="http://prdownloads.sf.net/aft/fooproj-0.9.13-bin.zip?download"
+ name="fooproj-0.9.13-bin.zip"
+ size="5738322"/>
+ <file
+ url="http://prdownloads.sf.net/aft/fooproj-0.9.13-src.zip?download"
+ name="fooproj-0.9.13-src.zip"
+ size="10239777"/>
+ </downloads>
+ </release>
+ <release version="0.9.12" date="2002-10-08">
+ <downloads>
+ <file
+ url="http://prdownloads.sf.net/aft/fooproj-0.9.12-src.zip?download"
+ name="fooproj-0.9.12-src.zip"
+ size="10022737"/>
+ </downloads>
+ </release>
+ </section>
+ <section id="cvs">
+ <title>Getting FooProject from CVS</title>
+ <p>....</p>
+ </section>
+ </body>
+</document></pre>
+<p>This file called "<span class="codefrag">download.xml</span>" would be placed in
+ your content directory (typically
+ <span class="codefrag">src/documentation/content/xdocs</span>) and an entry added to
+ <span class="codefrag">site.xml</span>
+</p>
+<p>
+ To handle these special tags, one would write a stylesheet to convert
+ them to the intermediate Forrest xdocs structure. Here is such a stylesheet,
+ called "<span class="codefrag">download2document.xsl</span>" ...
+ </p>
+<pre class="code"><?xml version="1.0" encoding="utf-8"?>
+<xsl:stylesheet
+ version="1.0"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+ <xsl:template match="release">
+ <section id="{@version}">
+ <title>Version <xsl:value-of select="@version"/> (released
+ <xsl:value-of select="@date"/>)</title>
+ <table>
+ <tr><th>File</th><th>Size</th></tr>
+ <xsl:apply-templates select="downloads/*"/>
+ </table>
+ </section>
+ </xsl:template>
+
+ <xsl:template match="file">
+ <tr>
+ <td><link href="{@url}"><xsl:value-of select="@name"/></link></td>
+ <td><xsl:value-of
+ select="format-number(@size div (1024*1024), '##.##')"/> MB</td>
+ </tr>
+ </xsl:template>
+
+ <xsl:template match="@* | node() | comment()">
+ <xsl:copy>
+ <xsl:apply-templates select="@*"/>
+ <xsl:apply-templates/>
+ </xsl:copy>
+ </xsl:template>
+
+</xsl:stylesheet>
+</pre>
+<p>
+ Place this file in the default stylesheets directory,
+ <span class="codefrag">src/documentation/resources/stylesheets</span> (or wherever
+ ${project.stylesheets-dir} points).
+ </p>
+<p>
+ Now we will create a project sitemap to control the
+ transformation of our custom xml
+ structure into the Forrest intermediate xdocs structure.
+ </p>
+<div class="frame note">
+<div class="label">Note</div>
+<div class="content">
+ The <a href="../docs/sitemap-ref.html">Sitemap
+ Reference</a> provides details about how the sitemap works.
+ </div>
+</div>
+<p>
+ Add the following as the file
+ <span class="codefrag">src/documentation/sitemap.xmap</span> ...
+ </p>
+<pre class="code"><?xml version="1.0"?>
+<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
+ <map:pipelines>
+ <map:pipeline>
+ <map:match pattern="**download.xml">
+ <map:generate src="{project:content.xdocs}{1}download.xml" />
+ <map:transform src="{project:resources.stylesheets}/download2document.xsl" />
+ <map:serialize type="xml"/>
+ </map:match>
+ </map:pipeline>
+ </map:pipelines>
+</map:sitemap>
+</pre>
+<p>
+ 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 machinery
+ will handle the aggregation with navigation menus etc. and will
+ apply the normal skin.
+ </p>
+<a name="N10202"></a><a name="new_dtd"></a>
+<h4>Registering a new DTD</h4>
+<p>
+ 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 is no
+ exception. The <a href="../docs/validation.html">XML
+ Validation</a> document continues this example, showing how
+ to register a new document type. Briefly, this involves:
+ </p>
+<ul>
+
+<li>Create a new DTD or (in our case) extend an existing
+ one.</li>
+
+<li>Place the new DTD in the
+ <span class="codefrag">${project.schema-dir}/dtd</span> directory.</li>
+
+<li>Add an XML Catalog to enable a mapping from the
+ DOCTYPE public id to the relevant DTD file.</li>
+
+<li>Tell the system about your catalog.</li>
+
+</ul>
+<div class="frame note">
+<div class="label">Note</div>
+<div class="content">
+ Please see <a href="../docs/validation.html">XML Validation</a>
+ for the complete description for those steps.
+ </div>
+</div>
+<a name="N1022A"></a><a name="adding_new_content_type_2"></a>
+<h3 class="underlined_5">Example: Adding a new content type (advanced)</h3>
+<p>
+ 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.
+ </p>
+<pre class="code"><?xml version="1.0"?>
+<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
+
+ <map:components>
+ <map:selectors default="parameter">
+ <map:selector logger="sitemap.selector.parameter"
+ name="parameter" src="org.apache.cocoon.selection.ParameterSelector" />
+ </map:selectors>
+ <map:actions>
+ <map:action logger="sitemap.action.sourcetype" name="sourcetype"
+ src="org.apache.cocoon.acting.sourcetype.SourceTypeAction">
+ <sourcetype name="download-v1.0">
+ <document-declaration
+ public-id="-//Acme//DTD Download Documentation V1.0//EN" />
+ </sourcetype>
+ <sourcetype name="download-v1.1">
+ <document-declaration
+ public-id="-//Acme//DTD Download Documentation V1.1//EN" />
+ </sourcetype>
+ </map:action>
+ </map:actions>
+ </map:components>
+
+ <map:pipelines>
+ <map:pipeline>
+ <map:match pattern="**download.xml">
+ <map:generate src="{project:content.xdocs}{1}download.xml" />
+ <map:act type="sourcetype" src="{project:content.xdocs}{1}download.xml">
+ <map:select type="parameter">
+ <map:parameter name="parameter-selector-test" value="{sourcetype}" />
+ <map:when test="download-v1.0">
+ <map:transform
+ src="{project:resources.stylesheets}/download2document.xsl" />
+ </map:when>
+ <map:when test="download-v1.1">
+ <map:transform
+ src="{project:resources.stylesheets}/download-v11-2document.xsl" />
+ </map:when>
+ </map:select>
+ </map:act>
+ <map:serialize type="xml"/>
+ </map:match>
+ </map:pipeline>
+ </map:pipelines>
+</map:sitemap>
+</pre>
+<p>
+ This is the type of processing that happens in the main
+ <span class="codefrag">src/core/context/forrest.xmap</span> sitemap. We have
+ added similar handling to our project sitemap. Basically, this
+ uses the <a href="../docs/cap.html">SourceTypeAction (content aware pipelines)</a>
+ to detect the doctype. The new document-v11.dtd needs to be also
+ added to your project Catalog.
+ </p>
+<p>
+ Note that any sitemap component must be declared before it
+ can be used, because the project sitemap is the first sitemap
+ to be consulted.
+ </p>
+<a name="N10245"></a><a name="integrating_rss"></a>
+<h3 class="underlined_5">Example: integrating external RSS content</h3>
+<p>Similar to the previous example, we can integrate RSS into our
+ site simply by providing a match in our project sitemap.xmap ...
+ </p>
+<pre class="code"><?xml version="1.0"?>
+<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
+ <map:pipelines>
+ <map:pipeline>
+ <strong>
+ <map:match pattern="**weblog.xml">
+ <map:generate src="http://blogs.cocoondev.org/stevenn/index.rss"/>
+ <map:transform src="{forrest:stylesheets}/rss2document.xsl"/>
+ <map:serialize type="xml"/>
+ </map:match>
+</strong>
+ <map:match pattern=".......">
+ <!-- handle other project-specific matches -->
+ </map:match>
+ </map:pipeline>
+ </map:pipelines>
+</map:sitemap>
+</pre>
+<p>You will probably want to copy the core Forrest
+ <span class="codefrag">rss2document.xsl</span> to your project,
+ customise it to your needs, and refer to it with
+ <span class="codefrag">src="{project:resources.stylesheets}/rss2document.xsl"</span>.
+ Then of course you would add an entry to site.xml to link
+ to weblog.html
+ </p>
+</div>
+
+
+<a name="N10260"></a><a name="skins"></a>
+<h2 class="underlined_10">Forrest skins</h2>
+<div class="section">
+<p>
+ As Forrest separates content from presentation, we can plug in different
+ "skins" to instantly change a site's look and feel. Forrest provides one
+ primary skin, <span class="codefrag">pelt</span>, and some others in various
+ states of development.
+ To change the skin, edit the <span class="codefrag">forrest.properties</span> file
+ to set <span class="codefrag">project.skin=leather-dev</span> or some other skin name.
+ </p>
+<div class="frame note">
+<div class="label">Note</div>
+<div class="content">
+ Forrest supplies a collection of
+ <a href="../docs/skins.html">default skins</a> 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.
+ </div>
+</div>
+<a name="N10279"></a><a name="skin-configuration"></a>
+<h3 class="underlined_5">Configuration of skins</h3>
+<p>
+ All configuration is done via your project
+ <span class="codefrag">src/documentation/skinconf.xml</span> file.
+ It contains many comments to describe each capability.
+ Please read those, there is no point repeating here.
+ </p>
+<a name="N10286"></a><a name="new_skin"></a>
+<h3 class="underlined_5">Defining a new skin</h3>
+<p>Consider discussing your needs on the mailing lists. There may
+ be planned enhancements to the core skins. Also consider contributing
+ your extensions to the core skins, rather than write your own skin.
+ Bear in mind that you could be creating an update and management
+ issue. Anyway, ...
+ </p>
+<p>
+ Projects can define their own skin in the
+ <span class="codefrag">src/documentation/skins</span> directory (or wherever
+ <span class="codefrag">${project.skins-dir}</span> points). The default sitemap assumes a
+ certain skin layout, so the easiest way to create a new skin is by
+ copying an existing Forrest skin. For example, copy
+ <span class="codefrag">forrest/src/core/context/skins/pelt</span>
+ to your project area at
+ <span class="codefrag">src/documentation/skins/my-fancy-skin</span> and add
+ <span class="codefrag">project.skin=my-fancy-skin</span> to forrest.properties
+ </p>
+<p>
+ The two most interesting XSLT stylesheets involved are:
+ </p>
+<dl>
+
+<dt>
+<span class="codefrag">xslt/html/document2html.xsl</span>
+</dt>
+
+<dd>
+ This stylesheet is applied to individual Forrest xdocs XML files, and
+ converts them to HTML suitable for embedding in a larger HTML page.
+ </dd>
+
+<dt>
+<span class="codefrag">xslt/html/site2xhtml.xsl</span>
+</dt>
+
+<dd>
+ This stylesheet generates the final HTML file from an intermediate
+ 'site' structure produced by the other stylesheets. It defines the general
+ layout, and adds the header and footer.
+ </dd>
+
+</dl>
+<p>
+ Typically there is a lot of commonality between skins. XSLT
+ provides an 'import' mechanism whereby one XSLT can extend another.
+ Forrest XSLTs typically 'import' from a common base:
+ </p>
+<pre class="code">
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+ <xsl:import href="../../../common/xslt/html/document2html.xsl"/>
+
+ <strong>... overrides of default templates ...</strong>
+</xsl:stylesheet></pre>
+<p>In order to use this feature in your custom skins you must copy
+ the common skin from the forrest distribution into your custom skins
+ directory (from <span class="codefrag">forrest/src/core/context/skins/common</span>).
+ This will protect your skin from changes in the Forrest common skin,
+ but you must remember to update this skin in order to take advantage
+ of new features added over time by the Forrest team.</p>
+<p>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.</p>
+</div>
+
+
+<a name="N102CA"></a><a name="webapp"></a>
+<h2 class="underlined_10">Interactive Forrest: faster turnaround when developing your docs</h2>
+<div class="section">
+<p>
+ In comparison to simpler tools (like
+ <a class="external" href="http://jakarta.apache.org/velocity/anakia.html">Anakia</a>) the Cocoon command-line mode
+ (and hence Forrest command-line mode) is slow.
+ As the <a href="../docs/dreams.html">dream list</a> notes, Forrest 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.
+ </p>
+<a name="N102DB"></a><a name="forrest_run"></a>
+<h3 class="underlined_5">Running as a webapp</h3>
+<p>
+ Type '<span class="codefrag">forrest run</span>' in your project root to start Forrest's
+ built-in Jetty web server. Once it has started, point your browser at
+ <a class="external" href="http://localhost:8888/">http://localhost:8888/</a>, which
+ will show your website, rendered on demand as each link is followed.
+ </p>
+<p>(Alternatively, if you wish to run Forrest from within an existing
+ servlet container, type <span class="codefrag">forrest webapp</span> to build an open
+ webapp in <span class="codefrag">build/webapp/</span>)
+ </p>
+<a name="N102F4"></a><a name="using_webapp"></a>
+<h4>Using the webapp</h4>
+<p>
+ You can now edit the XML content in
+ <span class="codefrag">build/webapp/content/xdocs</span> and see the changes
+ immediately in the browser.
+ </p>
+</div>
+
+<a name="N10303"></a><a name="invoking_from_ant"></a>
+<h2 class="underlined_10">Invoking Forrest from Ant</h2>
+<div class="section">
+<p>
+ Ant has an
+ <a class="external" href="http://ant.apache.org/manual/CoreTasks/import.html"><import></a>
+ task which can be used to invoke Forrest from Ant. All targets and properties
+ are imported and can be used in your project build. Here is a simple example:
+ </p>
+<pre class="code">
+<project name="myproject" default="hello">
+ <!-- FORREST_HOME must be set as an environment variable -->
+ <property environment="env"/>
+ <property name="forrest.home" value="${env.FORREST_HOME}"/>
+ <import file="${env.FORREST_HOME}/forrest.build.xml"/>
+
+ <!-- 'site' is a target imported from forrest.build.xml -->
+ <target name="post-build" depends="site">
+ <echo>something here</echo>
+ </target>
+</project>
+ </pre>
+<p>Because you are using your own version
+ of Ant to do Forrest's work, you will need to provide the
+ supporting catalog entity resolver:
+ '<span class="codefrag">cp forrest/lib/core/xml-commons-resolver-1.1.jar $ANT_HOME/lib</span>'
+ </p>
+<p>(Note: The technique described above requires Ant 1.6+ otherwise the <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: <span class="codefrag">forrest -f myproject.xml</span>.
+ This will not run forrest; it will just use Forrest's Ant to execute
+ your buildfile.)
+ </p>
+<p>
+ Another option is to use the Forrest Antlet from the Krysalis Project's <a class="external" href="http://antworks.sourceforge.net/importer/">Antworks Importer</a>.
+ </p>
+<p>
+ The <a href="../docs/forrestbot.html">Forrestbot</a> provides workstages
+ to get source, build, deploy, and notify. This is very useful for
+ automating builds; you may want to consider using the Forrestbot.
+ </p>
+</div>
+
+</div>
+<!--+
+ |end content
+ +-->
+<div class="clearboth"> </div>
+</div>
+<div id="footer">
+<!--+
+ |start bottomstrip
+ +-->
+<div class="lastmodified">
+<script type="text/javascript"><!--
+document.write("Last Published: " + document.lastModified);
+// --></script>
+</div>
+<div class="copyright">
+ Copyright © 2002-2004 The Apache Software Foundation.</div>
+<!--+
+ |end bottomstrip
+ +-->
+</div>
+</body>
+</html>
Propchange: forrest/site/0.6/docs/your-project.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/0.6/docs/your-project.pdf
URL: http://svn.apache.org/viewcvs/forrest/site/0.6/docs/your-project.pdf?view=auto&rev=160902
==============================================================================
Binary file - no diff available.
Propchange: forrest/site/0.6/docs/your-project.pdf
------------------------------------------------------------------------------
svn:mime-type = application/pdf
Added: forrest/site/0.6/dtd/.htaccess
URL: http://svn.apache.org/viewcvs/forrest/site/0.6/dtd/.htaccess?view=auto&rev=160902
==============================================================================
--- forrest/site/0.6/dtd/.htaccess (added)
+++ forrest/site/0.6/dtd/.htaccess Mon Apr 11 08:11:56 2005
@@ -0,0 +1,51 @@
+# The reason for this .htaccess is to deliver DTDs and associated resources
+# to some impoverished XML tools that do not use the Catalog Entity Resolver.
+# We do make every effort to encourage the latter. See ./index.html
+#
+#--------------------------------------------------------------------------
+# NOTE: There is a problem with getting the correct media-types ...
+# http://svn.apache.org/repos/asf/forrest/trunk/.../*.dtd
+# Currently the server just delivers text/plain
+# We can do 'svn propset svn:mime-type' for the *.dtd etc.
+# which will cause them to be delivered properly.
+# However there is an Issue for SVN (#1233) whereby the files will be seen
+# by SVN as binary, hence no diffs.
+# Please vote for http://subversion.tigris.org/issues/show_bug.cgi?id=1233
+#
+# So the workaround is to use ViewCVS to explicity set the media-type.
+#--------------------------------------------------------------------------
+
+# Get the content straight out of ViewCVS and use the appropriate media type:
+# See http://www.faqs.org/rfcs/rfc3023.html
+# FIXME: Verify these media types and maybe add charset
+#
+RewriteEngine On
+RewriteRule "(.*)\.dtd$" "http://svn.apache.org/viewcvs.cgi/*checkout*/forrest/trunk/src/core/context/resources/schema/dtd/$1.dtd?content-type=application/xml-dtd&root=Apache-SVN" [P]
+RewriteRule "(.*)\.mod$" "http://svn.apache.org/viewcvs.cgi/*checkout*/forrest/trunk/src/core/context/resources/schema/dtd/$1.mod?content-type=application/xml-dtd&root=Apache-SVN" [P]
+RewriteRule "(.*)\.pen$" "http://svn.apache.org/viewcvs.cgi/*checkout*/forrest/trunk/src/core/context/resources/schema/dtd/$1.pen?content-type=application/xml-external-parsed-entity&root=Apache-SVN" [P]
+RewriteRule "(.*)\.ent$" "http://svn.apache.org/viewcvs.cgi/*checkout*/forrest/trunk/src/core/context/resources/schema/dtd/$1.ent?content-type=application/xml-external-parsed-entity&root=Apache-SVN" [P]
+
+#--------------------------------------------------------------------------
+# NOTE: The following was suggested by someone to the forrest-dev
+# and not yet investigated.
+#--------------------------------------------------------------------------
+
+# FIXME: Is this Proxy stuff sufficient?
+
+# FIXME: Cache stuff is not yet working
+#
+## Now, since ViewCVS is slower than httpd, make sure we cache it
+#CacheEnable mem /dtd
+
+## for a day
+#CacheDefaultExpire 86400
+# MCacheSize 4096
+# MCacheMaxObjectCount 100
+# MCacheMinObjectSize 1
+# MCacheMaxObjectSize 2048
+
+## and in case your client is a good web citizen, tell the proxies
+## to avoid calling us, since we guarantee that the content is fresh
+## for a day
+#ExpiresActive On
+#ExpiresDefault "access plus 1 day"
Propchange: forrest/site/0.6/dtd/.htaccess
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/0.6/dtd/index.html
URL: http://svn.apache.org/viewcvs/forrest/site/0.6/dtd/index.html?view=auto&rev=160902
==============================================================================
--- forrest/site/0.6/dtd/index.html (added)
+++ forrest/site/0.6/dtd/index.html Mon Apr 11 08:11:56 2005
@@ -0,0 +1,19 @@
+<html>
+<head>
+ <title>Apache Document Type Definitions</title>
+</head>
+<body>
+ <h1>Apache Document Type Definitions</h1>
+
+ <p>
+ If you are here looking for the Apache Document DTDs
+ then you shouldn't be :-)
+ See <a href="http://forrest.apache.org/docs/catalog.html">Using Catalog Entity Resolver for local DTDs</a>.
+ </p>
+
+ <p>
+ That said, you can find the relevant DTDs using the naming convention
+ "forrest.apache.org/dtd/document-v13.dtd" etc.
+ </p>
+</body>
+</html>
Propchange: forrest/site/0.6/dtd/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/0.6/dtd/readme.txt
URL: http://svn.apache.org/viewcvs/forrest/site/0.6/dtd/readme.txt?view=auto&rev=160902
==============================================================================
--- forrest/site/0.6/dtd/readme.txt (added)
+++ forrest/site/0.6/dtd/readme.txt Mon Apr 11 08:11:56 2005
@@ -0,0 +1,7 @@
+There is a .htaccess in this directory.
+Its purpose is to deliver DTDs and associated resources to some
+impoverished XML tools that do not use the Catalog Entity Resolver.
+
+FIXME: There are similar .htaccess at both
+forrest.apache.org/dtd/ and forrest.apache.org/entity/
+until we merge the entity sets into the /dtd/ directory.
Propchange: forrest/site/0.6/dtd/readme.txt
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/0.6/entity/.htaccess
URL: http://svn.apache.org/viewcvs/forrest/site/0.6/entity/.htaccess?view=auto&rev=160902
==============================================================================
--- forrest/site/0.6/entity/.htaccess (added)
+++ forrest/site/0.6/entity/.htaccess Mon Apr 11 08:11:56 2005
@@ -0,0 +1,10 @@
+# The reason for this .htaccess is to deliver DTDs and associated resources
+# to some impoverished XML tools that do not use the Catalog Entity Resolver.
+# We do make every effort to encourage the latter. See ./index.html
+#
+#--------------------------------------------------------------------------
+# NOTE: See the discussion in ../dtd/.htaccess
+#--------------------------------------------------------------------------
+
+RewriteEngine On
+RewriteRule "(.*)\.pen$" "http://svn.apache.org/viewcvs.cgi/*checkout*/forrest/trunk/src/core/context/resources/schema/entity/$1.pen?content-type=application/xml-external-parsed-entity&root=Apache-SVN" [P]
Propchange: forrest/site/0.6/entity/.htaccess
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/0.6/entity/index.html
URL: http://svn.apache.org/viewcvs/forrest/site/0.6/entity/index.html?view=auto&rev=160902
==============================================================================
--- forrest/site/0.6/entity/index.html (added)
+++ forrest/site/0.6/entity/index.html Mon Apr 11 08:11:56 2005
@@ -0,0 +1,19 @@
+<html>
+<head>
+ <title>Apache Document Type Definitions</title>
+</head>
+<body>
+ <h1>Apache Document Type Definitions</h1>
+
+ <p>
+ If you are here looking for the Apache Document DTDs
+ then you shouldn't be :-)
+ See <a href="http://forrest.apache.org/docs/catalog.html">Using Catalog Entity Resolver for local DTDs</a>.
+ </p>
+
+ <p>
+ That said, you can find the relevant DTDs using the naming convention
+ "forrest.apache.org/dtd/document-v13.dtd" etc.
+ </p>
+</body>
+</html>
Propchange: forrest/site/0.6/entity/index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/0.6/entity/readme.txt
URL: http://svn.apache.org/viewcvs/forrest/site/0.6/entity/readme.txt?view=auto&rev=160902
==============================================================================
--- forrest/site/0.6/entity/readme.txt (added)
+++ forrest/site/0.6/entity/readme.txt Mon Apr 11 08:11:56 2005
@@ -0,0 +1,7 @@
+There is a .htaccess in this directory.
+Its purpose is to deliver DTDs and associated resources to some
+impoverished XML tools that do not use the Catalog Entity Resolver.
+
+FIXME: There are similar .htaccess at both
+forrest.apache.org/dtd/ and forrest.apache.org/entity/
+until we merge the entity sets into the /dtd/ directory.
Propchange: forrest/site/0.6/entity/readme.txt
------------------------------------------------------------------------------
svn:eol-style = native