You are viewing a plain text version of this content. The canonical link for it is here.
Posted to svn@forrest.apache.org by cr...@apache.org on 2006/02/09 01:26:32 UTC
svn commit: r376128 [3/34] - in /forrest/site: ./ docs_0_60/
docs_0_60/howto/ docs_0_60/howto/bugzilla-patch/ docs_0_60/howto/multi/
docs_0_70/ docs_0_70/howto/ docs_0_70/howto/cvs-ssh/ docs_0_70/howto/multi/
docs_0_80/ docs_0_80/howto/ docs_0_80/howto...
Propchange: forrest/site/docs_0_60/changes.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/compliance.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/compliance.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_60/compliance.source.xml (added)
+++ forrest/site/docs_0_60/compliance.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,108 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ Copyright 2002-2005 The Apache Software Foundation or its licensors,
+ as applicable.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+--><!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd">
+<document>
+ <header>
+ <title>Standards Compliance</title>
+ </header>
+ <body>
+ <section>
+ <title>Introduction</title>
+ <p>
+ Forrest is still quite young, so there are known issues.
+ Standards compliance is a definite major goal. Please send patches
+ for the Forrest skin stylesheets to ensure such compliance.
+ </p>
+ <!--
+ <note>
+ For your testing, use the Forrestbot generated website, because that
+ reflects the current SVN code ...
+ <link href="http://forrestbot.cocoondev.org/sites/xml-forrest/">http://forrestbot.cocoondev.org/sites/xml-forrest/</link>
+ </note>
+ -->
+ </section>
+
+ <section>
+ <title>HTML</title>
+
+ <p>
+ Tested using the W3C HTML Validation Service
+ (<link href="http://validator.w3.org/">validator.w3.org</link>). The
+ index.html page of Forrest sites will have a link to this validator,
+ unless the user has turned this off.
+ </p>
+ <p>
+ The "<code>crust</code>" skin (current forrest-0.6-dev)
+ validates as HTML 4.0.1
+ </p>
+ <p>
+ The "<code>tigris</code>" skin (current forrest-0.6-dev)
+ validates as HTML 4.0.1
+ </p>
+ </section>
+
+ <section>
+ <title>WAI</title>
+<p>See
+<link href="http://www.w3.org/WAI/">Web Accessibility Initiative (WAI)</link>
+</p>
+<p>
+ There are actually many accessibility issues with the heavy use of
+ tables and images. These skins are gradually being improved.
+</p>
+<p>
+Bobby with WAI:
+<link href="http://bobby.watchfire.com/">bobby.watchfire.com</link>
+</p>
+<p>Issues ...</p>
+<ol>
+ <li>
+ Priority 1: alt text for images.
+ </li>
+ <li>Priority 2:
+ <link href="http://bobby.watchfire.com/bobby/html/en/gls/g41.html">Explicitly
+ associate form controls and their labels with the LABEL element</link>.
+ Perhaps we could have a label hidden with CSS?</li>
+ <li>FIXME: need to list other issues here, or attend to them.</li>
+</ol>
+<note>The forrest-site skin does not have any missing alts. Perhaps Bobby
+ does not like the trick with empty alt attributes. However, it only
+ complains about the two in the footer, and not about the other 40.</note>
+<p>
+Bobby with U.S. Section 508 Guidelines:
+<link href="http://bobby.watchfire.com/">bobby.watchfire.com</link>
+</p>
+<p>Issues ...</p>
+<ol>
+ <li>The same issues as above</li>
+</ol>
+ </section>
+
+ <section>
+ <title>CSS</title>
+<p>
+Jigsaw:
+<link href="http://jigsaw.w3.org/css-validator/">jigsaw.w3.org</link>
+</p>
+<p>Issues ...</p>
+<ol>
+ <li>CSS 2: No errors. Some warnings.</li>
+ <li>CSS 1: Errors: hover class, @media-print. Some warnings.</li>
+ <li>FIXME: need to list other issues here, or attend to them.</li>
+</ol>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Propchange: forrest/site/docs_0_60/compliance.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/faq.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/faq.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_60/faq.source.xml (added)
+++ forrest/site/docs_0_60/faq.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,708 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ Copyright 2002-2005 The Apache Software Foundation or its licensors,
+ as applicable.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+--><!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.2//EN" "http://forrest.apache.org/dtd/faq-v12.dtd">
+<faqs title="Frequently Asked Questions">
+
+ <part id="getting_started">
+ <title>Getting Started and Building Forrest</title>
+ <faq id="overview">
+ <question>
+ Where can i read an overview about how to work with Forrest?
+ </question>
+ <answer>
+ <p>
+ See the <link href="site:v0.60//your-project">Using Forrest</link> guide.
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="website-status">
+ <question>
+ Which version of Forrest does the website documentation relate to?
+ </question>
+ <answer>
+ <p>
+ The documentation on the Forrest website relates to the current
+ head development version of the source repository. See
+ <link href="index.html#status">further explanation</link>.
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="requirements">
+ <question>
+ What are the system requirements for Forrest?
+ </question>
+ <answer>
+ <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. The
+ <link href="http://cocoon.apache.org/2.1/installing/requirements.html">Cocoon requirements</link>
+ indicate that Java 1.3+ is required.
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="cvs">
+ <question>
+ The old xml-forrest CVS code repository seems to be stale. What happened?
+ </question>
+ <answer>
+ <p>
+ Forrest switched from a CVS code repository to SVN (subversion)
+ code repository. The old CVS repository is not kept current.
+ </p>
+ </answer>
+ </faq>
+ <faq id="svn">
+ <question>
+ How can I use SVN to keep up to date with the latest codebase?
+ </question>
+ <answer>
+ <p>
+ Follow these <link href="site:v0.60//build">Building Forrest</link> notes.
+ </p>
+ <p>
+ The <link href="site:v0.60//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/secure/ViewIssue.jspa?key=FOR-10">appears
+ to be a bug in cygwin</link>. Please use the .bat script instead.
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="maxmemory">
+ <question>
+ How can I specify the amount of memory to be used by Java?
+ </question>
+ <answer>
+ <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 <code>maxmemory</code> property in the <code>forrest.properties</code> file controls how much
+ memory Cocoon uses. Like many other properties you can copy them from the default configuration at
+ <code>src/core/fresh-site/forrest.properties</code>
+ </p>
+ <p>
+ Set the <code>ANT_OPTS</code> environment variable before you run forrest. The exact value you set
+ it to is dependant on your JVM, but something like <code>ANT_OPTS=-Xmx500M</code> will probably work.
+ </p>
+ </answer>
+ </faq>
+ </part>
+
+
+
+ <part id="technical">
+ <title>Technical</title>
+ <faq id="PDF-output">
+ <question>How can I generate one pdf-file out of
+ the whole site or selected pages of the site?</question>
+ <answer>
+ <p>Add the following entries to your site.xml file:</p>
+ <source xml:space="preserve"><![CDATA[
+ <about tab="home" label="About" href="">
+ ...
+ <all_site label="Full HTML" href="wholesite.html"/>
+ <all_sitePDF label="Full PDF" href="wholesite.pdf"/>
+ ...
+ </about>]]></source>
+ <p>
+ In this case the menu labeled "About" will have 2 new items:
+ "Full PDF" and "Full HTML". (See also
+ <link href="site:v0.60//howto/pdf-tab">How to create a PDF document for each tab</link>.)
+ </p>
+ <p>
+ This assumes that you use the
+ <link href="site:v0.60//linking">site.xml</link> method for your site
+ structure and navigation, rather than the old book.xml method.
+ </p>
+ </answer>
+ </faq>
+ <faq id="clickable-email-adress">
+ <question>How can I generate html-pages to show a
+ 'clickable' email-address (of the author-element)?</question>
+ <answer>
+ <p>You would override <code>
+ src/core/context/skins/common/xslt/html/document2html.xsl</code>
+ and edit the "headers/authors" template.
+ </p>
+ </answer>
+ </faq>
+ <faq id="CVS_revison_tags">
+ <question>How can I generate html-pages to show the
+ revision tag of cvs?</question>
+ <answer>
+ <p>If you have:<code><version>$Revision: 1.30
+ $</version></code>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
+ <link href="site:v0.60//your-project"> Using Forrest</link> document.</p>
+ <p>This technique could also be used for a modification date with
+ $Date: 2005/01/15 08:52:47 $</p>
+ </answer>
+ </faq>
+
+ <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/context/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 xml:space="preserve"><![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. These are a powerful feature of Cocoon's
+ <link href="site:v0.60//sitemap-ref">sitemap</link>.
+ For example, <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>
+ <p>
+ For example, if
+ <code>src/documentation/content/xdocs/tools/downloads.xml</code>
+ has a <code><link href="tool.zip"></code> then put
+ <code>tool.zip</code> in the
+ <code>src/documentation/content/tools/</code> directory.
+ </p>
+ <p>
+ See the explanation and demonstration of "linking" in your local
+ 'forrest seed' site.
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="claimed_patterns">
+ <question>Some of my files are not being processed because they use
+ common filenames.
+ </question>
+ <answer>
+ <p>
+ Certain patterns are claimed by the default sitemaps for
+ special processing. These include:
+ <code>site, changes, todo, faq, images, my-images, skinconf,
+ community, howto</code>
+ </p>
+ <p>
+ Sometimes there are workarounds, e.g. perhaps "my_site".
+ In future versions of Forrest we will attempt to deal with this issue.
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="build_msg_a">
+ <question>What do the symbols and numbers mean when Forrest lists each
+ document that it has built?
+ </question>
+ <answer>
+ <source xml:space="preserve"><![CDATA[
+* [56/0] 6.281s 23.0Kb index.html
+* [0/0] 0.0060s 4.0Kb images/project-logo.gif
+^ apidocs/index.html
+* [50/0] 1.582s 18.7Kb todo.html
+X [0] brokenlink.html BROKEN: reason
+* [50/0] 1.222s 20.2Kb dreams.html
+* [0/0] 0.535s 11.1Kb dreams.pdf
+...]]></source>
+ <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>
+ </answer>
+ </faq>
+
+ <faq id="pdf_images">
+ <question>Images 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 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
+ <link href="http://xml.apache.org/fop/graphics.html">FOP Graphics
+ formats</link>
+ </p>
+ <p>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>$FORREST/lib/optional/jimi-1.0.jar</code>.</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
+ <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 '/'. Which file to serve is then a concern of the sitemap.
+ For example, if the "User Manual" tab should link to
+ <code>manual/Introduction.html</code> then
+ <code>tabs.xml</code> should contain:
+ </p>
+ <source xml:space="preserve"><![CDATA[
+ <tab label="User Manual" href="manual"/>]]></source>
+ <p>
+ and add this rule to the sitemap:
+ </p>
+ <source xml:space="preserve"><![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 xml:space="preserve">forrest -Dforrest.jvmargs=-Djava.awt.headless=true site</source>
+ <p>
+ See also
+ <link href="http://cocoon.apache.org/2.1/faq/faq-configure-environment.html">Cocoon FAQ</link>.
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="catalog">
+ <question>
+ How do i configure my favourite XML editor or parser to find the
+ local Forrest DTDs?
+ </question>
+ <answer>
+ <p>
+ Notes are provided for various tools at
+ <link href="site:v0.60//catalog">Using Catalog Entity Resolver for
+ local DTDs</link>.
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="label-entity">
+ <question>
+ How to use special characters in the labels of the site.xml file?
+ </question>
+ <answer>
+ <p>
+ Use the numeric values for character entities.
+ For example, rather than using
+ <code><![CDATA[ö]]></code> use
+ <code><![CDATA[ö]]></code>
+ </p>
+ <p>
+ See the
+ <link href="http://www.w3.org/TR/xhtml-modularization/dtd_module_defs.html#a_xhtml_character_entities">XHTML Character Entities</link>
+ and see more discussion at
+ <link href="http://issues.cocoondev.org/browse/FOR-244">Issue FOR-244</link>.
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="skin">
+ <question>
+ How to make the site look better and change its skin?
+ </question>
+ <answer>
+ <p>
+ There are <link href="site:v0.60//skins">default skins</link> 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
+ <link href="site:v0.60//your-project/skins">configuration</link> of the skins.
+ Some projects may have special needs and can define their
+ <link href="site:v0.60//your-project/new-skin">own skin</link>.
+ </p>
+ </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.
+ </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/context/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/), and add the following generator definition in the map:generators section:</p>
+ <source xml:space="preserve"><![CDATA[
+ <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 xml:space="preserve"><![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.apache.org/cocoon/AddingXSPToForrest">AddingXSPToForrest</link> Wiki page.</p>
+ </answer>
+ </faq>
+
+ <faq id="breadcrumbs">
+ <question>How do breadcrumbs work? Why don't they work locally?</question>
+ <answer>
+ <p>Breadcrumbs begin with up to three URLs specified in
+ <code>skinconf.xml</code>. Here is what the Forrest site uses:</p>
+ <source xml:space="preserve"><![CDATA[
+ <trail>
+ <link1 name="apache" href="http://www.apache.org/"/>
+ <link2 name="xml.apache" href="http://xml.apache.org/"/>
+ <link3 name="" href=""/>
+ </trail>]]></source>
+ <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 <code>skinconf.xml</code>.
+ </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 xml:space="preserve"><![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:</p>
+ <source xml:space="preserve"><![CDATA[
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+ "http://www.w3.org/TR/html4/loose.dtd">]]></source>
+ <p>
+ 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 xml:space="preserve"><![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 site.xml 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
+ site.xml, the above property must have site.xml
+ listed to prevent an attempt at DTD-based validation.
+ </p>
+ </answer>
+ </faq>
+ <faq id="building_error-custom_sitemap">
+ <question>
+ When building my project, I get any of these errors:
+ <code>menu.xmap (The system cannot find the file specified)</code>
+ <code>static.xmap (The system cannot find the file specified)</code>
+ <code>Type 'xml-document' is not defined for 'serialize'</code>
+ </question>
+ <answer>
+ <p>
+ You are using an old version of sitemap.xmap (download the historic document
+ 'Upgrading to Forrest 0.5' from the subversion repository).
+ </p>
+ </answer>
+ </faq>
+
+ </part>
+
+ <part id="general">
+ <title>General</title>
+
+ <faq id="generating_menus">
+ <question>What is the relationship between site.xml and
+ <code>book.xml</code>?
+ </question>
+ <answer>
+ <p>
+ One site.xml file in your project root can replace all the book.xml files
+ (one per directory) in your site. Internally, Forrest uses site.xml 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 site.xml-generated menus aren't appropriate.
+ See <link href="site:v0.60//linking">Menus and Linking</link>.
+ </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 "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
+ <link href="site:v0.60//project-sitemap">project sitemap</link>
+ as explained in
+ <link href="site:v0.60//your-project">Using Forrest</link>
+ 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>
+ <source xml:space="preserve"><![CDATA[<?xml version="1.0"?>
+<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
+ <map:pipelines>
+ <map:pipeline>
+ <map:match pattern="resolver-*.html">
+ <map:generate src="{project:content.xdocs}resolver-{1}.xml"/>
+ <map:transform
+ src="file:///usr/share/sgml/docbook/xsl-stylesheets/xhtml/docbook.xsl"/>
+ <map:serialize type="xhtml"/>
+ </map:match>
+ </map:pipeline>
+ </map:pipelines>
+</map:sitemap>]]>
+ </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 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
+ <link href="site:v0.60//your-project/new_dtd">Using Forrest</link>
+ for configuration guidance.
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="version">
+ <question>
+ How to report which version of Forrest is being used and the
+ properties that are set?
+ </question>
+ <answer>
+ <p>
+ Do <code>'forrest -projecthelp'</code> or <code>'./build.sh'</code>
+ 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 <code>'forrest -v'</code> will provide verbose build messages.
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="logs">
+ <question>
+ Where are the log files to find more infomation about errors?
+ </question>
+ <answer>
+ <p>
+ The logfiles are at <code>build/webapp/WEB-INF/logs/</code>
+ </p>
+ <p>
+ The log level can be raised with the <code>logkit.xconf</code>
+ configuration. If you are using Forrest in the interactive webapp
+ mode (which is generally easiest for debugging errors) then see the
+ <code>build/webapp/WEB-INF/logkit.xconf</code> file.
+ If you are generating a static site (with command-line 'forrest')
+ then copy <code>$FORREST_HOME/context/WEB-INF/logkit.xconf</code>
+ to your project at
+ <code>src/documentation/content/conf/logkit.xconf</code>
+ and modify it. See more information and efficiency tips with
+ <link href="http://wiki.apache.org/cocoon/ExploringTheLogs">Cocoon logging</link>.
+ </p>
+ <p>
+ Doing <code>'forrest -v'</code> will provide verbose build messages
+ to the standard output.
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="how_can_I_help">
+ <question>
+ How to help?
+ </question>
+ <answer>
+ <p>
+ Join one of the Forrest project
+ <link href="site:mail-lists">mailing lists</link>
+ and tell us what you would like to see improved. We regard all feedback
+ as valuable, particularly from newcomers—often, close proximity
+ blinds software developers to faults that are obvious to everyone
+ else. Don't be shy!
+ </p>
+ </answer>
+ </faq>
+
+ <faq id="patch">
+ <question>
+ How to contribute a patch?
+ </question>
+ <answer>
+ <p>Please send all contributions via our
+ <link href="site:bugs">issue tracker</link>.
+ Here are notes about
+ <link href="site:contrib/patch">making patches</link>.
+ </p>
+ <p>More info about contributing can be found at the
+ <link href="site:contrib">Contributing to Forrest</link> page.
+ It is always a good idea to check the Forrest
+ <link href="site:bugs">issue tracker</link>
+ and
+ <link href="site:v0.60//todo">to do list</link>
+ before diving in.
+ </p>
+ </answer>
+ </faq>
+ </part>
+</faqs>
\ No newline at end of file
Propchange: forrest/site/docs_0_60/faq.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/forrest-contract.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/forrest-contract.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_60/forrest-contract.source.xml (added)
+++ forrest/site/docs_0_60/forrest-contract.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,103 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ Copyright 2002-2005 The Apache Software Foundation or its licensors,
+ as applicable.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+--><!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd">
+<document>
+ <header>
+ <title>Our Contract</title>
+ <notice>The legal tone of this document is just a gimmick, this is not a
+ legal document in any sense. At all times: since this is open source: the real
+ contract is described in the implementation details of the full distribution.
+ This tries to list (not explain) what the ins and outs of using Forrest is
+ about. Please let the forrest-dev
+ <link href="site:mail-lists">mail list</link> know if
+ any of the bullets listed here are out of sync with the real
+ implementation.</notice>
+ <abstract>This document describes, in a very techy bullet-style way, how
+ to use Forrest.</abstract>
+ </header>
+ <body>
+ <note>
+ This document describes the formal contract between the
+ <strong>Forrest distribution code</strong>, hereafter referred as
+ "Forrest", and
+ the <strong>Project (team)</strong> that is using it for generating
+ its documentation and web-site, hereafter referred to as "TheProject".
+ </note>
+ <note>
+ Some terminology will assist: <code>{docroot}</code> is the location
+ inside TheProject's file hierarchy where all documentation related
+ resources are stored. Usually <code>{docroot}</code> equals to
+ <code>{projecthome}/src/documentation</code>
+ </note>
+
+ <section id="forrest-will">
+ <title>Forrest will:</title>
+ <p>Provide infrastructure ...</p>
+ <ul>
+ <li>Provide document type definitions (DTDs), skins, default sitemaps,
+ Cocoon pipelines.
+ </li>
+ <li>Provide a willing team of supporting developers at the forrest-dev
+ <link href="site:mail-lists">mail list</link>.
+ </li>
+ <li>Use Cocoon to generate the HTML and PDF documentation for
+ TheProject.</li>
+ </ul>
+ </section>
+
+ <section id="project-must">
+ <title>TheProject must:</title>
+ <p>Provide content and configuration ...</p>
+ <ul>
+ <li>Provide XML content in <code>{docroot}/content/xdocs</code>
+ according to the Forrest DTDs or one of the other input formats.
+ </li>
+ <li>Provide navigation metadata using the configuration files
+ <code>site.xml</code> and <code>tabs.xml</code>
+ </li>
+ <li>Provide the skin configuation file in
+ <code>{projecthome}/skinconf.xml</code>
+ </li>
+ </ul>
+ </section>
+
+ <section id="project-can">
+ <title>TheProject can:</title>
+ <p>Add extra abilities ...</p>
+ <ul>
+ <li>Provide its own skin in
+ <code>{docroot}/skins/{your-skin-name}</code> (Check the current
+ Forrest skins and the related pipelines to see what they are doing.
+ Bear in mind that the provided skins are able to be configured and
+ may already meet your needs.)</li>
+ <li>Provide own DTDs to handle other specialised document types in
+ <code>{docroot}/resources/schema/dtd</code>
+ <ul>
+ <li>and extra stylesheets to convert own grammar to the
+ intermediate 'document' structure.</li>
+ <li>and declare those extra DTDs in
+ <code>{docroot}/resources/schema/catalog.xcat</code></li>
+ </ul>
+ </li>
+ <li>Provide its own overwriting versions of sitemaps
+ (<code>{docroot}/sitemap.xmap</code> and other *.xmap files)
+ ... (be sure you know what you are doing since you are then leaving
+ the area where other Forresters can help you out.
+ </li>
+ </ul>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Propchange: forrest/site/docs_0_60/forrest-contract.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.source.xml (added)
+++ forrest/site/docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,361 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ Copyright 2002-2005 The Apache Software Foundation or its licensors,
+ as applicable.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+--><document><header>
+ <title>How to Contribute a Patch via Bugzilla</title>
+ <abstract>
+Bugzilla is the Internet-based mechanism to facilitate contributions to any
+Apache project. This includes changes to code and documents
+(Patches), and also reports of flaws in the system (Bugs), and suggestions
+for enhancement.
+In this How-to we will concentrate on the Patch tracking capabilities of
+Bugzilla. We will explain how to create your Bugzilla account,
+how to enter a patch description, and finally how to attach the actual patch
+file.
+ </abstract>
+ <last-modified-content-date date="2002-05-25"/>
+ </header><body><section id="Intended Audience"><title>Intended Audience</title>
+<p>
+This document is meant for first-time users of Bugzilla.
+The web interface can be daunting, so this concise explanation will help
+you to start. After your first patch submission, you can proceed to make more
+substantial contributions.
+</p>
+
+<p>
+As our example we use the contribution of a simple documentation patch for
+the Apache Cocoon project. The principles apply to any project.
+</p>
+ </section><section id="Prerequisites"><title>Prerequisites</title>
+<p>
+Bugzilla contributors should:
+</p>
+<ul>
+<li>Understand what a Patch is and how to make one.
+Note that a new complete document is still just a "patch",
+though it does need separate treatment to a normal "diff".
+</li>
+<li>Understand that Bugzilla is the Apache Bug Database. Bugzilla does not
+distinguish between a Bug report, a Patch submission, and an Enhancement suggestion. They are all <em>"Bugs"</em> as far as Bugzilla is concerned.
+</li>
+</ul>
+
+</section><section id="Steps"><title>Steps</title>
+<p>
+Here is how to proceed. Go to
+<fork href="http://issues.apache.org/bugzilla/">Bugzilla</fork>
+in another browser window.
+</p>
+
+ <section>
+ <title>1. Create your Bugzilla Account</title>
+<p>
+Follow the link the home page to "Open a new Bugzilla account".
+Do not worry, you will not be sent spam email nor bombarded with advertisements
+by setting up this account. It is purely a workgroup tool.
+</p>
+
+<p>
+Note that you can conduct queries in Bugzilla and review submissions without
+having an account. However, to make a contribution you must have an account.
+This ensures legitimacy. It also enables the system to send you
+email automatically when your patch is applied by a Cocoon committer.
+</p>
+ </section>
+
+ <section>
+ <title>2. Enter a new bug report</title>
+
+<p>
+Follow the "Enter a new bug report" link from the Bugzilla home page. First,
+you will be asked to select the relevant project ... choose Cocoon 2 of course.
+Next, you will be asked to provide your account details. Following that, you
+will be presented an input form for the various details ...
+</p>
+
+<p><img src="my-images/bugzilla-screen.gif" alt="Bugzilla Screen" height="342" width="479"/></p>
+
+ <section>
+ <title>Specify Version</title>
+<p>
+This is the version of Cocoon that you prepared your patch against. Choose
+<code>Current CVS</code> if you have an up-to-date local working copy
+of HEAD branch or a very recent nightly build. Otherwise choose the relevant
+release version. This is a very important step, as you will confuse the
+committer if your changes do not match the repository. If you are unsure, then
+please say so in the description at step 12.
+</p>
+ </section>
+
+ <section>
+ <title>Specify Component</title>
+<p>
+Follow the "Component" link for description of the available
+components. If you do not know which component is relevant, then just use
+<code>core</code>.
+</p>
+ </section>
+
+ <section>
+ <title>Specify Platform</title>
+<p>
+This is really meant for bug reporting. Perhaps it could be relevant for a
+patch. You would usually specify the <code>All</code> option.
+</p>
+ </section>
+
+ <section>
+ <title>Specify Operating System (OS)</title>
+<p>
+Really meant for bug reporting. Perhaps it could be relevant for a patch.
+You would usually specify the <code>All</code> option.
+</p>
+ </section>
+
+ <section>
+ <title>Specify Severity</title>
+<p>
+The impact that would arise if your patch is not applied. For a documentation
+patch, the severity would usually be the default <code>Normal</code>.
+However, if it addressed some serious lack or fixed a misguided configuration
+statement, then the impact could be <code>major</code>.
+</p>
+<p>
+<!--FIXME: (DS) Why include this if it isn't recommended for a patch? -->
+<!-- (DC) To try to discourage them from using it. Does it need
+better words? -->
+(The <code>enhancement</code> option would not be used for a patch, as it is
+intended for suggesting something that should be done. Use this option wisely.
+It would be better to discuss it on the mailing list first.)
+</p>
+ </section>
+
+ <section>
+ <title>Specify Initial State</title>
+<p>
+Use the <code>New</code> option.
+</p>
+ </section>
+
+ <section>
+ <title>Specify Assigned To</title>
+<p>
+Leave it blank. Your patch will be automatically assigned to the
+<code>cocoon-dev</code> mailing list. When a committer takes on your patch,
+that committer will assign the bug to their own email address. This pevents
+duplication of effort by other committers.
+</p>
+<p>
+The Cc field can be used if you need the bug reports, and any follow-up, to be
+copied to some other person. Remember that your report will be sent
+automatically to the <code>cocoon-dev</code> mailing list, so you do not need
+to Cc anyone there.
+</p>
+ </section>
+
+ <section>
+ <title>Specify URL</title>
+<p>
+If the patch refers to a particular document, then provide the website URL.
+If it refers to an issue with one of the local Cocoon Samples, then provide
+the localhost URL.
+</p>
+ </section>
+
+ <section>
+ <title>Carefully choose the Summary</title>
+<p>
+The summary will become the all-important title of the bug. Use it wisely. You want
+to draw attention to your patch. Just as with posting email to the listervers,
+choosing a poor title may cause your posting to be easily overlooked.
+Use up all the characters available ... about 60 maximum.
+</p>
+<p>
+Start the Summary with the <code>[PATCH]</code> tag. This will ensure that it
+is included in the Cocoon automated patch queue summary posted to the mailing
+lists. The patch queue summary reminds people what patches are pending. If you
+omit this tag, then your patch may easily be overlooked.
+</p>
+ </section>
+
+ <section>
+ <title>Description</title>
+<p>
+Provide a brief explanation of what your patch does. Supply any instructions
+to help the committer apply your patch efficiently. Note any issues that may
+remain. It may help to list each file that you are submitting and briefly
+describe what it is. A committer will need to provide a descriptive log message
+when committing your work. Providing a clear description here will help them.
+</p>
+<p>
+Consider writing the Description and Summary text before you start entering
+your patch report. You could save it in a local text file beforehand and
+then copy-and-paste it when the time comes.
+</p>
+<p>
+<!--FIXME (DS): Do we need this? It's a patch, not a bug. It may be confusing. -->
+If this were a bug report, then it would need extensive description.
+</p>
+ </section>
+
+ </section>
+
+
+ <section>
+ <title>3. Send the patch report</title>
+<p>
+Review your options, then press the <strong>Commit</strong> button. This will
+add an entry to the bug database and email a report to the
+<code>cocoon-dev</code> mailing list and a copy to you. Your submission will be
+assigned a unique Bug Number which you can use to review its progress.
+</p>
+<p>
+The next steps will show you how to attach your patch to the report that you
+have just created ...
+</p>
+ </section>
+
+ <section>
+ <title>4. Create an attachment of the actual patch</title>
+<p>
+You will be presented with a status screen saying that your bug report
+was accepted and that email was sent to <code>cocoon-dev</code> mailing list.
+</p>
+
+<p>
+Now you have a choice ... proceed to review your bug report by selecting the
+link "Back to Bug #XXXXX". If you forgot to mention something,
+then you can add more comments. From that screen, follow the link
+"Create a new attachment".
+Otherwise follow the link from this status screen to "Attach a file to
+this bug".
+</p>
+
+ <section>
+ <title>Specify the file to be uploaded</title>
+<p>
+Provide the local pathname to your patchfile, e.g.
+<code>/home/me/work/cocoon/patch/howto-bugzilla.tar.gz</code>
+</p>
+ </section>
+
+ <section>
+ <title>Describe the attachment</title>
+<p>
+Provide a concise one line description, e.g.
+<code>Gzipped TAR archive with new docs and diffs</code>
+</p>
+ </section>
+
+ <section>
+ <title>Specify the contentType of the attachment</title>
+<p>
+If it is a Gzipped TAR archive (*.tar.gz) or a .zip archive, then select
+"<code>Binary file (application/octet-stream)</code>".
+If it is just a single xml document, then select
+"<code>Plain text (text/plain)</code>".
+If the patch is just a single diff file, then select
+"<code>Patch file (text/plain, diffs)</code>".
+</p>
+ </section>
+
+ </section>
+
+ <section>
+ <title>5. Submit the attachment</title>
+<p>
+When you are ready, press the <strong>Submit</strong> button. As for Step 3,
+you will be presented with a status screen saying that your attachment
+was accepted and that email was sent to <code>cocoon-dev</code> mailing list.
+</p>
+ </section>
+
+ <section>
+ <title>6. Be patient</title>
+<p>
+Now your patch will wait inside Bugzilla until one of the Cocoon committers
+assigns the patch to their own email address and starts to process it to apply
+it to the master CVS repository. As the registered owner of the Bug, you will
+be sent an automatic email at each of these stages.
+</p>
+ </section>
+
+ <section>
+ <title>7. Add more description or attachments if necessary</title>
+<p>
+Until the patch is applied by the committer and the Bug report is closed, you
+can still add more to your bug report. However, only do this when
+absolutely necessary because the patch should not be
+changing while the committer is trying to commit it. If you just want to make
+further changes, then it would be better to wait until your patch is
+applied. Then you can make a new patch. Remember that the committer has full
+veto and may decide to make some slight modifications to your patch. So it
+is far better to wait.
+</p>
+ </section>
+
+ <section>
+ <title>8. Adding subsequent patches to the same document or program</title>
+<p>
+If you want to make more patches to the same file, then please open a new Bug
+rather than re-open the old one. After all, once the original patch is
+applied by the committer, its corresponding Bug report is closed.
+</p>
+ </section>
+
+ </section><section id="Real World Extension"><title>Real World Extension</title>
+ <!--FIXME: (DS) The purpose of this is to provide examples of how they can use
+ the knowledge gained in this how-to -->
+<p>Contributing patches, in the form of documentation or code, is a vital way to give back to the Cocoon community. For example, you might consider contributing a timely patch in the form of a new FAQ, how-to, or tutorial. Or, you may also consider submitting a patch which updates Cocoon's existing user and developer guides. </p>
+ </section><section id="Tips"><title>Tips</title>
+
+ <section>
+ <title>Setting user preferences</title>
+<p>
+You can configure certain preferences, though the Bugzilla defaults work just
+fine.
+</p>
+ </section>
+
+ <section>
+ <title>Review the bugzilla documentation</title>
+<p>
+There are various explanations of terminology and procedures ... follow the
+links should you need to know more.
+</p>
+ </section>
+
+ <section>
+ <title>Search Bugzilla</title>
+<p>
+Bugzilla has a very powerful search interface. Now that you have a login
+account, Bugzilla can remember customized queries which you can run with a
+single click.
+</p>
+ </section>
+
+ </section><section id="References"><title>References</title>
+ <ul>
+<li>
+Bugzilla is at
+<link href="http://issues.apache.org/bugzilla/">http://issues.apache.org/bugzilla/</link>
+</li>
+<li>
+Helpful Bug Writing Guidelines are available directly from the
+Bug entry interface.
+</li>
+ </ul>
+
+ </section></body></document>
\ No newline at end of file
Propchange: forrest/site/docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/howto/howto-asf-mirror.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/howto-asf-mirror.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_60/howto/howto-asf-mirror.source.xml (added)
+++ forrest/site/docs_0_60/howto/howto-asf-mirror.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,134 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ Copyright 2002-2005 The Apache Software Foundation or its licensors,
+ as applicable.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+--><document><header>
+ <title>Generate an ASF mirrors page using interactive web form</title>
+
+ <abstract>Use ihtml (interpreted html) to include html form elements
+ into a forrest-generated html page. For example, this enables building
+ automated download mirror pages for ASF project websites.
+ </abstract>
+
+ <last-modified-content-date date="2005-07-19"/>
+ </header><body><section id="Intended Audience"><title>Intended Audience</title>
+ <ul>
+ <li>Any Apache project that uses Forrest to generate their website
+ will need to have a mirrors page.</li>
+ <li>Also anyone interested in the use of ihtml to embed html form
+ elements into a generated Forrest page.</li>
+ </ul>
+ </section><section id="Purpose"><title>Purpose</title>
+ <p>All Apache projects use dynamically generated download pages
+ which determine the closest mirror and provide an interactive list of
+ the current alternative mirrors.
+ This HowTo describes the procedure to generate the template page
+ that is utilised by the mirrors.cgi script. The processed page
+ includes html "form" elements that are not included in the xdocs DTDs.
+ </p>
+ <p>This process has many exciting applications, beyond the scope of
+ this document.
+ </p>
+ </section><section id="Prerequisites"><title>Prerequisites</title>
+ <ul>
+ <li>Followed the documentation about
+ <link href="http://www.apache.org/~bodewig/mirror.html">Making your
+ downloads mirrorable</link> and
+ <link href="http://www.apache.org/dev/mirrors.html">Apache Mirroring Information</link>
+ .
+ </li>
+ <li>Established your ASF distribution space as described.</li>
+ <li>Already building your project website with Forrest.</li>
+ </ul>
+ </section><section id="Steps"><title>Steps</title>
+ <section id="cgi">
+ <title>Add the mirrors.cgi as a raw file</title>
+ <p>As explained in the mirrors document, there will be a two-line CGI
+ wrapper script at the top-level of your website called
+ <code>mirrors.cgi</code></p>
+ <p>Utilising the Forrest concept of raw un-processed content,
+ add the file as <code>src/documentation/mirrors.cgi</code>
+ (copy the Forrest project's
+ <link href="http://svn.apache.org/repos/asf/forrest/trunk/src/documentation/content/mirrors.cgi">mirrors.cgi</link>)
+ </p>
+ </section>
+
+ <section id="ihtml">
+ <title>Add the mirrors.ihtml to xdocs directory</title>
+ <p>This file contains the html content of your mirror page, including
+ the html form elements which drive the mirror selection. It also
+ contains the specific tokens that are interpreted by the mirrors.cgi
+ script to add the list of mirrors and select the closest.
+ </p>
+ <p>
+ Add the file as <code>src/documentation/xdocs/mirrors.html</code>
+ (Use the Forrest project's
+ <link href="http://svn.apache.org/repos/asf/forrest/trunk/src/documentation/content/xdocs/mirrors.ihtml">mirrors.html</link>
+ as a template and edit it to suit.)
+ </p>
+ </section>
+
+ <section id="menu">
+ <title>Add a menu entry for Download</title>
+ <p>Add an entry to your site.xml navigation. For example ...
+ </p>
+ <source xml:space="preserve">
+ <about label="About">
+ <index label="Index" href="index.html"/>
+ <license label="License" href="license.html"/>
+ <download label="Download" href="http://forrest.apache.org/mirrors.cgi"/>
+ <download_html href="mirrors.html"/><!-- so the page is part of a tab -->
+ ...</source>
+ </section>
+
+ <section id="link">
+ <title>Cause the mirrors.ithml to be processed as an extra file</title>
+ <p>Forrest gathers the links that are to be crawled, by reading site.xml
+ and by finding any other internal links in the actual documents.
+ There is no link to mirrors.html because it is an extra file that needs
+ to be generated and skinned, but not linked in any way.
+ </p>
+ <p>The Cocoon command-line interface
+ (<link href="http://cocoon.apache.org/2.1/userdocs/offline/">CLI</link>)
+ to the rescue. Add an entry to your project's cli.xconf by copying the
+ default one from
+ <code>$FORREST_HOME/context/WEB-INF/cli.xconf</code> to your
+ <code>src/documentation/conf/</code> directory (or wherever
+ ${forrest.conf-dir} points). Add the following entry ...
+ </p>
+ <source xml:space="preserve">
+<uris name="mirrors" follow-links="false">
+ <uri type="append" src="mirrors.html"/>
+</uris></source>
+ </section>
+
+ <section id="forrest">
+ <title>Run 'forrest' to build your site</title>
+ <p>
+ That is all that you need to do, Forrest will take care of it from
+ there. Run the '<code>forrest</code>' command. The mirrors.html page
+ will be generated with the skin applied.
+ </p>
+ </section>
+
+ <section id="explain">
+ <title>Explanation of the process</title>
+ <p>Forrest automatically reads ihtml files and transforms the html source
+ to the forrest xdocs intermediate format. It mainly detects heading
+ elements (h1, h2, etc.) and converts them to "sections". The remainder
+ of the html elements are copied over as-is. With this technique the
+ html form elements are copied over to the output.
+ </p>
+ </section>
+ </section></body></document>
\ No newline at end of file
Propchange: forrest/site/docs_0_60/howto/howto-asf-mirror.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/howto/howto-howto.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/howto-howto.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_60/howto/howto-howto.source.xml (added)
+++ forrest/site/docs_0_60/howto/howto-howto.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,192 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ Copyright 2002-2005 The Apache Software Foundation or its licensors,
+ as applicable.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+--><document><header>
+ <title>How to write a How-To</title>
+
+ <version>0.3</version>
+
+ <abstract>This How-To describes the steps necessary to write a How-To
+ document. Writing documentation is a valuable way to give back to the
+ community.</abstract>
+
+ <last-modified-content-date date="2005-07-18"/>
+ </header><body><section id="Intended Audience"><title>Intended Audience</title>
+ <p>Users who are ready to share their knowledge and experiences with the
+ community.</p>
+ </section><section id="Purpose"><title>Purpose</title>
+ <p>These guidelines are based on successful how-to document structures
+ used by other open source projects with diverse author groups. Following
+ these tried and true guidelines will help to insure the effectiveness of
+ your work.</p>
+ </section><section id="Prerequisites"><title>Prerequisites</title>
+ <p>How-To authors should have:</p>
+
+ <ul>
+ <li>A unique How-To topic, related to using Forrest, which fulfills a
+ specific need. Check out existing How-Tos to find a niche for your work.
+ Consider posting your idea for the How-To to user mailing list, to make
+ sure another author's draft is not already in process.</li>
+
+ <li>A sufficient ability in English to write the FAQ. However, we would
+ rather that you just make a start, as the community can help to
+ fine-tune the document.</li>
+
+ <li>Copy this template document "howto-howto.xml" to be modified with
+ your own content as necessary.</li>
+
+ <li>An understanding of the How-To document structure. Just use this
+ template document and you will be safe.
+ Make sure you run '<code>forrest validate-xdocs</code>' before
+ contributing your document.</li>
+ </ul>
+
+ <note>See the <link href="site:howto-v13-dtd">DTD documentation</link>
+ which explains the document structure.</note>
+ </section><section id="Steps"><title>Steps</title>
+ <p>Here is how to proceed.</p>
+
+ <section id="overview">
+ <title>Write the Overview</title>
+
+ <p>An overview helps potential readers to determine quickly if a
+ particular How-To matches their interests or needs. In a few sentences,
+ summarize the main points of your How-To. Make sure to include any
+ critical definitions which will help readers evaluate the utility of
+ your How-To. Consider writing the overview last, after you have
+ completed all other sections.</p>
+ </section>
+
+ <section id="audience">
+ <title>Describe your Intended Audience</title>
+
+ <p>If your How-To is targetted at a specific audience, describe it here.
+ For example, potential readers will have different levels of skill using
+ Forrest. They will also bring different areas of expertise and
+ backgrounds to their How-To learning experience. When you clarify your
+ target audience up front, you will save all other readers time and
+ confusion.</p>
+ </section>
+
+ <section id="purpose">
+ <title>State the Purpose</title>
+
+ <p>State the purpose of your How-To. Explain how the reader will benefit
+ by reading it. Give your reader an incentive or two to continue.</p>
+ </section>
+
+ <section id="prerequisites">
+ <title>List any Prerequisites</title>
+
+ <p>Inform your reader about any required knowledge, configuration, or
+ resources they may need before stepping through your How-To. Assist them
+ in this preparation by linking to other useful resources on the Forrest
+ site or the web. Helping your readers to prepare increases the
+ likelihood that they will continue reading your How-To.</p>
+ </section>
+
+ <section id="steps">
+ <title>Describe the Steps of your How-To</title>
+
+ <p>In a precise, step-by-step approach, walk your reader through the
+ process. Make sure your reader can reproduce your intended result by
+ following your exact steps. Make the learning process efficient by
+ supplying sample code snippets or configuration details as
+ necessary.</p>
+ </section>
+
+ <section id="extension">
+ <title>Extend the Learning</title>
+
+ <p>Provide your reader with a few real-world examples of how the
+ techniques or capabilities gained from your How-To could be applied.
+ Reward the reader for successfully completing the How-To with a few
+ ideas about how it will pay off.</p>
+ </section>
+
+ <section id="summarize">
+ <title>Summarize the Entire Process</title>
+
+ <p>In a few sentences, remind the reader what they have just learned.
+ This helps to reinforce the main points of your How-To.</p>
+ </section>
+
+ <section id="tips">
+ <title>Additional Tips or FAQs</title>
+
+ <p>In some cases, step-by-step instructions simply aren't enough. Use
+ this section to pass on any other tips or frequently asked questions.
+ Anticipating the needs of your readers will increase the overall success
+ of your writing effort.</p>
+ </section>
+
+ <section id="references">
+ <title>References</title>
+
+ <p>Remember to acknowledge any third-party resources or individuals who
+ contributed to the development of your How-To. Consider providing links
+ for those motivated readers who want to learn more.</p>
+ </section>
+
+ <section id="contribute">
+ <title>Submit via the project issue tracker</title>
+
+ <p>Create an attachment for your How-To document, and submit it via the
+ project <link href="site:bugs">issue tracker</link>.</p>
+ </section>
+
+ <section id="feedback">
+ <title>Get some feedback</title>
+
+ <p>When the committers have added your document then it will be
+ available for everyone to to build upon and enhance. Feedback will
+ happen via the <link href="site:mail-lists">mailing lists</link>.</p>
+ </section>
+ </section><section id="Extension"><title>Extension</title>
+ <p>Solutions can be extended to cover many different problem domains. A
+ nearly unlimited number of potential How-To topics, from simple to
+ complex, are available right now, limited only by your imagination.</p>
+ </section><section id="Frequently Asked Questions"><title>Frequently Asked Questions</title><section><title>1 What is the difference between a How-To and a tutorial?</title>
+ <p>The goal of a How-To is to help the reader to accomplish a specific
+ task with clear and consise instructions. While tutorials may contain
+ How-To-like instructions and content, they also include additional
+ background and conceptual content to help teach their readers higher
+ order concepts along the way. How-Tos are concerned about filling an
+ immediate, short-term need. Tutorials often provide long-term
+ knowledge which can be applied across a range of needs.</p>
+ </section><section><title>2 What spelling convention should I follow?</title>
+ <p>Use whatever spelling convention (American, British, etc.) that is
+ most intuitive to you.</p>
+ </section></section><section id="Tips"><title>Tips</title>
+ <section id="tip-dtd">
+ <title>How-To dtd</title>
+
+ <p>The document structure is likely to change soon. Please note that
+ this HOWTO page is likely to change as well.</p>
+ </section>
+ </section><section id="References"><title>References</title>
+ <p>This is not the first, nor will it be the last, How-To on writing
+ How-Tos. For other ideas and opinions on the matter, check out the
+ following sources.</p>
+
+ <ul>
+ <li>Joel D. Canfield's <link href="http://www.evolt.org/article/How_To_Write_A_How_To/9741/18250/index.html">How
+ to Write a How-To</link> on evolt.org.</li>
+
+ <li>The Linux Documentation Project's <link href="http://www.tldp.org/HOWTO/HOWTO-INDEX/index.html">HOWTO</link>
+ index page provides many excellent How-To documents to inspire your
+ efforts.</li>
+ </ul>
+ </section></body></document>
\ No newline at end of file
Propchange: forrest/site/docs_0_60/howto/howto-howto.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/howto/howto-pdf-tab.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/howto-pdf-tab.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_60/howto/howto-pdf-tab.source.xml (added)
+++ forrest/site/docs_0_60/howto/howto-pdf-tab.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,234 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ Copyright 2002-2005 The Apache Software Foundation or its licensors,
+ as applicable.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+--><document><header>
+ <title>How to create a PDF document for each tab</title>
+ <abstract>This How-To describes the generation of a PDF document for each
+ group of documents that is defined by a tab.
+ </abstract>
+ <last-modified-content-date date="2005-07-19"/>
+ </header><body><section id="Intended Audience"><title>Intended Audience</title>
+ <p>
+ Users who need to generate one printable document aggregated from a
+ group of documents.
+ </p>
+ </section><section id="Purpose"><title>Purpose</title>
+ <p>
+ By default Forrest generates a pdf file for each separate document of
+ your project.
+ As well you can create a pdf of the whole site. But sometimes it may
+ be necessary to generate a pdf file out of selected tab, i.e. only for
+ certain parts of the site.
+ </p>
+ </section><section id="Prerequisites"><title>Prerequisites</title>
+ <ul>
+ <li>Understand how to create project-specific sitemaps by following the
+ <link href="site:v0.60//your-project">Using Forrest</link> document.</li>
+ </ul>
+ </section><section id="Steps"><title>Steps</title>
+ <p>The procedure outlined below will define a project
+ <code>sitemap.xmap</code> and create a new
+ <code>pdf-tab.xmap</code> based on the <code>aggregate.xmap</code>
+ </p>
+ <section id="sitemap">
+ <title>Create your project's main sitemap.xmap</title>
+ <p>
+ Simply copy the sitemap.xmap from the Forrest sitemaps at
+ <code>${FORREST_HOME}/context/sitemap.xmap</code> into your
+ <code>src/documentation</code> directory (or wherever
+ ${project.sitemap-dir} points to).
+ </p>
+ </section>
+
+ <section id="aggregator">
+ <title>Create the aggregator sitemap pdf-tab.xmap</title>
+ <p>
+ Copy the aggregate.xmap from Forrest sitemaps into your
+ ${project.sitemap-dir} and rename it to pdf-tab.xmap
+ </p>
+ </section>
+
+ <section id="workaround-202">
+ <title>Edit project sitemap.xmap</title>
+ <note>
+ This is a workaround for Issue FOR-202
+ </note>
+ <p>
+ Edit the project <code>sitemap.xmap</code> to comment-out the match
+ for the sitemap like this:
+ </p>
+ <source xml:space="preserve">
+<!--
+<map:pipeline internal-only="false">
+<map:select type="exists">
+ <map:when test="{project:sitemap}">
+ <map:mount uri-prefix="" src="{project:sitemap}" check-reload="yes" />
+ </map:when>
+</map:select>
+</map:pipeline
+-->
+ </source>
+ </section>
+
+ <section id="mount">
+ <title>Edit project sitemap.xmap to mount pdf-tab.xmap</title>
+ <p>
+ Insert the following lines after the
+ <code><map:match pattern="site.xml"></code>
+ pipeline in the section called "SOURCE FORMATS".
+ </p>
+ <source xml:space="preserve">
+...
+<map:match pattern="pdf-tab.xml">
+ <map:mount uri-prefix="" src="pdf-tab.xmap" check-reload="yes" />
+</map:match>
+...
+ </source>
+ </section>
+
+ <section id="edit-aggregator">
+ <title>Edit the file <code>pdf-tab.xmap</code></title>
+ <p>
+ The <code><map:match pattern="*.xml"></code> element
+ should look like the following:
+ </p>
+ <source xml:space="preserve">
+<map:match pattern="*.xml">
+ <map:generate src="cocoon://abs-linkmap"/>
+ <map:transform type="xpath">
+ <map:parameter name="include" value="//*[@wholesite='true']"/>
+ <map:parameter name="exclude" value="//*[@wholesite='false']"/>
+ </map:transform>
+ <map:transform src="resources/stylesheets/site2book.xsl" />
+ <map:transform src="resources/stylesheets/aggregates/book2cinclude.xsl">
+ <map:parameter name="title"
+ value="{conf:project-name}: Still My Foo Site"/>
+ </map:transform>
+ <map:transform type="cinclude"/>
+ <map:transform src="resources/stylesheets/aggregates/doc2doc-uniqueids.xsl"/>
+ <map:transform src="resources/stylesheets/aggregates/docs2document.xsl"/>
+ <map:serialize type="xml"/>
+</map:match>
+ </source>
+ </section>
+ <section id="edit-site">
+ <title>Edit your site.xml</title>
+ <p>Add the following entry to your site.xml in the
+ <code><about></code> element
+ </p>
+ <source xml:space="preserve">...
+<whole_foosite href="pdf-tab.html" label="sub site" />
+ </source>
+ <p>
+ Your site.xml should look like this ...
+ </p>
+ <source xml:space="preserve">...
+<about label="About">
+ <index label="Index" href="index.html" description="Welcome to MyProj"/>
+ <changes label="Changes" href="changes.html"
+ description="History of Changes" />
+ <todo label="Todo" href="todo.html" description="Todo List" />
+ <whole_foosite href="pdf-tab.html" label="pdf-tab" />
+</about>
+...
+ </source>
+ <p>
+ This allows you to link to it via a
+ <code><link href="site:v0.60//whole_foosite"></code>
+ reference.
+ </p>
+ <p>Add to every element that should be included in the pdf-tab.pdf
+ the attribute <code>wholesite="true"</code></p>
+ <source xml:space="preserve">
+<sample-wiki label="Wiki page" href="wiki-sample.html"
+ description="wiki-sample" wholesite="true"/>
+ </source>
+ <note>This attribute will be inherited by all children of the element.
+ Do not use it in the parent element that contains the
+ <code><whole_foosite href="pdf-tab.html" label="pdf-tab" /></code>
+ as the child (will cause a <code>stack overflow</code> if you do)!!!
+ </note>
+ </section>
+ <section id="explain">
+ <title>Explanation of the operation</title>
+ <p>
+ Line 4 of our example
+ <br/>
+ <code><map:parameter name="include" value="//*[@wholesite='true']"/></code>
+ looks at your site.xml and will match every element containing the
+ <code>wholesite="true"</code> attribute. For example, to use the "samples"
+ tab ...
+ </p>
+ <source xml:space="preserve">
+...
+<samples label="Samples" href="samples/" tab="samples" wholesite="true">
+...
+</samples>
+...
+ </source>
+ <p>
+ It matches <strong>all</strong> of the elements that contain
+ <code>wholesite="true"</code>
+ (in our example <code><samples></code>
+ and its "children") for the content of the pdf file to be generated.
+ </p>
+ <source xml:space="preserve">
+<samples label="Samples" href="samples/" tab="samples" wholesite="true">
+ <sample2 label="Static content" href="sample2.html"
+ description="More Samples" wholesite='false'/>
+ <sample-wiki label="Wiki page" href="wiki-sample.html"
+ description="wiki-sample" />
+ <sample-ihtml label="ihtml page" href="ihtml-sample.html"
+ description="Test iHTML page" />
+</samples>
+ </source>
+ <p>
+ This example shows that you can as well exclude site(s) from the aggregation
+ by using the <code>wholesite="false"</code> attribute. This attribute will be as well inherited
+ by all children of the element.
+ </p>
+ <p>
+ Line 8 defines the title of the pdf file by taking the content
+ of the project-name variable in
+ <code>skinconf.xml</code> and adding some funny text:
+ <br/>
+ <code><map:parameter name="title" value="{conf:project-name}: Still My Foo Site"/></code>
+ </p>
+ <note>
+ In the original <code>aggregate.xmap</code> there is the line
+ <br/>
+ <code><map:parameter name="ignore" value="{1}"/></code>
+ <br/>
+ just before the title definition
+ (<code><map:parameter name="title" value=".../></code>).
+ Be sure to delete it or comment it out if you like to generate a
+ pdf-file for specific sites. You only need it for the generation of
+ one pdf-file for the whole project (this is what
+ <code>aggregate.xmap</code> usually does).
+ </note>
+ </section>
+ </section><section id="Feedback and further development of this How-To"><title>Feedback and further development of this How-To</title>
+ <p>
+ Please provide feedback about this document via the
+ <link href="site:mail-lists">mailing lists</link>.
+ </p>
+ <p>
+ In the future, this ability will probably be incorporated into the
+ main Forrest process.
+ </p>
+ <fixme author="open">
+ This document will need to be modified when Issue FOR-202 is solved.
+ </fixme>
+ </section></body></document>
\ No newline at end of file
Propchange: forrest/site/docs_0_60/howto/howto-pdf-tab.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/howto/index.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/index.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_60/howto/index.source.xml (added)
+++ forrest/site/docs_0_60/howto/index.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ Copyright 2002-2005 The Apache Software Foundation or its licensors,
+ as applicable.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+--><!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd">
+<document>
+
+ <header>
+ <title>Overview of the How-To documents</title>
+ </header>
+
+ <body>
+ <ul>
+ <li><link href="site:v0.60//howto/write-howto">How to write a How-To</link>
+ - Provides instructions about writing documents. Please copy this
+ file to serve as a template for your own document.
+ </li>
+ <li><link href="site:v0.60//howto/asf-mirror">Generate an ASF mirrors page using interactive web form</link>
+ - Use ihtml (interpreted html) to include html form elements
+ into a forrest-generated html page. For example, this enables building
+ automated download mirror pages for ASF project websites.
+ </li>
+ <li><link href="site:v0.60//howto/pdf-tab">How to create a PDF document for each tab</link>
+ - Describes the generation of a PDF document for each
+ group of documents that is defined by a tab.
+ </li>
+ </ul>
+ </body>
+
+</document>
\ No newline at end of file
Propchange: forrest/site/docs_0_60/howto/index.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/howto/multi/howto-multi.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/multi/howto-multi.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_60/howto/multi/howto-multi.source.xml (added)
+++ forrest/site/docs_0_60/howto/multi/howto-multi.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ Copyright 2002-2005 The Apache Software Foundation or its licensors,
+ as applicable.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+--><document><header>
+ <title>Example of a multi-page how-to</title>
+ <abstract>This is the shell of a multi-page how-to. Add your own content.
+ </abstract>
+ <last-modified-content-date date="2003-09-10"/>
+ </header><body><section id="Intended audience"><title>Intended audience</title>
+ <p>Describe the audience here.</p>
+ </section><section id="Purpose"><title>Purpose</title>
+ <p>Explain the purpose of the howto here.</p>
+ </section><section id="Prerequisites"><title>Prerequisites</title>
+ <p>Configuration requirements:</p>
+ <ul>
+ <li>This.</li>
+ <li>That.</li>
+ </ul>
+ <p>Requisite skills:</p>
+ <ul>
+ <li>These.</li>
+ <li>Those.</li>
+ </ul>
+
+ </section><section id="Various Steps"><title>Various Steps</title>
+ <p>After this brief introductory paragraph, the steps are described in
+ separate documents:</p>
+ <ul>
+ <li><link href="step1.html">Step 1: Do foo</link></li>
+ <li><link href="step2.html">Step 2: Do foobar</link></li>
+ <li><link href="step3.html">Step 3: Finish up</link></li>
+ </ul>
+ </section><section id="Real World Extension"><title>Real World Extension</title>
+ <p>Briefly describe some relevant extensions that go beyond these basics.</p>
+ </section><section id="Tips"><title>Tips</title>
+ <p>If you have a problem running the example, then you can try the
+ following tips:</p>
+ <ul>
+ <li>Tip #1</li>
+ <li>Tip #2</li>
+ </ul>
+ </section><section id="Related Resources"><title>Related Resources</title>
+ <p>Cocoon resources:</p>
+ <ul>
+ <li>For all Cocoon basics see the
+ <link href="ext:cocoon">Cocoon Web site</link>.
+ </li>
+ </ul>
+ </section><section id="Feedback"><title>Feedback</title>
+ <p>If you find any faults in this How-to or can see any improvements,
+ please contact the
+ <link href="site:mail-lists">project mail lists</link> with them.
+ </p>
+ </section></body></document>
\ No newline at end of file
Propchange: forrest/site/docs_0_60/howto/multi/howto-multi.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/howto/multi/step1.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/multi/step1.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_60/howto/multi/step1.source.xml (added)
+++ forrest/site/docs_0_60/howto/multi/step1.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ Copyright 2002-2005 The Apache Software Foundation or its licensors,
+ as applicable.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+--><document><header>
+ <title>Multi-page how-to: Step 1</title>
+ <last-modified-content-date date="2003-09-10"/>
+ </header><body><section id="Step 1: Do foo"><title>Step 1: Do foo</title>
+ <section>
+ <title>First section of this step</title>
+ <p>Description here.</p>
+ </section>
+ <section>
+ <title>Second section of this step</title>
+ <p>Description here.</p>
+ <p>Source code follows ...</p>
+ <source xml:space="preserve">
+<pointy-brackets>
+ <are-allowed-in-source-CDATA-sections/>
+</pointy-brackets>
+
+ </source>
+ <p>Now we move on to <link href="step2.html">Step 2: Do foobar</link></p>
+ </section>
+ </section></body></document>
\ No newline at end of file
Propchange: forrest/site/docs_0_60/howto/multi/step1.source.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/howto/multi/step2.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/multi/step2.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_60/howto/multi/step2.source.xml (added)
+++ forrest/site/docs_0_60/howto/multi/step2.source.xml Wed Feb 8 16:26:20 2006
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ Copyright 2002-2005 The Apache Software Foundation or its licensors,
+ as applicable.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+--><document><header>
+ <title>Multi-page how-to: Step 2</title>
+ <last-modified-content-date date="2003-09-10"/>
+ </header><body><section id="Step 2: Do foobar"><title>Step 2: Do foobar</title>
+ <section>
+ <title>First section of this step</title>
+ <p>Description here.</p>
+ </section>
+ <section>
+ <title>Second section of this step</title>
+ <p>Description here.</p>
+ <p>Now we move on to <link href="step3.html">Step 3: Finish up</link></p>
+ </section>
+ </section></body></document>
\ No newline at end of file
Propchange: forrest/site/docs_0_60/howto/multi/step2.source.xml
------------------------------------------------------------------------------
svn:eol-style = native