forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: r168512 [2/5] - /forrest/site/0.6 /forrest/site/0.7 /forrest/site/0.7/docs /forrest/site/0.7/docs/howto /forrest/site/0.7/docs/plugins /forrest/site/0.7/skin /forrest/site/0.7/skin/images
Date Fri, 06 May 2005 03:54:35 GMT
Modified: forrest/site/0.7/docs/faq.html
URL: http://svn.apache.org/viewcvs/forrest/site/0.7/docs/faq.html?rev=168512&r1=168511&r2=168512&view=diff
==============================================================================
--- forrest/site/0.7/docs/faq.html (original)
+++ forrest/site/0.7/docs/faq.html Thu May  5 20:54:30 2005
@@ -294,40 +294,26 @@
 <a href="#getting_started">1. Getting Started and Building Forrest</a>
 <ul class="minitoc">
 <li>
-<a href="#overview">1.1. 
-        Where can I read an overview about how to work with Forrest?
-      </a>
+<a href="#overview">1.1.  Where can I read an overview about how to work with Forrest? </a>
 </li>
 <li>
-<a href="#requirements">1.2. 
-        What are the system requirements for Forrest?
-      </a>
+<a href="#requirements">1.2.  What are the system requirements for Forrest? </a>
 </li>
 <li>
-<a href="#cvs">1.3. 
-        The old xml-forrest CVS code repository seems to be stale. What happened?
-      </a>
+<a href="#cvs">1.3.  The old xml-forrest CVS code repository seems to be stale. What happened? </a>
 </li>
 <li>
-<a href="#svn">1.4. 
-        How can I use SVN to keep up to date with the latest codebase?
-      </a>
+<a href="#svn">1.4.  How can I use SVN to keep up to date with the latest codebase? </a>
 </li>
 <li>
-<a href="#single-document">1.5. 
-        What is the best way to generate "standalone documents" using Forrest?
-      </a>
+<a href="#single-document">1.5.  What is the best way to generate "standalone documents" using Forrest? </a>
 </li>
 <li>
-<a href="#cygwin_mutex_error">1.6. 
-        When running ./build.sh in cygwin, I get an error:
-        cygpath.exe: *** can't create title mutex, Win32 error 6. 
-      </a>
+<a href="#cygwin_mutex_error">1.6.  When running ./build.sh in cygwin, I get an error: cygpath.exe:
+          *** can't create title mutex, Win32 error 6. </a>
 </li>
 <li>
-<a href="#maxmemory">1.7. 
-        How can I specify the amount of memory to be used by Java?
-      </a>
+<a href="#maxmemory">1.7.  How can I specify the amount of memory to be used by Java? </a>
 </li>
 </ul>
 </li>
@@ -338,36 +324,40 @@
 <a href="#edit-content">2.1. What tools can be used to edit the content?</a>
 </li>
 <li>
-<a href="#PDF-output">2.2. How can I generate one pdf-file out of
-      the whole site or selected pages of the site?</a>
+<a href="#PDF-output">2.2. How can I generate one pdf-file out of the whole site or selected pages of the site?</a>
 </li>
 <li>
 <a href="#pageBreaks">2.3. How do I insert page breaks into documents?</a>
 </li>
 <li>
-<a href="#clickable-email-address">2.4. How can I generate html-pages to show a 
-      'clickable' email-address (of the author-element)?</a>
+<a href="#clickable-email-address">2.4. How can I generate html-pages to show a 'clickable' email-address (of the
+        author-element)?</a>
 </li>
 <li>
-<a href="#link_raw">2.5. How do I link to raw files such as config.txt and brochure.pdf?
-      </a>
+<a href="#link_raw">2.5. How do I link to raw files such as config.txt and brochure.pdf? </a>
 </li>
 <li>
 <a href="#pdf_images">2.6. Images don't display in PDFs. How do I fix this?</a>
 </li>
 <li>
-<a href="#index.html">2.7. 
-        The tab link in my site incorrectly assumes that 'index.html' is present in
-        the linked-to directory. How do I fix this?
-      </a>
+<a href="#index.html">2.7.  The tab link in my site incorrectly assumes that 'index.html' is present in the
+        linked-to directory. How do I fix this? </a>
 </li>
 <li>
-<a href="#label-entity">2.8. 
-        How to use special characters in the labels of the site.xml file?
-      </a>
+<a href="#defaultFileName">2.8.  How can I change the default file name that Forrest will look for when I request a
+        URL like http://myserver or http://myserver/mydir/? </a>
 </li>
 <li>
-<a href="#encoding">2.9. Does Forrest handle accents for non-English languages?</a>
+<a href="#defaultStartPage">2.9.  How can I use a start-up-page other than index.html? </a>
+</li>
+<li>
+<a href="#label-entity">2.10.  How to use special characters in the labels of the site.xml file? </a>
+</li>
+<li>
+<a href="#encoding">2.11. Does Forrest handle accents for non-English languages?</a>
+</li>
+<li>
+<a href="#cleanSite">2.12.  How can I make Forrest properly clean up the build/site-directory? </a>
 </li>
 </ul>
 </li>
@@ -375,56 +365,43 @@
 <a href="#technical">3. Technical</a>
 <ul class="minitoc">
 <li>
-<a href="#proxy_config">3.1. I'm behind a proxy and it's preventing Plugins from 
-      being downloaded, what should I do?</a>
+<a href="#proxy_config">3.1. I'm behind a proxy and it's preventing Plugins from being downloaded, what should I
+        do?</a>
 </li>
 <li>
-<a href="#CVS_revison_tags">3.2. How can I generate html-pages to show the
-      revision tag of cvs?</a>
+<a href="#CVS_revison_tags">3.2. How can I generate html-pages to show the revision tag of cvs?</a>
 </li>
 <li>
-<a href="#cli-xconf">3.3. 
-        How to control the processing of URIs by Cocoon, e.g. exclude
-        certain URIs, include other additional ones.
-      </a>
+<a href="#cli-xconf">3.3.  How to control the processing of URIs by Cocoon, e.g. exclude certain URIs, include
+        other additional ones. </a>
 </li>
 <li>
-<a href="#ignoring_javadocs">3.4. 
-        How do I stop Forrest breaking on links to external files that may not
-        exist, like javadocs?
-      </a>
+<a href="#ignoring_javadocs">3.4.  How do I stop Forrest breaking on links to external files that may not exist, like
+        javadocs? </a>
 </li>
 <li>
-<a href="#claimed_patterns">3.5. Some of my files are not being processed because they use
-      common filenames.
-      </a>
+<a href="#claimed_patterns">3.5. Some of my files are not being processed because they use common filenames. </a>
 </li>
 <li>
-<a href="#build_msg_a">3.6. What do the symbols and numbers mean when Forrest lists each
-        document that it has built?
-      </a>
+<a href="#build_msg_a">3.6. What do the symbols and numbers mean when Forrest lists each document that it has
+        built? </a>
 </li>
 <li>
-<a href="#headless_operation">3.7. 
-        When generating PNG images from SVG, I get an error: Can't connect to X11 window server using ':0.0' as the value of the DISPLAY variable.
-      </a>
+<a href="#headless_operation">3.7.  When generating PNG images from SVG, I get an error: Can't connect to X11 window
+        server using ':0.0' as the value of the DISPLAY variable. </a>
 </li>
 <li>
-<a href="#catalog">3.8. 
-        How do i configure my favourite XML editor or parser to find the
-        local Forrest DTDs?
-      </a>
+<a href="#catalog">3.8.  How do i configure my favourite XML editor or parser to find the local Forrest
+        DTDs? </a>
 </li>
 <li>
-<a href="#skin">3.9. 
-        How to make the site look better and change its skin?
-      </a>
+<a href="#skin">3.9.  How to make the site look better and change its skin? </a>
 </li>
 <li>
 <a href="#xsp">3.10. How do I enable XSP processing?</a>
 </li>
 <li>
-<a href="#breadcrumbs">3.11. How do breadcrumbs work?  Why don't they work locally?</a>
+<a href="#breadcrumbs">3.11. How do breadcrumbs work? Why don't they work locally?</a>
 </li>
 <li>
 <a href="#run_port">3.12. How do I make forrest run listen on a different port?</a>
@@ -435,9 +412,7 @@
 <a href="#old_faqs">4. Older version: 0.6</a>
 <ul class="minitoc">
 <li>
-<a href="#old_claimed_patterns">4.1. Some of my files are not being processed because they use
-      common filenames.
-      </a>
+<a href="#old_claimed_patterns">4.1. Some of my files are not being processed because they use common filenames. </a>
 </li>
 </ul>
 </li>
@@ -445,35 +420,23 @@
 <a href="#general">5. General</a>
 <ul class="minitoc">
 <li>
