src/documentation/content/xdocs/faq.xml - forrest - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.2//EN" "dtd/faq-v12.dtd" [
 <!ENTITY s '<code>site.xml</code>'>
 ]>

 <faqs title="Frequently Asked Questions">

   <part id="getting_started">
     <title>Building Forrest</title>
     <faq id="checked_out_now_what">
       <question>
         I have checked out a working copy of <code>xml-forrest</code> CVS, now what?
       </question>
       <answer>
         <p>
           Run &quot;<code>./build.sh</code>&quot; to build forrest, then run
           &quot;<code>forrest</code>&quot; to generate the documentation
           for Forrest, built with Forrest.
           The documentation is generated in the <code>build/site/</code> directory.
           Logfiles are in the <code>build/tmp/context/WEB-INF/logs/</code> directory.
           When you thereafter update your cvs, then run "build clean" before building.
         </p>
         <p>
           The <link href="site:your-project">Using Forrest</link> guide provides
           further step-by-step assistance in getting started with Forrest for your project.
         </p>
       </answer>
     </faq>

     <faq id="cygwin_mutex_error">
       <question>
         When running <code>./build.sh</code> in cygwin, I get an error:
         <code>cygpath.exe: *** can't create title mutex, Win32 error 6</code>.
       </question>
       <answer>
         <p>
           This <link
             href="http://issues.cocoondev.org/jira//secure/ViewIssue.jspa?key=FOR-10">appears
             to be a bug in cygwin</link>.  Please use the .bat script instead.
         </p>
       </answer>
     </faq>
   </part>


   <part id="technical">
     <title>Technical</title>
     <faq id="ignoring_javadocs">
       <question>
         How do I stop Forrest breaking on links to external files that may not
         exist, like javadocs?
       </question>
       <answer>
         <p>
           This can be done by overriding the <code>cli.xconf</code> config file,
           and defining patterns for URLs to exclude.
         </p>
         <p>
           This means creating a directory <code>src/documentation/conf</code>
           (or wherever <code>${forrest.conf-dir}</code> points) and copying
           <code>$FORREST_HOME/WEB-INF/cli.xconf</code> to it.  Then edit
           cli.xconf, and add any exclude sections you require at the end.  The
           default cli.xconf ignores directory links and links containing
           'apidocs' or starting with 'api/':
         </p>
         <source><![CDATA[
    ....
    <!-- Includes and excludes can be used to limit which URLs are rendered -->
    ]]><strong><![CDATA[
    <exclude pattern="**/"/>
    <exclude pattern="**apidocs**"/>
    <exclude pattern="api/**"/>
    ]]></strong><![CDATA[

    <uri src="favicon.ico"/>
 </cocoon>]]></source>
         <p>This is just an example, and you should modify it appropriately for
           your site.</p>
         <note>
           Wildcards may be used.  Wildcards work as in Cocoon's sitemap.  <strong>foo/*</strong> would match
           <code>foo/bar</code>, but not <code>foo/bar/baz</code> &mdash; use <strong>foo/**</strong> to match that.
         </note>
       </answer>
     </faq>

     <faq id="link_raw">
       <question>How do I link to raw files such as config.txt and brochure.pdf?
       </question>
       <answer>
         <p>
           Place them in the <code>src/documentation/content</code> 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>
       </answer>
     </faq>

     <faq id="build_msg_a">
       <question>What do the numbers in square brackets mean when Forrest lists
         each document that it has built?
       </question>
       <answer>
         <source><![CDATA[
  * [37] index.html
  * [0] images/project-logo.png
  * [0] skin/images/printer.gif
  * [32] components/index.html
  * [31] components/resolver/index.html
 ...
           ]]></source>
         <p>
          This is the number of links that were gathered from that page.
         </p>
       </answer>
     </faq>

     <faq id="pdf_images">
       <question>Image don't display in PDFs. How do I fix this?</question>
       <answer>
         <p>
           Forrest uses <link href="http://xml.apache.org/fop/">Apache FOP</link>
           for rendering images.  FOP cannot handle all image types natively, and
           requires third-party jars to be added.  For an overview, see <link
             href="http://xml.apache.org/fop/graphics.html">FOP Graphics
             formats</link>
         </p>
         <p>Specifically, to get PNGs working in PDFs with Jimi:</p>
         <ol>
           <li>Download Jimi from <link
               href="http://java.sun.com/products/jimi/">http://java.sun.com/products/jimi/</link></li>
           <li>Unpack the Jimi distribution and copy JimiProClasses.zip to
             <code>lib/core/jimi-1.0.jar</code> (or to
             <code>src/documentation/lib/jimi-1.0.jar</code> so that each
             developer does not need to modify their Forrest installation).</li>
           <li>Rebuild Forrest (if you used the lib/core/ option above).</li>
         </ol>
         <p>Alternative you can use JAI (Java Advanced Imaging API). For more
           info, see <link
             href="http://xml.apache.org/fop/graphics.html#packages">FOP Graphics
             Packages</link>
         </p>
         <note>Due to Sun's licensing, we cannot redistribute Jimi or JAI with
           Forrest</note>
       </answer>
     </faq>


      <faq id="index.html">
       <question>
         The tab link in my site incorrectly assumes that 'index.html' is present in
         the linked-to directory. How do I fix this?
       </question>
       <answer>
         <p>
           In <code>tabs.xml</code>, use @href instead of @dir, and omit the trailing
           '/'. That will leave which file to serve up to the sitemap.  For example, if
           the 'User Manual' tab should link to <code>manual/Introduction.html</code>,
           <code>tabs.xml</code> should contain:
         </p>
         <source><![CDATA[
           <tab label="User Manual" href="manual"/>
           ]]></source>
         <p>
           and add this rule to the sitemap:
         </p>
         <source><![CDATA[
           <map:match pattern="manual">
             <map:redirect-to uri="manual/Introduction.html"/>
           </map:match>
           ]]></source>
      </answer>
     </faq>

     <faq id="headless_operation">
       <question>
         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.
       </question>
       <answer>
         <p>
           If you are using JDK 1.4.0 or newer, you can enable <em>headless</em>
           operation by running Forrest with the <code>forrest.jvmarg</code>
           parameter set to <code>-Djava.awt.headless=true</code>, like this:
         </p>
         <source>forrest -Dforrest.jvmargs=-Djava.awt.headless=true site</source>
       </answer>
     </faq>

     <faq id="xsp">
       <question>How do I enable <acronym title="eXtensible Server Pages">XSP</acronym> processing?</question>
       <answer>
         <p>First consider whether your needs would be better met by Cocoon itself, rather than Forrest.  Forrest was
           designed primarily with static sites in mind, and is not a general-purpose Cocoon distribution.</p>
         <p>That said, there are valid reasons for wanting programmatically generated content, so here is how to enable
           XSP:</p>
         <ol>
           <li>Download <link
               href="http://cvs.apache.org/viewcvs.cgi/*checkout*/cocoon-2.1/lib/optional/jdtcore-2.1.0.jar?rev=1.1&amp;content-type=application/java">jdtcore-2.1.0.jar</link>,
             and copy it to the $FORREST_HOME/WEB-INF/lib directory (or lib/core/ directory in the source
             distribution).</li>
           <li><p>Override sitemap.xmap in your local project (copy $FORREST_HOME/context/sitemap.xmap to
               src/documentation/conf/), and add the following generator definition in the map:generators section:</p>
             <source>
               &lt;map:generator name="serverpages" pool-grow="2"
               pool-max="32" pool-min="4" src="org.apache.cocoon.generation.ServerPagesGenerator"/&gt;
             </source>
           </li>
           <li><p>Decide how you want to use XSP.  For single files, you could just define a *.xml matcher:</p>
             <source><![CDATA[
 <map:match pattern="dynamic.xml">
   <map:generate src="content/xdocs/dynamic.xsp" type="serverpages"/>
   ...
   <map:serialize type="xml"/>
 </map:match>]]></source>
             <p>You may instead wish to override forrest.xmap to define a general mapping for XSPs.</p>
           </li>

         </ol>
         <p>See also the <link
             href="http://wiki.cocoondev.org/Wiki.jsp?page=AddingXSPToForrest">AddingXSPToForrest</link> Wiki page.</p>
       </answer>
     </faq>

   </part>

   <part id="old_faqs">
     <title>Older versions</title>
     <faq id="unresolved_project.home">
       <question>When invoking Forrest 0.4 from the
         <code>forrest.antproxy.xml</code>, the build fails because
         <code>${project.home}</code> isn't resolved.
       </question>
       <answer>
         <p>This is a bug in 0.4. The following modification to
           <code>FORREST_HOME/forrest.antproxy.xml</code> should fix it:</p>
         <source
 ><![CDATA[--- forrest.antproxy.xml        7 Feb 2003 22:21:15 -0000       1.2
 +++ forrest.antproxy.xml        22 Feb 2003 09:39:42 -0000
 @@ -41,6 +41,7 @@
    </path>

    <target name="forrest">
 +    <property name="project.home" location="."/>
      <java classname="org.apache.tools.ant.Main" fork="true">
        <classpath refid="forrest-classpath"/>
        <jvmarg value="-Dforrest.home=${forrest.home}"/>]]></source>
       </answer>
     </faq>

     <faq id="odd_html">
       <question>
         After upgrading to 0.4 my HTML looks significantly different, and table
         widths are wrong. What happened?
       </question>
       <answer>
         <p>
           Forrest now uses a HTML 4.0.1 <code>DOCTYPE</code> declaration,
           <code><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01
             Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">]]></code>.
           This causes browsers to render the page in standards-compliance mode,
           or rather, not in "quirks" mode. For some operations (like determining
           table column widths), quirks mode results in better looking pages.
           For the old pre-0.4 behaviour, create a custom sitemap and remove the
           line:</p>
         <source><![CDATA[
           <doctype-system>http://www.w3.org/TR/html4/loose.dtd</doctype-system>
           ]]></source>
       </answer>
     </faq>
     <faq id="validation_error:doctype_root_null">
       <question>
         When building my project, I get an validation error: <code>Document root
           element "site", must match DOCTYPE root "null".</code>.
       </question>
       <answer>
         <p>
           You are probably trying to build the project with an old version of
           Forrest (built before 2003-01-08) that is incorrectly trying to validate
           the &s; file.  If so, please update your Forrest
           installation.
         </p>
         <p>
           Alternatively, you may be building with an up-to-date Forrest, but have
           overridden <code>forrest.validate.xdocs.excludes</code> in
           <code>forrest.properties</code>.  With the introduction of
           &s;, the above property must have &s;
           listed to prevent an attempt at DTD-based validation.
         </p>
       </answer>
     </faq>

   </part>

   <part id="general">
     <title>General</title>

     <faq id="generating_menus">
       <question>What is the relation between &s; and
         <code>book.xml</code>?
       </question>
       <answer>
         <p>
           One &s; file in your project root can replace all the book.xml files
           (one per directory) in your site.  Internally, Forrest uses &s; to
           dynamically generate book.xml files.  However, Forrest first checks
           for the existence of a book.xml file, so backwards-compatibility is
           preserved.  If a directory has a book.xml file, the book.xml will be
           used to generate the menu.  This is useful in situations where
           &s;-generated menus aren't appropriate.
       </p>
       </answer>
     </faq>

     <faq id="docbook">
       <question>
         How do I use DocBook as the xml documentation format?
       </question>
       <answer>
         <p>
          There are two ways. Forrest can transform the DocBook format into the
          Forrest "document" DTD on-the-fly and then render that as normal.
          The stylesheet that does this transformation still needs a little
          work but it handles most things.
         </p>
         <p>
          The other way is to use the 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 "sitemap" as explained in
          <link href="site:your-project">Using Forrest</link>
          and add matches to handle your DocBook documents, e.g.
         </p>
         <source><![CDATA[
 ...
   <map:match pattern="**/resolver-*.html">
     <map:generate src="content/xdocs/{1}/resolver-{2}.xml"/>
     <map:transform
       src="file:///usr/share/sgml/docbook/xsl/xhtml/docbook.xsl"/>
     <map:serialize/>
   </map:match>
 ...
 ]]>
         </source>
         <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 "document-v*" DTD and DocBook.
         </p>
       </answer>
     </faq>

     <faq id="how_can_I_help">
       <question>
         How can I help?
       </question>
       <answer>
         <p>
           Join the forrest-dev <link href="site:mail-lists">mailing list</link>,
           and tell us what you'd 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>
           More info on contributing can be found on the <link
             href="site:contrib">Contributing to Forrest</link> page.  Its always
           a good idea to check the Forrest <link href="site:todo">to do</link>
           list before diving in.
         </p>
       </answer>
     </faq>
   </part>
 </faqs>
	<?xml version="1.0" encoding="UTF-8"?>
	<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.2//EN" "dtd/faq-v12.dtd" [
	<!ENTITY s '<code>site.xml</code>'>
	]>

	<faqs title="Frequently Asked Questions">

	<part id="getting_started">
	<title>Building Forrest</title>
	<faq id="checked_out_now_what">
	<question>
	I have checked out a working copy of <code>xml-forrest</code> CVS, now what?
	</question>
	<answer>
	<p>
	Run "<code>./build.sh</code>" to build forrest, then run
	"<code>forrest</code>" to generate the documentation
	for Forrest, built with Forrest.
	The documentation is generated in the <code>build/site/</code> directory.
	Logfiles are in the <code>build/tmp/context/WEB-INF/logs/</code> directory.
	When you thereafter update your cvs, then run "build clean" before building.
	</p>
	<p>
	The <link href="site:your-project">Using Forrest</link> guide provides
	further step-by-step assistance in getting started with Forrest for your project.
	</p>
	</answer>
	</faq>

	<faq id="cygwin_mutex_error">
	<question>
	When running <code>./build.sh</code> in cygwin, I get an error:
	<code>cygpath.exe: *** can't create title mutex, Win32 error 6</code>.
	</question>
	<answer>
	<p>
	This <link
	href="http://issues.cocoondev.org/jira//secure/ViewIssue.jspa?key=FOR-10">appears
	to be a bug in cygwin</link>. Please use the .bat script instead.
	</p>
	</answer>
	</faq>
	</part>



	<part id="technical">
	<title>Technical</title>
	<faq id="ignoring_javadocs">
	<question>
	How do I stop Forrest breaking on links to external files that may not
	exist, like javadocs?
	</question>
	<answer>
	<p>
	This can be done by overriding the <code>cli.xconf</code> config file,
	and defining patterns for URLs to exclude.
	</p>
	<p>
	This means creating a directory <code>src/documentation/conf</code>
	(or wherever <code>${forrest.conf-dir}</code> points) and copying
	<code>$FORREST_HOME/WEB-INF/cli.xconf</code> to it. Then edit
	cli.xconf, and add any exclude sections you require at the end. The
	default cli.xconf ignores directory links and links containing
	'apidocs' or starting with 'api/':
	</p>
	<source><![CDATA[
	....
	<!-- Includes and excludes can be used to limit which URLs are rendered -->
	]]><strong><![CDATA[
	<exclude pattern="**/"/>
	<exclude pattern="apidocs"/>
	<exclude pattern="api/**"/>
	]]></strong><![CDATA[

	<uri src="favicon.ico"/>
	</cocoon>]]></source>
	<p>This is just an example, and you should modify it appropriately for
	your site.</p>
	<note>
	Wildcards may be used. Wildcards work as in Cocoon's sitemap. <strong>foo/*</strong> would match
	<code>foo/bar</code>, but not <code>foo/bar/baz</code> — use <strong>foo/**</strong> to match that.
	</note>
	</answer>
	</faq>

	<faq id="link_raw">
	<question>How do I link to raw files such as config.txt and brochure.pdf?
	</question>
	<answer>
	<p>
	Place them in the <code>src/documentation/content</code> 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>
	</answer>
	</faq>

	<faq id="build_msg_a">
	<question>What do the numbers in square brackets mean when Forrest lists
	each document that it has built?
	</question>
	<answer>
	<source><![CDATA[
	* [37] index.html
	* [0] images/project-logo.png
	* [0] skin/images/printer.gif
	* [32] components/index.html
	* [31] components/resolver/index.html
	...
	]]></source>
	<p>
	This is the number of links that were gathered from that page.
	</p>
	</answer>
	</faq>

	<faq id="pdf_images">
	<question>Image don't display in PDFs. How do I fix this?</question>
	<answer>
	<p>
	Forrest uses <link href="http://xml.apache.org/fop/">Apache FOP</link>
	for rendering images. FOP cannot handle all image types natively, and
	requires third-party jars to be added. For an overview, see <link
	href="http://xml.apache.org/fop/graphics.html">FOP Graphics
	formats</link>
	</p>
	<p>Specifically, to get PNGs working in PDFs with Jimi:</p>
	<ol>
	<li>Download Jimi from <link
	href="http://java.sun.com/products/jimi/">http://java.sun.com/products/jimi/</link></li>
	<li>Unpack the Jimi distribution and copy JimiProClasses.zip to
	<code>lib/core/jimi-1.0.jar</code> (or to
	<code>src/documentation/lib/jimi-1.0.jar</code> so that each
	developer does not need to modify their Forrest installation).</li>
	<li>Rebuild Forrest (if you used the lib/core/ option above).</li>
	</ol>
	<p>Alternative you can use JAI (Java Advanced Imaging API). For more
	info, see <link
	href="http://xml.apache.org/fop/graphics.html#packages">FOP Graphics
	Packages</link>
	</p>
	<note>Due to Sun's licensing, we cannot redistribute Jimi or JAI with
	Forrest</note>
	</answer>
	</faq>


	<faq id="index.html">
	<question>
	The tab link in my site incorrectly assumes that 'index.html' is present in
	the linked-to directory. How do I fix this?
	</question>
	<answer>
	<p>
	In <code>tabs.xml</code>, use @href instead of @dir, and omit the trailing
	'/'. That will leave which file to serve up to the sitemap. For example, if
	the 'User Manual' tab should link to <code>manual/Introduction.html</code>,
	<code>tabs.xml</code> should contain:
	</p>
	<source><![CDATA[
	<tab label="User Manual" href="manual"/>
	]]></source>
	<p>
	and add this rule to the sitemap:
	</p>
	<source><![CDATA[
	<map:match pattern="manual">
	<map:redirect-to uri="manual/Introduction.html"/>
	</map:match>
	]]></source>
	</answer>
	</faq>

	<faq id="headless_operation">
	<question>
	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.
	</question>
	<answer>
	<p>
	If you are using JDK 1.4.0 or newer, you can enable <em>headless</em>
	operation by running Forrest with the <code>forrest.jvmarg</code>
	parameter set to <code>-Djava.awt.headless=true</code>, like this:
	</p>
	<source>forrest -Dforrest.jvmargs=-Djava.awt.headless=true site</source>
	</answer>
	</faq>

	<faq id="xsp">
	<question>How do I enable <acronym title="eXtensible Server Pages">XSP</acronym> processing?</question>
	<answer>
	<p>First consider whether your needs would be better met by Cocoon itself, rather than Forrest. Forrest was
	designed primarily with static sites in mind, and is not a general-purpose Cocoon distribution.</p>
	<p>That said, there are valid reasons for wanting programmatically generated content, so here is how to enable
	XSP:</p>
	<ol>
	<li>Download <link
	href="http://cvs.apache.org/viewcvs.cgi/checkout/cocoon-2.1/lib/optional/jdtcore-2.1.0.jar?rev=1.1&content-type=application/java">jdtcore-2.1.0.jar</link>,
	and copy it to the $FORREST_HOME/WEB-INF/lib directory (or lib/core/ directory in the source
	distribution).</li>
	<li><p>Override sitemap.xmap in your local project (copy $FORREST_HOME/context/sitemap.xmap to
	src/documentation/conf/), and add the following generator definition in the map:generators section:</p>
	<source>
	<map:generator name="serverpages" pool-grow="2"
	pool-max="32" pool-min="4" src="org.apache.cocoon.generation.ServerPagesGenerator"/>
	</source>
	</li>
	<li><p>Decide how you want to use XSP. For single files, you could just define a *.xml matcher:</p>
	<source><![CDATA[
	<map:match pattern="dynamic.xml">
	<map:generate src="content/xdocs/dynamic.xsp" type="serverpages"/>
	...
	<map:serialize type="xml"/>
	</map:match>]]></source>
	<p>You may instead wish to override forrest.xmap to define a general mapping for XSPs.</p>
	</li>

	</ol>
	<p>See also the <link
	href="http://wiki.cocoondev.org/Wiki.jsp?page=AddingXSPToForrest">AddingXSPToForrest</link> Wiki page.</p>
	</answer>
	</faq>

	</part>

	<part id="old_faqs">
	<title>Older versions</title>
	<faq id="unresolved_project.home">
	<question>When invoking Forrest 0.4 from the
	<code>forrest.antproxy.xml</code>, the build fails because
	<code>${project.home}</code> isn't resolved.
	</question>
	<answer>
	<p>This is a bug in 0.4. The following modification to
	<code>FORREST_HOME/forrest.antproxy.xml</code> should fix it:</p>
	<source
	><![CDATA[--- forrest.antproxy.xml 7 Feb 2003 22:21:15 -0000 1.2
	+++ forrest.antproxy.xml 22 Feb 2003 09:39:42 -0000
	@@ -41,6 +41,7 @@
	</path>

	<target name="forrest">
	+ <property name="project.home" location="."/>
	<java classname="org.apache.tools.ant.Main" fork="true">
	<classpath refid="forrest-classpath"/>
	<jvmarg value="-Dforrest.home=${forrest.home}"/>]]></source>
	</answer>
	</faq>

	<faq id="odd_html">
	<question>
	After upgrading to 0.4 my HTML looks significantly different, and table
	widths are wrong. What happened?
	</question>
	<answer>
	<p>
	Forrest now uses a HTML 4.0.1 <code>DOCTYPE</code> declaration,
	<code><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01
	Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">]]></code>.
	This causes browsers to render the page in standards-compliance mode,
	or rather, not in "quirks" mode. For some operations (like determining
	table column widths), quirks mode results in better looking pages.
	For the old pre-0.4 behaviour, create a custom sitemap and remove the
	line:</p>
	<source><![CDATA[
	<doctype-system>http://www.w3.org/TR/html4/loose.dtd</doctype-system>
	]]></source>
	</answer>
	</faq>
	<faq id="validation_error:doctype_root_null">
	<question>
	When building my project, I get an validation error: <code>Document root
	element "site", must match DOCTYPE root "null".</code>.
	</question>
	<answer>
	<p>
	You are probably trying to build the project with an old version of
	Forrest (built before 2003-01-08) that is incorrectly trying to validate
	the &s; file. If so, please update your Forrest
	installation.
	</p>
	<p>
	Alternatively, you may be building with an up-to-date Forrest, but have
	overridden <code>forrest.validate.xdocs.excludes</code> in
	<code>forrest.properties</code>. With the introduction of
	&s;, the above property must have &s;
	listed to prevent an attempt at DTD-based validation.
	</p>
	</answer>
	</faq>

	</part>

	<part id="general">
	<title>General</title>

	<faq id="generating_menus">
	<question>What is the relation between &s; and
	<code>book.xml</code>?
	</question>
	<answer>
	<p>
	One &s; file in your project root can replace all the book.xml files
	(one per directory) in your site. Internally, Forrest uses &s; to
	dynamically generate book.xml files. However, Forrest first checks
	for the existence of a book.xml file, so backwards-compatibility is
	preserved. If a directory has a book.xml file, the book.xml will be
	used to generate the menu. This is useful in situations where
	&s;-generated menus aren't appropriate.
	</p>
	</answer>
	</faq>

	<faq id="docbook">
	<question>
	How do I use DocBook as the xml documentation format?
	</question>
	<answer>
	<p>
	There are two ways. Forrest can transform the DocBook format into the
	Forrest "document" DTD on-the-fly and then render that as normal.
	The stylesheet that does this transformation still needs a little
	work but it handles most things.
	</p>
	<p>
	The other way is to use the 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 "sitemap" as explained in
	<link href="site:your-project">Using Forrest</link>
	and add matches to handle your DocBook documents, e.g.
	</p>
	<source><![CDATA[
	...
	<map:match pattern="*/resolver-.html">
	<map:generate src="content/xdocs/{1}/resolver-{2}.xml"/>
	<map:transform
	src="file:///usr/share/sgml/docbook/xsl/xhtml/docbook.xsl"/>
	<map:serialize/>
	</map:match>
	...
	]]>
	</source>
	<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 "document-v*" DTD and DocBook.
	</p>
	</answer>
	</faq>

	<faq id="how_can_I_help">
	<question>
	How can I help?
	</question>
	<answer>
	<p>
	Join the forrest-dev <link href="site:mail-lists">mailing list</link>,
	and tell us what you'd like to see improved. We regard all feedback
	as valuable, particularly from newcomers—often, close proximity
	blinds software developers to faults that are obvious to everyone
	else. Don't be shy!
	</p>
	<p>
	More info on contributing can be found on the <link
	href="site:contrib">Contributing to Forrest</link> page. Its always
	a good idea to check the Forrest <link href="site:todo">to do</link>
	list before diving in.
	</p>
	</answer>
	</faq>
	</part>
	</faqs>