-<a href="#generating_menus">5.1. What is the relationship between site.xml and
-        book.xml?
-      </a>
+<a href="#generating_menus">5.1. What is the relationship between site.xml and book.xml? </a>
 </li>
 <li>
-<a href="#docbook">5.2. 
-        How do I use DocBook as the xml documentation format?
-      </a>
+<a href="#docbook">5.2.  How do I use DocBook as the xml documentation format? </a>
 </li>
 <li>
-<a href="#version">5.3. 
-        How to report which version of Forrest is being used and the
-        properties that are set?
-      </a>
+<a href="#version">5.3.  How to report which version of Forrest is being used and the properties that are
+        set? </a>
 </li>
 <li>
-<a href="#logs">5.4. 
-        Where are the log files to find more infomation about errors?
-      </a>
+<a href="#logs">5.4.  Where are the log files to find more infomation about errors? </a>
 </li>
 <li>
-<a href="#how_can_I_help">5.5. 
-        How to help?
-      </a>
+<a href="#how_can_I_help">5.5.  How to help? </a>
 </li>
 <li>
-<a href="#patch">5.6. 
-        How to contribute a patch?
-      </a>
+<a href="#patch">5.6.  How to contribute a patch? </a>
 </li>
 </ul>
 </li>
@@ -487,114 +450,79 @@
 <a name="N1000C"></a><a name="getting_started"></a>
 <h3 class="underlined_5">1. Getting Started and Building Forrest</h3>
 <a name="N10010"></a><a name="overview"></a>
-<h4 class="faq">1.1. 
-        Where can I read an overview about how to work with Forrest?
-      </h4>
+<h4 class="faq">1.1.  Where can I read an overview about how to work with Forrest? </h4>
 <div align="right">
 <a href="#overview-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>
-          See the <a href="../docs/your-project.html">Using Forrest</a> guide.
-        </p>
+<p> See the <a href="../docs/your-project.html">Using Forrest</a> guide. </p>
 </div>
 <a name="N1001C"></a><a name="requirements"></a>
-<h4 class="faq">1.2. 
-        What are the system requirements for Forrest?
-      </h4>
+<h4 class="faq">1.2.  What are the system requirements for Forrest? </h4>
 <div align="right">
 <a href="#requirements-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>
-          Forrest includes everything necessary to build and run, except
-          of course for Java. In addition to all the Cocoon JARs, Forrest
-          includes and uses its own version of Ant. Java 1.4+ is required.
-        </p>
+<p> Forrest includes everything necessary to build and run, except of course for Java. In
+          addition to all the Cocoon JARs, Forrest includes and uses its own version of Ant. Java
+          1.4+ is required. </p>
 </div>
 <a name="N10024"></a><a name="cvs"></a>
-<h4 class="faq">1.3. 
-        The old xml-forrest CVS code repository seems to be stale. What happened?
-      </h4>
+<h4 class="faq">1.3.  The old xml-forrest CVS code repository seems to be stale. What happened? </h4>
 <div align="right">
 <a href="#cvs-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>
-          Forrest switched from a CVS code repository to SVN (subversion)
-          code repository. The old CVS repository is not kept current.
-        </p>
+<p> Forrest switched from a CVS code repository to SVN (subversion) code repository. The old
+          CVS repository is not kept current. </p>
 </div>
 <a name="N1002C"></a><a name="svn"></a>
-<h4 class="faq">1.4. 
-        How can I use SVN to keep up to date with the latest codebase?
-      </h4>
+<h4 class="faq">1.4.  How can I use SVN to keep up to date with the latest codebase? </h4>
 <div align="right">
 <a href="#svn-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>
-          Follow these <a href="../docs/build.html">Building Forrest</a> notes.
-        </p>
-<p>
-          The <a href="../docs/your-project.html">Using Forrest</a> guide provides
-          further step-by-step assistance in getting started with Forrest for your project.
-        </p>
+<p> Follow these <a href="../docs/build.html">Building Forrest</a> notes. </p>
+<p> The <a href="../docs/your-project.html">Using Forrest</a> guide provides further
+          step-by-step assistance in getting started with Forrest for your project. </p>
 </div>
 <a name="N1003F"></a><a name="single-document"></a>
-<h4 class="faq">1.5. 
-        What is the best way to generate "standalone documents" using Forrest?
-      </h4>
+<h4 class="faq">1.5.  What is the best way to generate "standalone documents" using Forrest? </h4>
 <div align="right">
 <a href="#single-document-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>
-          forrest site -Dproject.start-uri=myfile.pdf 
-        </p>
-<p>
-          The <a href="../docs/your-project.html">Using Forrest</a> guide provides
-          further step-by-step assistance in getting started with Forrest for your project.
-        </p>
+<p> forrest site -Dproject.start-uri=myfile.pdf </p>
+<p> The <a href="../docs/your-project.html">Using Forrest</a> guide provides further
+          step-by-step assistance in getting started with Forrest for your project. </p>
 </div>
 <a name="N1004E"></a><a name="cygwin_mutex_error"></a>
-<h4 class="faq">1.6. 
-        When running ./build.sh in cygwin, I get an error:
-        cygpath.exe: *** can't create title mutex, Win32 error 6. 
-      </h4>
+<h4 class="faq">1.6.  When running ./build.sh in cygwin, I get an error: cygpath.exe:
+          *** can't create title mutex, Win32 error 6. </h4>
 <div align="right">
 <a href="#cygwin_mutex_error-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>
-          This 
-          <a href="http://issues.cocoondev.org/secure/ViewIssue.jspa?key=FOR-10">appears
-            to be a bug in cygwin</a>. Please use the .bat script instead.
-        </p>
+<p> This <a href="http://issues.cocoondev.org/secure/ViewIssue.jspa?key=FOR-10">appears
+            to be a bug in cygwin</a>. Please use the .bat script instead. </p>
 </div>
 <a name="N10060"></a><a name="maxmemory"></a>
-<h4 class="faq">1.7. 
-        How can I specify the amount of memory to be used by Java?
-      </h4>
+<h4 class="faq">1.7.  How can I specify the amount of memory to be used by Java? </h4>
 <div align="right">
 <a href="#maxmemory-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>
-         There are two ways to control this.  If you get an OutOfMemoryError when Cocoon is generating pages,
-         see the first paragraph.  If you get an OutOfMemoryError when outside of Cocoon (e.g., copying raw
-         files), see the second paragraph.
-        </p>
-<p>
-         The <span class="codefrag">maxmemory</span> property in the <span class="codefrag">forrest.properties</span> file controls how much
-         memory Cocoon uses. Like many other properties you can copy them from the default configuration at
-         <span class="codefrag">src/core/fresh-site/forrest.properties</span>
+<p> There are two ways to control this. If you get an OutOfMemoryError when Cocoon is
+          generating pages, see the first paragraph. If you get an OutOfMemoryError when outside of
+          Cocoon (e.g., copying raw files), see the second paragraph. </p>
+<p> The <span class="codefrag">maxmemory</span> property in the <span class="codefrag">forrest.properties</span> file controls
+          how much memory Cocoon uses. Like many other properties you can copy them from the default
+          configuration at <span class="codefrag">src/core/fresh-site/forrest.properties</span>
         
 </p>
-<p>
-         Set the <span class="codefrag">ANT_OPTS</span> environment variable before you run forrest.  The exact value you set
-         it to is dependant on your JVM, but something like <span class="codefrag">ANT_OPTS=-Xmx500M</span> will probably work.
-        </p>
+<p> Set the <span class="codefrag">ANT_OPTS</span> environment variable before you run forrest. The exact
+          value you set it to is dependant on your JVM, but something like
+          <span class="codefrag">ANT_OPTS=-Xmx500M</span> will probably work. </p>
 </div>
 <a name="N1007D"></a><a name="content_faqs"></a>
 <h3 class="underlined_5">2. Content Creation</h3>
@@ -604,27 +532,18 @@
 <a href="#edit-content-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>If you are using the Apache Forrest xml
-          <a href="../docs/dtd-docs.html">document format</a> or DocBook
-          or other xml document types, then you can use any text editor
-          or even a dedicated xml editor. You must ensure valid xml. See our
-          <a href="../docs/catalog.html">configuration notes</a>
-          for various editors.
-        </p>
-<p>There are content management systems like
-         <a href="http://lenya.apache.org/">Apache Lenya</a>.
-        </p>
-<p>Remember that Forrest can also use other source formats, such as
-          OpenOffice.org docs or JSPWiki. Use the appropriate editor for those
-          document types and ensure that the document stucture is consistent.
-          Forrest can also use "html" as the source format, in which case you
-          can use text editors or "html editors" such as the one provided
-          with the Mozilla web browser.
-        </p>
+<p>If you are using the Apache Forrest xml <a href="../docs/dtd-docs.html">document format</a>
+          or DocBook or other xml document types, then you can use any text editor or even a
+          dedicated xml editor. You must ensure valid xml. See our <a href="../docs/catalog.html">configuration notes</a> for various editors. </p>
+<p>There are content management systems like <a href="http://lenya.apache.org/">Apache Lenya</a>. </p>
+<p>Remember that Forrest can also use other source formats, such as OpenOffice.org docs or
+          JSPWiki. Use the appropriate editor for those document types and ensure that the document
+          stucture is consistent. Forrest can also use "html" as the source format, in which case
+          you can use text editors or "html editors" such as the one provided with the Mozilla web
+          browser. </p>
 </div>
 <a name="N1009B"></a><a name="PDF-output"></a>
-<h4 class="faq">2.2. How can I generate one pdf-file out of
-      the whole site or selected pages of the site?</h4>
+<h4 class="faq">2.2. How can I generate one pdf-file out of the whole site or selected pages of the site?</h4>
 <div align="right">
 <a href="#PDF-output-menu">^</a>
 </div>
@@ -637,16 +556,11 @@
     &lt;all_sitePDF label="Full PDF" href="wholesite.pdf"/&gt;  
      ...
   &lt;/about&gt;</pre>
-<p>
-       In this case the menu labeled "About" will have 2 new items: 
-       "Full PDF" and "Full HTML". (See also
-       <a href="../docs/howto/howto-pdf-tab.html">How to create a PDF document for each tab</a>.)
-       </p>
-<p>
-         This assumes that you use the
-         <a href="../docs/linking.html">site.xml</a> method for your site
-         structure and navigation, rather than the old book.xml method.
-       </p>
+<p> In this case the menu labeled "About" will have 2 new items: "Full PDF" and "Full HTML".
+          (See also <a href="../docs/howto/howto-pdf-tab.html">How to create a PDF document for each
+          tab</a>.) </p>
+<p> This assumes that you use the <a href="../docs/linking.html">site.xml</a> method for your
+          site structure and navigation, rather than the old book.xml method. </p>
 </div>
 <a name="N100B5"></a><a name="pageBreaks"></a>
 <h4 class="faq">2.3. How do I insert page breaks into documents?</h4>
@@ -654,156 +568,178 @@
 <a href="#pageBreaks-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>Page breaks do not make a great deal of sense in HTML documents
-        intended for display on a screen. However, PDF documents are intended
-        for printing and therefore page breaks can be important.</p>
-<p>To insert a page break in a PDF document simply add 
-        <em>pageBreakBefore</em> or <em>pageBreakAfter</em> to the class
-        attribute of a section.</p>
-<p>If you want these classes to be processed in your HTML documents
-        as well you should add the following to the <span class="codefrag">extra-css</span>
-        element in your projects <span class="codefrag">skinconf.xml</span>
-</p>
-<pre class="code">
-        .pageBreakBefore {
-          margin-bottom: 0;
-          page-break-before: always;
-        } 
-        
-        .pageBreakAfter {
-          margin-bottom: 0;
-          page-break-after: always;
-        }
-        </pre>
-</div>
-<a name="N100D2"></a><a name="clickable-email-address"></a>
-<h4 class="faq">2.4. How can I generate html-pages to show a 
-      'clickable' email-address (of the author-element)?</h4>
+<p>Page breaks do not make a great deal of sense in HTML documents intended for display on a
+          screen. However, PDF documents are intended for printing and therefore page breaks can be
+          important.</p>
+<p>To insert a page break in a PDF document simply add <em>pageBreakBefore</em> or
+            <em>pageBreakAfter</em> to the class attribute of a section.</p>
+<p>If you want these classes to be processed in your HTML documents as well you should add
+          the following to the <span class="codefrag">extra-css</span> element in your projects
+          <span class="codefrag">skinconf.xml</span>
+        
+</p>
+<pre class="code"> .pageBreakBefore { margin-bottom: 0; page-break-before: always; } .pageBreakAfter {
+          margin-bottom: 0; page-break-after: always; } </pre>
+</div>
+<a name="N100D3"></a><a name="clickable-email-address"></a>
+<h4 class="faq">2.4. How can I generate html-pages to show a 'clickable' email-address (of the
+        author-element)?</h4>
 <div align="right">
 <a href="#clickable-email-address-menu">^</a>
 </div>
 <div style="margin-left: 15px">
 <p>You would override <span class="codefrag">
-       $FORREST_HOME/main/webapp/skins/common/xslt/html/document2html.xsl</span>
-       and edit the "headers/authors" template.
-       </p>
-</div>
-<a name="N100DD"></a><a name="link_raw"></a>
-<h4 class="faq">2.5. How do I link to raw files such as config.txt and brochure.pdf?
-      </h4>
+            $FORREST_HOME/main/webapp/skins/common/xslt/html/document2html.xsl</span> and edit the
+          "headers/authors" template. </p>
+</div>
+<a name="N100DE"></a><a name="link_raw"></a>
+<h4 class="faq">2.5. How do I link to raw files such as config.txt and brochure.pdf? </h4>
 <div align="right">
 <a href="#link_raw-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>
-          Place them in the <span class="codefrag">src/documentation/content</span> directory
-          and they will get copied into the output tree where you can link to
-          them. You can also have sub-directories there to reflect your xdocs
-          tree. See the samples documents when you 'forrest seed' a new
-          project for a demonstration of this ability.
-        </p>
-<p>
-         For example, if
-         <span class="codefrag">src/documentation/content/xdocs/tools/downloads.xml</span>
-         has a <span class="codefrag">&lt;link href="tool.zip"&gt;</span> then put
-         <span class="codefrag">tool.zip</span> in the
-         <span class="codefrag">src/documentation/content/tools/</span> directory.
-        </p>
-<p>
-          See the explanation and demonstration of "linking" in your local
-          'forrest seed' site.
+<p> Place them in the <span class="codefrag">src/documentation/content</span> directory and they will get
+          copied into the output tree where you can link to them. You can also have sub-directories
+          there to reflect your xdocs tree. See the samples documents when you 'forrest seed' a new
+          project for a demonstration of this ability. </p>
+<p> For example, if <span class="codefrag">src/documentation/content/xdocs/tools/downloads.xml</span> has a
+            <span class="codefrag">&lt;link href="tool.zip"&gt;</span> then put <span class="codefrag">tool.zip</span> in the
+            <span class="codefrag">src/documentation/content/tools/</span> directory. </p>
+<p> See the explanation and demonstration of "linking" in your local 'forrest seed' site.
         </p>
 </div>
-<a name="N100FA"></a><a name="pdf_images"></a>
+<a name="N100FB"></a><a name="pdf_images"></a>
 <h4 class="faq">2.6. Images don't display in PDFs. How do I fix this?</h4>
 <div align="right">
 <a href="#pdf_images-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>
-	  Forrest uses <a href="http://xml.apache.org/fop/">Apache FOP</a>
-          for rendering PDFs.  FOP cannot handle all image types natively, and
-          requires third-party jars to be added. FOP natively handles BMP, GIF,
-	  JPG, TIFF and EPS (with a few limitations). FOP can also handle SVG
-	  (via Batik!and PNG (see below). For details, see 
-	  <a href="http://xml.apache.org/fop/graphics.html">FOP Graphics
-          formats</a>
+<p> Forrest uses <a href="http://xml.apache.org/fop/">Apache FOP</a> for rendering
+          PDFs. FOP cannot handle all image types natively, and requires third-party jars to be
+          added. FOP natively handles BMP, GIF, JPG, TIFF and EPS (with a few limitations). FOP can
+          also handle SVG (via Batik!and PNG (see below). For details, see <a href="http://xml.apache.org/fop/graphics.html">FOP Graphics formats</a>
         
 </p>
 <p>To get PNGs working in PDFs with Jimi:</p>
 <ol>
           
-<li>Download Jimi from
-           <a href="http://java.sun.com/products/jimi/">http://java.sun.com/products/jimi/</a>
+<li>Download Jimi from <a href="http://java.sun.com/products/jimi/">http://java.sun.com/products/jimi/</a>
+          
 </li>
           
 <li>Unpack the Jimi distribution and copy JimiProClasses.zip to
-            <span class="codefrag">$FORREST/lib/optional/jimi-1.0.jar</span>.</li>
+              <span class="codefrag">$FORREST/lib/optional/jimi-1.0.jar</span>.</li>
         
 </ol>
-<p>Alternatively you can use JAI (Java Advanced Imaging API at 
-	  http://java.sun.com/products/java-media/jai). For more
-          info, see
-          <a href="http://xml.apache.org/fop/graphics.html#packages">FOP Graphics 
-          Packages</a>
+<p>Alternatively you can use JAI (Java Advanced Imaging API at
+          http://java.sun.com/products/java-media/jai). For more info, see <a href="http://xml.apache.org/fop/graphics.html#packages">FOP Graphics Packages</a>
         
 </p>
 <div class="frame note">
 <div class="label">Note</div>
-<div class="content">Due to Sun's licensing, we cannot redistribute Jimi or JAI with
-          Forrest.</div>
+<div class="content">Due to Sun's licensing, we cannot redistribute Jimi or JAI with Forrest.</div>
 </div>
 </div>
-<a name="N10126"></a><a name="index.html"></a>
-<h4 class="faq">2.7. 
-        The tab link in my site incorrectly assumes that 'index.html' is present in
-        the linked-to directory. How do I fix this?
-      </h4>
+<a name="N10128"></a><a name="index.html"></a>
+<h4 class="faq">2.7.  The tab link in my site incorrectly assumes that 'index.html' is present in the
+        linked-to directory. How do I fix this? </h4>
 <div align="right">
 <a href="#index.html-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>
-          In <span class="codefrag">tabs.xml</span>, use @href instead of @dir, and omit the
-          trailing '/'. Which file to serve is then a concern of the sitemap.
-          For example, if the "User Manual" tab should link to
-          <span class="codefrag">manual/Introduction.html</span> then
-          <span class="codefrag">tabs.xml</span> should contain:
-        </p>
+<p> In <span class="codefrag">tabs.xml</span>, use @href instead of @dir, and omit the trailing '/'. Which
+          file to serve is then a concern of the sitemap. For example, if the "User Manual" tab
+          should link to <span class="codefrag">manual/Introduction.html</span> then <span class="codefrag">tabs.xml</span> should
+          contain: </p>
 <pre class="code">
   &lt;tab label="User Manual" href="manual"/&gt;</pre>
-<p>
-          and add this rule to the sitemap:
-        </p>
+<p> and add this rule to the sitemap: </p>
 <pre class="code">
   &lt;map:match pattern="manual"&gt;
     &lt;map:redirect-to uri="manual/Introduction.html"/&gt;
   &lt;/map:match&gt;</pre>
 </div>
-<a name="N10142"></a><a name="label-entity"></a>
-<h4 class="faq">2.8. 
-        How to use special characters in the labels of the site.xml file?
-      </h4>
+<a name="N10144"></a><a name="defaultFileName"></a>
+<h4 class="faq">2.8.  How can I change the default file name that Forrest will look for when I request a
+        URL like http://myserver or http://myserver/mydir/? </h4>
+<div align="right">
+<a href="#defaultFileName-menu">^</a>
+</div>
+<div style="margin-left: 15px">
+<p>To change the default file name from 'index.html' (default) to 'overview.htm' you need to
+          make the following changes:</p>
+<ol>
+          
+<li> Find and open the file 'cli.xconf' in your forrest program directory tree </li>
+          
+<li> Replace 'index.html' in &lt;default-filename&gt;index.html&lt;/default-filename&gt;
+            with 'overview.html'. </li>
+          
+<li> Save the changes. </li>
+          
+<li> Open the file 'sitemap.xmap' in your project's 'src'-directory. </li>
+          
+<li> Add the following code just before the end of the pipelines-element:
+        &lt;map:pipeline&gt;
+          &lt;map:match type="regexp" pattern="^.+/$"&gt;
+&gt;&gt;           &lt;map:redirect-to uri="overview.html"/&gt;
+&gt;&gt;       &lt;/map:match&gt;
+        &lt;/map:pipeline&gt;
+          </li>
+          
+<li> Save the changes. </li>
+        
+</ol>
+<div class="frame note">
+<div class="label">Note</div>
+<div class="content">Please note that parts of these changes are global and will effect all your Forrests
+          run from this program directory. </div>
+</div>
+</div>
+<a name="N1016A"></a><a name="defaultStartPage"></a>
+<h4 class="faq">2.9.  How can I use a start-up-page other than index.html? </h4>
+<div align="right">
+<a href="#defaultStartPage-menu">^</a>
+</div>
+<div style="margin-left: 15px">
+<p>Forrest by default assumes that the first page (home page) of your site is named
+          index.html. Which is good because most web servers are configured to look for index.html
+          when you call a url like http://myserver.</p>
+<p>Like most settings in Forrest however this can be changed, for example when you want your
+          start-up-page for a CD-based documentation project to be named 'start.html'. </p>
+<p>To change the start page of a site:</p>
+<ol>
+          
+<li>Open the file 'sitemap.xmap' in your project's src-directory.</li>
+          
+<li>Add the following code just before the end of the pipelines-element:
+        &lt;map:pipeline&gt;
+          &lt;map:match pattern=""&gt;
+            &lt;map:redirect-to uri="start.html" /&gt;
+           &lt;/map:match&gt;
+        &lt;/map:pipeline&gt;
+          </li>
+          
+<li>Name the uri-attribute whatever you'd like your start page to be.</li>
+          
+<li>Don't forget to create that page and refer to it in your site.xml!</li>
+        
+</ol>
+</div>
+<a name="N10187"></a><a name="label-entity"></a>
+<h4 class="faq">2.10.  How to use special characters in the labels of the site.xml file? </h4>
 <div align="right">
 <a href="#label-entity-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>
-        Use the numeric values for character entities.
-        For example, rather than using
-        <span class="codefrag">&amp;ouml;</span> use
-        <span class="codefrag">&amp;#246;</span>
+<p> Use the numeric values for character entities. For example, rather than using
+            <span class="codefrag">&amp;ouml;</span> use <span class="codefrag">&amp;#246;</span>
         
 </p>
-<p>
-        See the
-        <a href="http://www.w3.org/TR/xhtml-modularization/dtd_module_defs.html#a_xhtml_character_entities">XHTML Character Entities</a>
-        and see more discussion at
-        <a href="http://issues.cocoondev.org/browse/FOR-244">Issue FOR-244</a>.
-        </p>
+<p> See the <a href="http://www.w3.org/TR/xhtml-modularization/dtd_module_defs.html#a_xhtml_character_entities">XHTML Character Entities</a> and see more discussion at <a href="http://issues.cocoondev.org/browse/FOR-244">Issue FOR-244</a>. </p>
 </div>
-<a name="N1015B"></a><a name="encoding"></a>
-<h4 class="faq">2.9. Does Forrest handle accents for non-English languages?</h4>
+<a name="N101A0"></a><a name="encoding"></a>
+<h4 class="faq">2.11. Does Forrest handle accents for non-English languages?</h4>
 <div align="right">
 <a href="#encoding-menu">^</a>
 </div>
@@ -818,108 +754,95 @@
 <li>tildes: &atilde; &ntilde; Ä© &otilde; Å©</li>
         
 </ul>
-<p>This is because sources for Forrest docs are xml documents, which can include any of these,
-          provided the encoding declared by the xml doc matches the actual encoding used in the file.
-          For example if you declare the default encoding:</p>
+<p>This is because sources for Forrest docs are xml documents, which can include any of
+          these, provided the encoding declared by the xml doc matches the actual encoding used in
+          the file. For example if you declare the default encoding:</p>
 <pre class="code">&lt;?xml version="1.0" encoding="UTF-8"?&gt;</pre>
-<p>but the file content is actually using ISO-8859-1 then you will
-           receive validation errors, especially if 
-           you include some non-ASCII characters.</p>
-<p>
-          This situation is commonly encountered when you edit the templates
-          created by <span class="codefrag">forrest seed</span> with your favorite 
-          (probably localized) editor without paying attention to the encoding,
-          or when you create a new file 
-          and simply copy the headers from another file.
-        </p>
-<p>Although UTF-8 is an encoding well-suited for most languages,
-          it is not usually the default in popular editors or systems.
-          In UNIX-like systems, most popular editors can handle different encodings to 
-          write the file in disk. With some editors the encoding of the file is preserved, while with others the default
-          is used regardless of the original encoding. In most cases the encoding used to write files
-          can be controlled by setting the environment variable <span class="codefrag">LANG</span>
-          to an appropriate value, for instance:
-        </p>
+<p>but the file content is actually using ISO-8859-1 then you will receive validation
+          errors, especially if you include some non-ASCII characters.</p>
+<p> This situation is commonly encountered when you edit the templates created by
+            <span class="codefrag">forrest seed</span> with your favorite (probably localized) editor without paying
+          attention to the encoding, or when you create a new file and simply copy the headers from
+          another file. </p>
+<p>Although UTF-8 is an encoding well-suited for most languages, it is not usually the
+          default in popular editors or systems. In UNIX-like systems, most popular editors can
+          handle different encodings to write the file in disk. With some editors the encoding of
+          the file is preserved, while with others the default is used regardless of the original
+          encoding. In most cases the encoding used to write files can be controlled by setting the
+          environment variable <span class="codefrag">LANG</span> to an appropriate value, for instance: </p>
 <pre class="code">[localhost]$ export LANG=en_US.UTF-8</pre>
-<p>Of course the <em>appropriate</em> way to set the encoding depends on the editor/OS, 
-          but ultimately relys on the user preferences. So you can use the encoding you prefer, as long as 
-          the <span class="codefrag">encoding</span> attribute of the xml declaration matches the actual encoding of the file. 
-          This means 
-          that if you are not willing to abandon ISO-8859-1 you can always use the following declaration instead:</p>
+<p>Of course the <em>appropriate</em> way to set the encoding depends on the editor/OS, but
+          ultimately relys on the user preferences. So you can use the encoding you prefer, as long
+          as the <span class="codefrag">encoding</span> attribute of the xml declaration matches the actual encoding
+          of the file. This means that if you are not willing to abandon ISO-8859-1 you can always
+          use the following declaration instead:</p>
 <pre class="code">&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;</pre>
-<p>Another option is to use "character entities" such as
-        <span class="codefrag">&amp;ouml;</span> (&ouml;) or the numeric form
-        <span class="codefrag">&amp;#246;</span> (&ouml;).
-        </p>
-<p>Another related issue is that your webserver needs to send http
-          headers with the matching charset definitions to the html page.
-        </p>
-<p>Here are some references which explain further:
-          <a href="http://orixo.com/events/gt2004/bios.html#torsten">GT2004 presentation by Torsten Schlabach</a> and 
-          <a href="http://www.alanwood.net/unicode/">Alan Wood's Unicode resources</a>.
-        </p>
+<p>Another option is to use "character entities" such as <span class="codefrag">&amp;ouml;</span>
+          (&ouml;) or the numeric form <span class="codefrag">&amp;#246;</span> (&ouml;). </p>
+<p>Another related issue is that your webserver needs to send http headers with the matching
+          charset definitions to the html page. </p>
+<p>Here are some references which explain further: <a href="http://orixo.com/events/gt2004/bios.html#torsten">GT2004 presentation by Torsten
+            Schlabach</a> and <a href="http://www.alanwood.net/unicode/">Alan Wood's Unicode
+            resources</a>. </p>
+</div>
+<a name="N101F2"></a><a name="cleanSite"></a>
+<h4 class="faq">2.12.  How can I make Forrest properly clean up the build/site-directory? </h4>
+<div align="right">
+<a href="#cleanSite-menu">^</a>
+</div>
+<div style="margin-left: 15px">
+<p>Forrest for performance reasons doesn't clean out the build/site-directory each time you
+          compile your project. This usually doesn't matter during development but might become a
+          problem in a production environment.</p>
+<p>To ensure a clean build call 'forrest clean site' instead of just 'forrest' so Forrest
+          will delete all build directories before creating new content. </p>
 </div>
-<a name="N101AD"></a><a name="technical"></a>
+<a name="N101FD"></a><a name="technical"></a>
 <h3 class="underlined_5">3. Technical</h3>
-<a name="N101B1"></a><a name="proxy_config"></a>
-<h4 class="faq">3.1. I'm behind a proxy and it's preventing Plugins from 
-      being downloaded, what should I do?</h4>
+<a name="N10201"></a><a name="proxy_config"></a>
+<h4 class="faq">3.1. I'm behind a proxy and it's preventing Plugins from being downloaded, what should I
+        do?</h4>
 <div align="right">
 <a href="#proxy_config-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>You can configure the proxy in the <span class="codefrag">forrest.properties</span>
-        file. Set the <span class="codefrag">proxy.host</span> and <span class="codefrag">proxy.port</span>
-        accordingly (the port will default to port 80).</p>
-</div>
-<a name="N101C2"></a><a name="CVS_revison_tags"></a>
-<h4 class="faq">3.2. How can I generate html-pages to show the
-      revision tag of cvs?</h4>
+<p>You can configure the proxy in the <span class="codefrag">forrest.properties</span> file. Set the
+            <span class="codefrag">proxy.host</span> and <span class="codefrag">proxy.port</span> accordingly (the port will default
+          to port 80).</p>
+</div>
+<a name="N10212"></a><a name="CVS_revison_tags"></a>
+<h4 class="faq">3.2. How can I generate html-pages to show the revision tag of cvs?</h4>
 <div align="right">
 <a href="#CVS_revison_tags-menu">^</a>
 </div>
 <div style="margin-left: 15px">
 <p>If you have:<span class="codefrag">&lt;version&gt;$Revision: 1.30
-      $&lt;/version&gt;</span>The '1.30' will be extracted and
-      displayed at the bottom of the page as "version 1.30". See for
-      example the bottom of the
-      <a href="../docs/your-project.html"> Using Forrest</a> document.</p>
-<p>This technique could also be used for a modification date with
-      $Date: 2004/01/15 08:52:47 $</p>
-</div>
-<a name="N101D4"></a><a name="cli-xconf"></a>
-<h4 class="faq">3.3. 
-        How to control the processing of URIs by Cocoon, e.g. exclude
-        certain URIs, include other additional ones.
-      </h4>
+          $&lt;/version&gt;</span>The '1.30' will be extracted and
+          displayed at the bottom of the page as "version 1.30". See for example the
+          bottom of the <a href="../docs/your-project.html"> Using Forrest</a> document.</p>
+<p>This technique could also be used for a modification date with $Date: 2004/01/15 08:52:47
+          $</p>
+</div>
+<a name="N10224"></a><a name="cli-xconf"></a>
+<h4 class="faq">3.3.  How to control the processing of URIs by Cocoon, e.g. exclude certain URIs, include
+        other additional ones. </h4>
 <div align="right">
 <a href="#cli-xconf-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>
-          Forrest uses a configuration file to control the processing
-          done by the Apache Cocoon command-line called cli.xconf
-        </p>
-<p>
-          Your project can supply its own <span class="codefrag">cli.xconf</span>
-          and define patterns for URIs to exclude. There are also
-          other powerful configuration features.
-        </p>
-<p>
-          This means creating a directory <span class="codefrag">src/documentation/conf</span>
-          (or wherever <span class="codefrag">${forrest.conf-dir}</span> points) and copying
-          <span class="codefrag">$FORREST_HOME/main/webapp/WEB-INF/cli.xconf</span> to it.
-          Declare the location of this file in the forrest.properties
-          configuration, e.g.
-          <span class="codefrag">project.configfile=${project.home}/src/documentation/conf/cli.xconf</span>
+<p> Forrest uses a configuration file to control the processing done by the Apache Cocoon
+          command-line called cli.xconf </p>
+<p> Your project can supply its own <span class="codefrag">cli.xconf</span> and define patterns for URIs to
+          exclude. There are also other powerful configuration features. </p>
+<p> This means creating a directory <span class="codefrag">src/documentation/conf</span> (or wherever
+            <span class="codefrag">${forrest.conf-dir}</span> points) and copying
+            <span class="codefrag">$FORREST_HOME/main/webapp/WEB-INF/cli.xconf</span> to it. Declare the location of
+          this file in the forrest.properties configuration, e.g.
+            <span class="codefrag">project.configfile=${project.home}/src/documentation/conf/cli.xconf</span>
         
 </p>
-<p>
-          Then edit
-          cli.xconf, and add any exclude sections that you require. The
-          default cli.xconf ignores directory links and links containing
-          'apidocs' or starting with 'api/':
-        </p>
+<p> Then edit cli.xconf, and add any exclude sections that you require. The default
+          cli.xconf ignores directory links and links containing 'apidocs' or starting with 'api/': </p>
 <pre class="code">
    ....
    &lt;!-- Includes and excludes can be used to limit which URLs are rendered --&gt;
@@ -930,60 +853,44 @@
    </strong>
    &lt;uri src="favicon.ico"/&gt;
 &lt;/cocoon&gt;</pre>
-<p>This is just an example, and you should modify it appropriately for
-          your site.</p>
+<p>This is just an example, and you should modify it appropriately for your site.</p>
 <div class="frame note">
 <div class="label">Note</div>
-<div class="content">
-          Wildcards may be used.  These are a powerful feature of Cocoon's
-          <a href="../docs/sitemap-ref.html">sitemap</a>.
-          For example, <strong>foo/*</strong> would match
-          <span class="codefrag">foo/bar</span>, but not <span class="codefrag">foo/bar/baz</span>
-           &mdash; use <strong>foo/**</strong> to match that.
-        </div>
+<div class="content"> Wildcards may be used. These are a powerful feature of Cocoon's <a href="../docs/sitemap-ref.html">sitemap</a>. For example, <strong>foo/*</strong> would match
+            <span class="codefrag">foo/bar</span>, but not <span class="codefrag">foo/bar/baz</span> &mdash; use
+          <strong>foo/**</strong> to match that. </div>
 </div>
 </div>
-<a name="N10211"></a><a name="ignoring_javadocs"></a>
-<h4 class="faq">3.4. 
-        How do I stop Forrest breaking on links to external files that may not
-        exist, like javadocs?
-      </h4>
+<a name="N10261"></a><a name="ignoring_javadocs"></a>
+<h4 class="faq">3.4.  How do I stop Forrest breaking on links to external files that may not exist, like
+        javadocs? </h4>
 <div align="right">
 <a href="#ignoring_javadocs-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>
-          This can be done by overriding the 
-          <a href="#cli-xconf"><span class="codefrag">cli.xconf</span></a>
-          Cocoon config file, and defining patterns for URLs to exclude.
-        </p>
+<p> This can be done by overriding the <a href="#cli-xconf">
+            <span class="codefrag">cli.xconf</span>
+          </a> Cocoon config file, and defining patterns for URLs to exclude. </p>
 </div>
-<a name="N1021E"></a><a name="claimed_patterns"></a>
-<h4 class="faq">3.5. Some of my files are not being processed because they use
-      common filenames.
-      </h4>
+<a name="N10270"></a><a name="claimed_patterns"></a>
+<h4 class="faq">3.5. Some of my files are not being processed because they use common filenames. </h4>
 <div align="right">
 <a href="#claimed_patterns-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>
-          Certain patterns are claimed by the default sitemaps for
-          special processing. These include:
-          <span class="codefrag">site, changes, todo, faq, images, my-images, skinconf,
-          community, howto</span>
+<p> Certain patterns are claimed by the default sitemaps for special processing. These
+          include: <span class="codefrag">site, changes, todo, faq, images, my-images, skinconf, community,
+          howto</span>
         
 </p>
-<p>
-          Sometimes there are workarounds, e.g. faq.html or faq-interview.html
-          would fail, but interview-faq.html would be fine.
-          In future versions of Forrest we will attempt to deal with this issue
-          (<a href="http://issues.cocoondev.org/browse/FOR-217">FOR-217</a>).
+<p> Sometimes there are workarounds, e.g. faq.html or faq-interview.html would fail, but
+          interview-faq.html would be fine. In future versions of Forrest we will attempt to deal
+          with this issue (<a href="http://issues.cocoondev.org/browse/FOR-217">FOR-217</a>).
         </p>
 </div>
-<a name="N10230"></a><a name="build_msg_a"></a>
-<h4 class="faq">3.6. What do the symbols and numbers mean when Forrest lists each
-        document that it has built?
-      </h4>
+<a name="N10282"></a><a name="build_msg_a"></a>
+<h4 class="faq">3.6. What do the symbols and numbers mean when Forrest lists each document that it has
+        built? </h4>
 <div align="right">
 <a href="#build_msg_a-menu">^</a>
 </div>
@@ -997,90 +904,64 @@
 * [50/0]     1.222s 20.2Kb  dreams.html
 * [0/0]      0.535s 11.1Kb  dreams.pdf
 ...</pre>
-<p>
-         Column 1 is the page build status (*=okay X=brokenLink ^=pageSkipped).
-         Column 2 is the number of links that were gathered from that page.
-         Column 3 is the time taken.
-         Column 4 is the page size.
-        </p>
-</div>
-<a name="N1023C"></a><a name="headless_operation"></a>
-<h4 class="faq">3.7. 
-        When generating PNG images from SVG, I get an error: Can't connect to X11 window server using ':0.0' as the value of the DISPLAY variable.
-      </h4>
+<p> Column 1 is the page build status (*=okay X=brokenLink ^=pageSkipped). Column 2 is the
+          number of links that were gathered from that page. Column 3 is the time taken. Column 4 is
+          the page size. </p>
+</div>
+<a name="N1028E"></a><a name="headless_operation"></a>
+<h4 class="faq">3.7.  When generating PNG images from SVG, I get an error: Can't connect to X11 window
+        server using ':0.0' as the value of the DISPLAY variable. </h4>
 <div align="right">
 <a href="#headless_operation-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>
-          If you are using JDK 1.4.0 or newer, you can enable <em>headless</em>
-          operation by running Forrest with the <span class="codefrag">forrest.jvmarg</span>
-          parameter set to <span class="codefrag">-Djava.awt.headless=true</span>, like this:
-        </p>
+<p> If you are using JDK 1.4.0 or newer, you can enable <em>headless</em> operation by
+          running Forrest with the <span class="codefrag">forrest.jvmarg</span> parameter set to
+            <span class="codefrag">-Djava.awt.headless=true</span>, like this: </p>
 <pre class="code">forrest -Dforrest.jvmargs=-Djava.awt.headless=true site</pre>
-<p>
-          See also
-          <a href="http://cocoon.apache.org/2.1/faq/faq-configure-environment.html">Cocoon FAQ</a>.
-        </p>
+<p> See also <a href="http://cocoon.apache.org/2.1/faq/faq-configure-environment.html">Cocoon FAQ</a>. </p>
 </div>
-<a name="N10258"></a><a name="catalog"></a>
-<h4 class="faq">3.8. 
-        How do i configure my favourite XML editor or parser to find the
-        local Forrest DTDs?
-      </h4>
+<a name="N102AA"></a><a name="catalog"></a>
+<h4 class="faq">3.8.  How do i configure my favourite XML editor or parser to find the local Forrest
+        DTDs? </h4>
 <div align="right">
 <a href="#catalog-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>
-          Notes are provided for various tools at
-          <a href="../docs/catalog.html">Using Catalog Entity Resolver for
-          local DTDs</a>.
-        </p>
+<p> Notes are provided for various tools at <a href="../docs/catalog.html">Using Catalog Entity
+            Resolver for local DTDs</a>. </p>
 </div>
-<a name="N10264"></a><a name="skin"></a>
-<h4 class="faq">3.9. 
-        How to make the site look better and change its skin?
-      </h4>
+<a name="N102B6"></a><a name="skin"></a>
+<h4 class="faq">3.9.  How to make the site look better and change its skin? </h4>
 <div align="right">
 <a href="#skin-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>
-        There are <a href="../docs/skins.html">default skins</a> provided,
-        which are configurable and so should meet the needs of most projects.
-        The aim is to provide many capabilities so that extra skins are not
-        needed.
-        </p>
-<p>
-        See notes about
-        <a href="../docs/your-project.html#skins">configuration</a> of the skins.
-        Some projects may have special needs and can define their
-        <a href="../docs/your-project.html#new_skin">own skin</a>.
-        </p>
+<p> There are <a href="../docs/skins.html">default skins</a> provided, which are configurable
+          and so should meet the needs of most projects. The aim is to provide many capabilities so
+          that extra skins are not needed. </p>
+<p> See notes about <a href="../docs/your-project.html#skins">configuration</a> of the skins.
+          Some projects may have special needs and can define their <a href="../docs/your-project.html#new_skin">own skin</a>. </p>
 </div>
-<a name="N1027B"></a><a name="xsp"></a>
+<a name="N102CD"></a><a name="xsp"></a>
 <h4 class="faq">3.10. How do I enable XSP processing?</h4>
 <div align="right">
 <a href="#xsp-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>First consider whether your needs would be better met by Cocoon itself, rather than Forrest.
-        </p>
-<p>That said, there are valid reasons for wanting programmatically generated content, so here is how to enable
-          XSP:</p>
+<p>First consider whether your needs would be better met by Cocoon itself, rather than
+          Forrest. </p>
+<p>That said, there are valid reasons for wanting programmatically generated content, so
+          here is how to enable XSP:</p>
 <ol>
           
-<li>Download 
-          <a href="http://cvs.apache.org/viewcvs.cgi/*checkout*/cocoon-2.1/lib/optional/jdtcore-2.1.0.jar?rev=1.1&content-type=application/java">jdtcore-2.1.0.jar</a>,
-            and copy it to the $FORREST_HOME/main/webapp/WEB-INF/lib directory
-            (or lib/core/ directory in the source
-            distribution).</li>
+<li>Download <a href="http://cvs.apache.org/viewcvs.cgi/*checkout*/cocoon-2.1/lib/optional/jdtcore-2.1.0.jar?rev=1.1&content-type=application/java">jdtcore-2.1.0.jar</a>, and copy it to the $FORREST_HOME/main/webapp/WEB-INF/lib
+            directory (or lib/core/ directory in the source distribution).</li>
           
 <li>
-<p>
-              Add the following generator definition in the map:generators section
-              of your <a href="../docs/project-sitemap.html">project sitemap</a>
+            
+<p> Add the following generator definition in the map:generators section of your <a href="../docs/project-sitemap.html">project sitemap</a>
+            
 </p>
             
 <pre class="code">
@@ -1091,7 +972,9 @@
 </li>
           
 <li>
-<p>Decide how you want to use XSP.  For single files, you could just define a *.xml matcher:</p>
+            
+<p>Decide how you want to use XSP. For single files, you could just define a *.xml
+              matcher:</p>
             
 <pre class="code">
 &lt;map:match pattern="dynamic.xml"&gt;
@@ -1100,127 +983,103 @@
   &lt;map:serialize type="xml"/&gt;
 &lt;/map:match&gt;</pre>
             
-<p>You may instead wish to override forrest.xmap to define a general mapping for XSPs.</p>
+<p>You may instead wish to override forrest.xmap to define a general mapping for
+            XSPs.</p>
           
 </li>
         
 </ol>
-<p>See also the 
-        <a href="http://wiki.apache.org/cocoon/AddingXSPToForrest">AddingXSPToForrest</a> Wiki page.</p>
+<p>See also the <a href="http://wiki.apache.org/cocoon/AddingXSPToForrest">AddingXSPToForrest</a> Wiki page.</p>
 </div>
-<a name="N102B3"></a><a name="breadcrumbs"></a>
-<h4 class="faq">3.11. How do breadcrumbs work?  Why don't they work locally?</h4>
+<a name="N10308"></a><a name="breadcrumbs"></a>
+<h4 class="faq">3.11. How do breadcrumbs work? Why don't they work locally?</h4>
 <div align="right">
 <a href="#breadcrumbs-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>Breadcrumbs begin with up to three URLs specified in
-      <span class="codefrag">skinconf.xml</span>.  Here is what the Forrest site uses:</p>
+<p>Breadcrumbs begin with up to three URLs specified in <span class="codefrag">skinconf.xml</span>. Here is
+          what the Forrest site uses:</p>
 <pre class="code">
   &lt;trail&gt;
     &lt;link1 name="apache" href="http://www.apache.org/"/&gt;
     &lt;link2 name="xml.apache" href="http://xml.apache.org/"/&gt;
     &lt;link3 name="" href=""/&gt;
   &lt;/trail&gt;</pre>
-<p>If any links are blank, they are not used.  After these first links,
-      JavaScript looks at the URL for the current page and
-      makes a link for each directory after the domain.  If you are viewing
-      the site locally, there is no domain and so
-      there will be no extra breadcrumbs, only the ones that are specified
-      in <span class="codefrag">skinconf.xml</span>.
-      </p>
+<p>If any links are blank, they are not used. After these first links, JavaScript looks at
+          the URL for the current page and makes a link for each directory after the domain. If you
+          are viewing the site locally, there is no domain and so there will be no extra
+          breadcrumbs, only the ones that are specified in <span class="codefrag">skinconf.xml</span>. </p>
 </div>
-<a name="N102C8"></a><a name="run_port"></a>
+<a name="N1031D"></a><a name="run_port"></a>
 <h4 class="faq">3.12. How do I make forrest run listen on a different port?</h4>
 <div align="right">
 <a href="#run_port-menu">^</a>
 </div>
 <div style="margin-left: 15px">
 <p>
+          
 <span class="codefrag">forrest run -Dforrest.jvmargs="-Djetty.port=80"</span>
+        
 </p>
 <p>Or copy Forrest's main/webapp/jettyconf.xml file to your project's src/documentation
-      directory and set the port number in that file.  Then do <span class="codefrag">forrest run</span>
-      
+          directory and set the port number in that file. Then do <span class="codefrag">forrest run</span>
+        
 </p>
 </div>
-<a name="N102DA"></a><a name="old_faqs"></a>
+<a name="N10331"></a><a name="old_faqs"></a>
 <h3 class="underlined_5">4. Older version: 0.6</h3>
-<a name="N102DE"></a><a name="old_claimed_patterns"></a>
-<h4 class="faq">4.1. Some of my files are not being processed because they use
-      common filenames.
-      </h4>
+<a name="N10335"></a><a name="old_claimed_patterns"></a>
+<h4 class="faq">4.1. Some of my files are not being processed because they use common filenames. </h4>
 <div align="right">
 <a href="#old_claimed_patterns-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>
-          Certain patterns are claimed by the default sitemaps for
-          special processing. These include:
-          <span class="codefrag">site, changes, todo, faq, images, my-images, skinconf,
-          community, howto</span>
+<p> Certain patterns are claimed by the default sitemaps for special processing. These
+          include: <span class="codefrag">site, changes, todo, faq, images, my-images, skinconf, community,
+          howto</span>
         
 </p>
-<p>
-          Sometimes there are workarounds, e.g. faq.html or faq-interview.html
-          would fail, but interview-faq.html would be fine.
-          In future versions of Forrest we will attempt to deal with this issue
-          (<a href="http://issues.cocoondev.org/browse/FOR-217">FOR-217</a>).
+<p> Sometimes there are workarounds, e.g. faq.html or faq-interview.html would fail, but
+          interview-faq.html would be fine. In future versions of Forrest we will attempt to deal
+          with this issue (<a href="http://issues.cocoondev.org/browse/FOR-217">FOR-217</a>).
         </p>
 </div>
-<a name="N102F0"></a><a name="general"></a>
+<a name="N10347"></a><a name="general"></a>
 <h3 class="underlined_5">5. General</h3>
-<a name="N102F4"></a><a name="generating_menus"></a>
-<h4 class="faq">5.1. What is the relationship between site.xml and
-        book.xml?
-      </h4>
+<a name="N1034B"></a><a name="generating_menus"></a>
+<h4 class="faq">5.1. What is the relationship between site.xml and book.xml? </h4>
 <div align="right">
 <a href="#generating_menus-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>
-          One <span class="codefrag">site.xml</span> file in your project root can replace all the book.xml files
-          (one per directory) in your site.  Internally, Forrest uses <span class="codefrag">site.xml</span> to
-          dynamically generate book.xml files.  However, Forrest first checks
-          for the existence of a book.xml file, so backwards-compatibility is
-          preserved.  If a directory has a book.xml file, the book.xml will be
-          used to generate the menu.  This supplement is useful in situations
-          where <span class="codefrag">site.xml</span>-generated menus aren't appropriate.
-          See <a href="../docs/linking.html">Menus and Linking</a>.
-      </p>
-</div>
-<a name="N1030F"></a><a name="docbook"></a>
-<h4 class="faq">5.2. 
-        How do I use DocBook as the xml documentation format?
-      </h4>
+<p> One <span class="codefrag">site.xml</span> file in your project root can replace all the book.xml files (one per
+          directory) in your site. Internally, Forrest uses <span class="codefrag">site.xml</span> to dynamically generate book.xml
+          files. However, Forrest first checks for the existence of a book.xml file, so
+          backwards-compatibility is preserved. If a directory has a book.xml file, the book.xml
+          will be used to generate the menu. This supplement is useful in situations where
+          <span class="codefrag">site.xml</span>-generated menus aren't appropriate. See <a href="../docs/linking.html">Menus and
+            Linking</a>. </p>
+</div>
+<a name="N10366"></a><a name="docbook"></a>
+<h4 class="faq">5.2.  How do I use DocBook as the xml documentation format? </h4>
 <div align="right">
 <a href="#docbook-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>
-         There are two ways. Forrest has a <span class="codefrag">simplified-docbook</span> plugin
-         which can transform the DocBook format into the
-         Forrest "xdocs" format on-the-fly and then render that as normal
-         Forrest documents.
-         Be aware that the stylesheet that does this transformation is
-         deliberately very limited and does not attempt to deal with all
-         DocBook elements.
-        </p>
-<p>
-         The other way is to use the full DocBook stylesheets directly. The DocBook
-         DTDs are shipped with Forrest and automatically handled. However, you
-         will need to have the DocBook stylesheets on your system (they are
-         too massive to ship with Forrest) and configure Forrest accordingly.
-         You will need to create a
-         <a href="../docs/project-sitemap.html">project sitemap</a>
-          as explained in
-         <a href="../docs/your-project.html">Using Forrest</a>
-         and add matches to handle your DocBook documents.
-         Here is an example. Note that you need to change it to suit your
-         situation. The match must be very specific so that only the
-         DocBook documents are matched. The rest of the documents will be
-         handled by Forrest core. Powerful regex capabilities are available.
-        </p>
+<p> There are two ways. Forrest has a <span class="codefrag">simplified-docbook</span> plugin which can
+          transform the DocBook format into the Forrest "xdocs" format on-the-fly and then render
+          that as normal Forrest documents. Be aware that the stylesheet that does this
+          transformation is deliberately very limited and does not attempt to deal with all DocBook
+          elements. </p>
+<p> The other way is to use the full DocBook stylesheets directly. The DocBook DTDs are
+          shipped with Forrest and automatically handled. However, you will need to have the DocBook
+          stylesheets on your system (they are too massive to ship with Forrest) and configure
+          Forrest accordingly. You will need to create a <a href="../docs/project-sitemap.html">project
+            sitemap</a> as explained in <a href="../docs/your-project.html">Using Forrest</a> and
+          add matches to handle your DocBook documents. Here is an example. Note that you need to
+          change it to suit your situation. The match must be very specific so that only the DocBook
+          documents are matched. The rest of the documents will be handled by Forrest core. Powerful
+          regex capabilities are available. </p>
 <pre class="code">&lt;?xml version="1.0"?&gt;
 &lt;map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0"&gt;
  &lt;map:pipelines&gt;
@@ -1233,105 +1092,68 @@
    &lt;/map:match&gt;
   &lt;/map:pipeline&gt;
  &lt;/map:pipelines&gt;
-&lt;/map:sitemap&gt;
-        </pre>
-<p>
-         You can also use a mixture of the two methods, some handled
-         automatically by Forrest and some directly using DocBook stylesheets.
-         You can also have a mixture of source files as "document-v*" DTD and DocBook.
-        </p>
-<p>
-         Ensure that the document type declaration in your xml instance is
-         well specified. Use a public identifier. The DTD will then be properly
-         resolved by Forrest. If you need to use different DTDs, then see
-         <a href="../docs/your-project.html#new_dtd">Using Forrest</a>
-         for configuration guidance.
-        </p>
-</div>
-<a name="N10333"></a><a name="version"></a>
-<h4 class="faq">5.3. 
-        How to report which version of Forrest is being used and the
-        properties that are set?
-      </h4>
+&lt;/map:sitemap&gt;</pre>
+<p> You can also use a mixture of the two methods, some handled automatically by Forrest and
+          some directly using DocBook stylesheets. You can also have a mixture of source files as
+          "document-v*" DTD and DocBook. </p>
+<p> Ensure that the document type declaration in your xml instance is well specified. Use a
+          public identifier. The DTD will then be properly resolved by Forrest. If you need to use
+          different DTDs, then see <a href="../docs/your-project.html#new_dtd">Using Forrest</a> for
+          configuration guidance. </p>
+</div>
+<a name="N1038A"></a><a name="version"></a>
+<h4 class="faq">5.3.  How to report which version of Forrest is being used and the properties that are
+        set? </h4>
 <div align="right">
 <a href="#version-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>
-          Do <span class="codefrag">'forrest -projecthelp'</span> or <span class="codefrag">'./build.sh'</span>
-          to find the version number.
-        </p>
-<p>
-          To list the properties, add "forrest.echo=true" to your
-          forrest.properties file and watch the build messages.
-          Doing <span class="codefrag">'forrest -v'</span> will provide verbose build messages.
-        </p>
+<p> Do <span class="codefrag">'forrest -projecthelp'</span> or <span class="codefrag">'./build.sh'</span> to find the version
+          number. </p>
+<p> To list the properties, add "forrest.echo=true" to your forrest.properties file and
+          watch the build messages. Doing <span class="codefrag">'forrest -v'</span> will provide verbose build
+          messages. </p>
 </div>
-<a name="N10347"></a><a name="logs"></a>
-<h4 class="faq">5.4. 
-        Where are the log files to find more infomation about errors?
-      </h4>
+<a name="N1039E"></a><a name="logs"></a>
+<h4 class="faq">5.4.  Where are the log files to find more infomation about errors? </h4>
 <div align="right">
 <a href="#logs-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>
-          The logfiles are at <span class="codefrag">build/webapp/WEB-INF/logs/</span>
+<p> The logfiles are at <span class="codefrag">build/webapp/WEB-INF/logs/</span>
         
 </p>
-<p>
-          The log level can be raised with the <span class="codefrag">logkit.xconf</span>
-          configuration. If you are using Forrest in the interactive webapp
-          mode (which is generally easiest for debugging errors) then see the
-          <span class="codefrag">build/webapp/WEB-INF/logkit.xconf</span> file.
-          If you are generating a static site (with command-line 'forrest')
-          then copy <span class="codefrag">$FORREST_HOME/main/webapp/WEB-INF/logkit.xconf</span>
-          to your project at
-          <span class="codefrag">src/documentation/content/conf/logkit.xconf</span>
-          and modify it. See more information and efficiency tips with
-          <a href="http://wiki.apache.org/cocoon/ExploringTheLogs">Cocoon logging</a>.
-        </p>
-<p>
-          Doing <span class="codefrag">'forrest -v'</span> will provide verbose build messages
-          to the standard output.
-        </p>
+<p> The log level can be raised with the <span class="codefrag">logkit.xconf</span> configuration. If you are
+          using Forrest in the interactive webapp mode (which is generally easiest for debugging
+          errors) then see the <span class="codefrag">build/webapp/WEB-INF/logkit.xconf</span> file. If you are
+          generating a static site (with command-line 'forrest') then copy
+            <span class="codefrag">$FORREST_HOME/main/webapp/WEB-INF/logkit.xconf</span> to your project at
+            <span class="codefrag">src/documentation/content/conf/logkit.xconf</span> and modify it. See more
+          information and efficiency tips with <a href="http://wiki.apache.org/cocoon/ExploringTheLogs">Cocoon logging</a>. </p>
+<p> Doing <span class="codefrag">'forrest -v'</span> will provide verbose build messages to the standard
+          output. </p>
 </div>
-<a name="N1036B"></a><a name="how_can_I_help"></a>
-<h4 class="faq">5.5. 
-        How to help?
-      </h4>
+<a name="N103C2"></a><a name="how_can_I_help"></a>
+<h4 class="faq">5.5.  How to help? </h4>
 <div align="right">
 <a href="#how_can_I_help-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>
-          Join one of the Forrest project
-          <a href="../mail-lists.html">mailing lists</a>
-          and tell us what you would like to see improved.  We regard all feedback
-          as valuable, particularly from newcomers&mdash;often, close proximity
-          blinds software developers to faults that are obvious to everyone
-          else. Don't be shy!
-        </p>
+<p> Join one of the Forrest project <a href="../mail-lists.html">mailing lists</a> and
+          tell us what you would like to see improved. We regard all feedback as valuable,
+          particularly from newcomers&mdash;often, close proximity blinds software developers to
+          faults that are obvious to everyone else. Don't be shy! </p>
 </div>
-<a name="N10377"></a><a name="patch"></a>
-<h4 class="faq">5.6. 
-        How to contribute a patch?
-      </h4>
+<a name="N103CE"></a><a name="patch"></a>
+<h4 class="faq">5.6.  How to contribute a patch? </h4>
 <div align="right">
 <a href="#patch-menu">^</a>
 </div>
 <div style="margin-left: 15px">
-<p>Please send all contributions via our
-          <a href="http://issues.cocoondev.org/secure/BrowseProject.jspa?id=10000">issue tracker</a>.
-          Here are notes about
-          <a href="../contrib.html#patch">making patches</a>.
-        </p>
-<p>More info about contributing can be found at the 
-          <a href="../contrib.html">Contributing to Forrest</a> page.
-          It is always a good idea to check the Forrest
-          <a href="http://issues.cocoondev.org/secure/BrowseProject.jspa?id=10000">issue tracker</a>
-          before diving in.
-        </p>
+<p>Please send all contributions via our <a href="http://issues.cocoondev.org/secure/BrowseProject.jspa?id=10000">issue tracker</a>. Here
+          are notes about <a href="../contrib.html#patch">making patches</a>. </p>
+<p>More info about contributing can be found at the <a href="../contrib.html">Contributing
+            to Forrest</a> page. It is always a good idea to check the Forrest <a href="http://issues.cocoondev.org/secure/BrowseProject.jspa?id=10000">issue tracker</a> before diving in. </p>
 </div>
 </div>
 </div>
@@ -1350,7 +1172,9 @@
 //  --></script>
 </div>
 <div class="copyright">
- Copyright &copy; 2002-2005 The Apache Software Foundation.</div>
+        Copyright &copy;
+         2002-2005 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
+</div>
 <!--+
     |end bottomstrip
     +-->

Modified: forrest/site/0.7/docs/faq.pdf
URL: http://svn.apache.org/viewcvs/forrest/site/0.7/docs/faq.pdf?rev=168512&r1=168511&r2=168512&view=diff
==============================================================================
Binary files - no diff available.



Mime
View raw message