You are viewing a plain text version of this content. The canonical link for it is here.
Posted to svn@forrest.apache.org by cr...@apache.org on 2005/06/23 07:36:34 UTC
svn commit: r193078 [37/65] - in /forrest/site: ./ docs_0_60/
docs_0_60/howto/ docs_0_60/howto/bugzilla-patch/
docs_0_60/howto/bugzilla-patch/my-images/ docs_0_60/howto/multi/
docs_0_60/images/ docs_0_70/ docs_0_70/howto/ docs_0_70/howto/cvs-ssh/
docs_...
Added: forrest/site/docs_0_80/faq.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/faq.xml?rev=193078&view=auto
==============================================================================
--- forrest/site/docs_0_80/faq.xml (added)
+++ forrest/site/docs_0_80/faq.xml Wed Jun 22 22:36:19 2005
@@ -0,0 +1,527 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+ Copyright 2002-2004 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>Frequently Asked Questions</title></header><body><section id="Questions"><title>Questions</title><section id="getting_started"><title>1. Getting Started and Building Forrest</title><section id="overview"><title>1.1. Where can I read an overview about how to work with Forrest? </title>
+ <p> See the <link href="site:v0.80//your-project">Using Forrest</link> guide. </p>
+ </section><section id="requirements"><title>1.2. What are the system requirements for Forrest? </title>
+ <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 Apache Ant.
+ </p>
+ <p>
+ Java 1.4 (or newer) is required. If you are only going to use Forrest
+ as-is then you need only the Java Runtime Environment (JRE).
+ If you intend to enhance and rebuild Forrest (or use the Forrest sources
+ with Subversion or use a source snapshot) then you need the full JDK.
+ </p>
+ </section><section id="cvs"><title>1.3. The old xml-forrest CVS code repository seems to be stale. What happened? </title>
+ <p> Forrest switched from a CVS code repository to SVN (Subversion) code repository. The old
+ CVS repository is closed and not kept current. </p>
+ </section><section id="svn"><title>1.4. How can I use SVN to keep up to date with the latest codebase? </title>
+ <p> Follow these <link href="site:v0.80//build">Building Forrest</link> notes. </p>
+ <p> The <link href="site:v0.80//your-project">Using Forrest</link> guide provides further
+ step-by-step assistance in getting started with Forrest for your project. </p>
+ </section><section id="single-document"><title>1.5. What is the best way to generate "standalone documents" using Forrest? </title>
+ <p> forrest site -Dproject.start-uri=myfile.pdf </p>
+ <p> The <link href="site:v0.80//your-project">Using Forrest</link> guide provides further
+ step-by-step assistance in getting started with Forrest for your project. </p>
+ </section><section id="cygwin_mutex_error"><title>1.6. When running <code>./build.sh</code> in cygwin, I get an error: <code>cygpath.exe:
+ *** can't create title mutex, Win32 error 6</code>. </title>
+ <p> This <link href="http://issues.apache.org/jira/secure/ViewIssue.jspa?key=FOR-10">appears
+ to be a bug in cygwin</link>. Please use the .bat script instead. </p>
+ </section><section id="maxmemory"><title>1.7. How can I specify the amount of memory to be used by Java? </title>
+ <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>
+ </section></section><section id="content_faqs"><title>2. Content Creation</title><section id="edit-content"><title>2.1. What tools can be used to edit the content?</title>
+ <p>If you are using the Apache Forrest xml <link href="site:v0.80//dtd-docs">document format</link>
+ or DocBook or other xml document types, then you can use any text editor or even a
+ dedicated xml editor. You must ensure valid xml. See our <link href="site:v0.80//catalog">configuration notes</link> for various editors. </p>
+ <p>There are content management systems like <link href="ext:lenya">Apache Lenya</link>. </p>
+ <p>Remember that Forrest can also use other source formats, such as OpenOffice.org docs or
+ JSPWiki. Use the appropriate editor for those document types and ensure that the document
+ stucture is consistent. Forrest can also use "html" as the source format, in which case
+ you can use text editors or "html editors" such as the one provided with the Mozilla web
+ browser. </p>
+ </section><section id="site-xml"><title>2.2.
+ How to use the <code>site.xml</code> configuration file for menus and linking.
+ </title>
+ <p>
+ The <code>site.xml</code> configuration file is used for two different purposes:
+ defining the left-hand navigation menus, and as a method for defining references
+ to be used when linking between documents.
+ This file is fully explained in
+ <link href="site:v0.80//linking">Menus and Linking</link>. Here is a precis:
+ </p>
+ <p>
+ The labels can be whatever text you want.
+ </p>
+ <source xml:space="preserve"><faq label="FAQs" href="faq.html">
+ <tech label="Technical" href="faq-tech.html">
+ <docbook href="#docbook"/>
+ <ignoring_javadocs href="#ignoring_javadocs"/>
+ </tech>
+ <user label="User" href="faq-user.html">
+</faq></source>
+ <p>
+ That will create a menu like this with three links:
+ </p>
+ <source xml:space="preserve">FAQs
+ Technical
+ User</source>
+
+ <p>
+ These documents can be linked to from other documents, like this:
+ </p>
+ <source xml:space="preserve"><a href="site:v0.80//faq/tech"> link to the top of the Tech FAQs
+<a href="site:v0.80//faq/tech/docbook"> link to the DocBook FAQ in the Tech FAQs</source>
+
+ <p>
+ If that "docbook" entry was a unique name in your site.xml then you
+ can shorten that latter link:
+ </p>
+ <source xml:space="preserve"><a href="site:v0.80//docbook"> link to the DocBook FAQ in the Tech FAQs</source>
+ </section><section id="examples"><title>2.3.
+ Where are examples of documents and site.xml and tabs.xml files?
+ </title>
+ <p>
+ There are examples in the 'forrest seed site' and also the Forrest website documents
+ are included with the distribution (cd forrest/site-author; forrest run).
+ </p>
+ </section><section id="PDF-output"><title>2.4. How can I generate one pdf-file out of the whole site or selected pages of the site?</title>
+ <p>Add the following entries to your site.xml file:</p>
+ <source xml:space="preserve">
+ <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.80//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.80//linking">site.xml</link> method for your
+ site structure and navigation, rather than the old book.xml method. </p>
+ </section><section id="pageBreaks"><title>2.5. How do I insert page breaks into documents?</title>
+ <p>Page breaks do not make a great deal of sense in HTML documents intended for display on a
+ screen. However, PDF documents are intended for printing and therefore page breaks can be
+ important.</p>
+ <p>To insert a page break in a PDF document simply add <em>pageBreakBefore</em> and/or
+ <em>pageBreakAfter</em> to the class attribute of the block you wish to force a
+ page break on. All the common block grouping elements support this class, for example,
+ note, warning, p and so on.</p>
+ <p>If you want these classes to be processed in your HTML documents as well you should add
+ the following to the <code>extra-css</code> element in your projects
+ <code>skinconf.xml</code>
+ </p>
+ <source xml:space="preserve"> .pageBreakBefore { margin-bottom: 0; page-break-before: always; } .pageBreakAfter {
+ margin-bottom: 0; page-break-after: always; } </source>
+ </section><section id="clickable-email-address"><title>2.6. How can I generate html-pages to show a 'clickable' email-address (of the
+ author-element)?</title>
+ <p>You would override <code>
+ $FORREST_HOME/main/webapp/skins/common/xslt/html/document2html.xsl</code> and edit the
+ "headers/authors" template. </p>
+ </section><section id="link_raw"><title>2.7. How do I link to raw files such as config.txt and brochure.pdf? </title>
+ <p>Handling of raw files was significantly changed in Forrest 0.7. See
+ <link href="site:v0.70//upgrading_07/raw">Upgrading to Apache Forrest 0.7</link> for
+ all the details.</p>
+ </section><section id="pdf_images"><title>2.8. Images don't display in PDFs. How do I fix this?</title>
+ <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>
+ </section><section id="tab-index"><title>2.9. The tab link in my site incorrectly assumes that 'index.html' is present in the
+ linked-to directory. How do I fix this? </title>
+ <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">
+ <tab label="User Manual" href="manual"/></source>
+ <p> and add this rule to the sitemap: </p>
+ <source xml:space="preserve">
+ <map:match pattern="manual">
+ <map:redirect-to uri="manual/Introduction.html"/>
+ </map:match></source>
+ </section><section id="tab-site"><title>2.10. I need help with the interaction between tabs.xml and site.xml </title>
+ <p>
+ See the <link href="site:v0.80//linking/tab-site">tips</link>.
+ </p>
+ </section><section id="defaultFileName"><title>2.11. How can I change the default file name that Forrest will look for when I request a
+ URL like <code>http://myserver</code> or <code>http://myserver/mydir/</code> ? </title>
+ <p>To change the default file name from 'index.html' (default) to 'overview.html' you need to
+ make the following changes:</p>
+ <ol>
+ <li> Create a '<link href="#cli-xconf">cli.xconf</link>' file for your project </li>
+ <li> Edit that file to replace 'index.html' in
+ <default-filename>index.html</default-filename>
+ with 'overview.html'. </li>
+ <li> Edit your project's <link href="site:v0.80//project-sitemap">sitemap.xmap</link> file. </li>
+ <li> Add the following code just before the end of the pipelines-element:<source xml:space="preserve">
+ <map:pipeline>
+ <map:match type="regexp" pattern="^.+/$">
+ <map:redirect-to uri="overview.html"/>
+ </map:match>
+ </map:pipeline>
+ </source></li>
+ </ol>
+ </section><section id="defaultStartPage"><title>2.12. How can I use a start-up-page other than index.html? </title>
+ <p>Forrest by default assumes that the first page (home page) of your site is named
+ index.html. Which is good because most web servers are configured to look for index.html
+ when you call a url like http://myserver</p>
+ <p>Like most settings in Forrest however this can be changed, for example when you want your
+ start-up-page for a CD-based documentation project to be named 'start.html'. </p>
+ <p>To change the start page of a site:</p>
+ <ol>
+ <li>Edit your project's <link href="site:v0.80//project-sitemap">sitemap.xmap</link> file.</li>
+ <li>Add the following code just before the end of the pipelines-element:<source xml:space="preserve">
+ <map:pipeline>
+ <map:match pattern="">
+ <map:redirect-to uri="start.html" />
+ </map:match>
+ </map:pipeline>
+ </source></li>
+ <li>Name the uri-attribute whatever you'd like your start page to be.</li>
+ <li>Don't forget to create that page and refer to it in your site.xml</li>
+ </ol>
+ </section><section id="label-entity"><title>2.13. How to use special characters in the labels of the site.xml file? </title>
+ <p> Use the numeric values for character entities. For example, rather than using
+ <code>&ouml;</code> use <code>&#246;</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.apache.org/jira/browse/FOR-244">Issue FOR-244</link>. </p>
+ </section><section id="encoding"><title>2.14. Does Forrest handle accents for non-English languages?</title>
+ <p>Yes, Forrest can process text in any language, so you can include:</p>
+ <ul>
+ <li>accents: á é í ó ú</li>
+ <li>diereses: ä ë ï ö ü</li>
+ <li>tildes: ã ñ ĩ õ ũ</li>
+ </ul>
+ <p>This is because sources for Forrest docs are xml documents, which can include any of
+ these, provided the encoding declared by the xml doc matches the actual encoding used in
+ the file. For example if you declare the default encoding:</p>
+ <source xml:space="preserve"><?xml version="1.0" encoding="UTF-8"?></source>
+ <p>but the file content is actually using ISO-8859-1 then you will receive validation
+ errors, especially if you include some non-ASCII characters.</p>
+ <p> This situation is commonly encountered when you edit the templates created by
+ <code>forrest seed</code> with your favorite (probably localized) editor without paying
+ attention to the encoding, or when you create a new file and simply copy the headers from
+ another file. </p>
+ <p>Although UTF-8 is an encoding well-suited for most languages, it is not usually the
+ default in popular editors or systems. In UNIX-like systems, most popular editors can
+ handle different encodings to write the file in disk. With some editors the encoding of
+ the file is preserved, while with others the default is used regardless of the original
+ encoding. In most cases the encoding used to write files can be controlled by setting the
+ environment variable <code>LANG</code> to an appropriate value, for instance: </p>
+ <source xml:space="preserve">[localhost]$ export LANG=en_US.UTF-8</source>
+ <p>Of course the <em>appropriate</em> way to set the encoding depends on the editor/OS, but
+ ultimately relys on the user preferences. So you can use the encoding you prefer, as long
+ as the <code>encoding</code> attribute of the xml declaration matches the actual encoding
+ of the file. This means that if you are not willing to abandon ISO-8859-1 you can always
+ use the following declaration instead:</p>
+ <source xml:space="preserve"><?xml version="1.0" encoding="ISO-8859-1"?></source>
+ <p>Another option is to use "character entities" such as <code>&ouml;</code>
+ (ö) or the numeric form <code>&#246;</code> (ö). </p>
+ <p>Another related issue is that your webserver needs to send http headers with the matching
+ charset definitions to the html page. </p>
+ <p>Here are some references which explain further: <link href="http://orixo.com/events/gt2004/bios.html#torsten">GT2004 presentation by Torsten
+ Schlabach</link> and <link href="http://www.alanwood.net/unicode/">Alan Wood's Unicode
+ resources</link>. </p>
+ </section><section id="cleanSite"><title>2.15. How can I make Forrest properly clean up the build/site-directory? </title>
+ <p>Forrest for performance reasons doesn't clean out the build/site-directory each time you
+ compile your project. This usually doesn't matter during development but might become a
+ problem in a production environment.</p>
+ <p>To ensure a clean build call 'forrest clean site' instead of just 'forrest' so Forrest
+ will delete all build directories before creating new content. </p>
+ </section><section id="i18n"><title>2.16. How can I internationalise (i18n) my content?</title>
+ <p>The i18n features of Forrest are still under development (as of 0.7) however there are
+ some features available. For example, navigation menus can be i18n'd (see fresh-site for an
+ example). Currently, <link href="http://issues.apache.org/jira/browse/FOR-506">work is underway</link> to
+ i18n skins</p>
+
+ <p>All internationalistation of tokens in, for example, the skins and the menus, is carried out
+ by the <link href="http://cocoon.apache.org/2.1/userdocs/transformers/i18n-transformer.html">Cocoon i18n
+ Transformer</link>. You can see an example of how it works in the above linked issue.</p>
+ </section><section id="rawTML"><title>2.17. How can I include HTML content that is not to be skinned by Forrest?</title>
+ <p>To server, for example, a legacy HTML site add something like the following
+ to your projects sitemap:</p>
+ <source xml:space="preserve">
+<map:match pattern="old_site/**.html">
+ <map:select type="exists">
+ <map:when test="{project:content}{0}">
+ <map:read src="{project:content}/{0}" mime-type="text/html"/>
+ <!--
+ Use this instead if you want JTidy to clean up your HTML
+ <map:generate type="html" src="{project:content}/{0}" />
+ <map:serialize type="html"/>
+ -->
+ </map:when>
+</map:match>
+ </source>
+ </section></section><section id="technical"><title>3. Technical</title><section id="proxy_config"><title>3.1. I'm behind a proxy and it's preventing Plugins from being downloaded, what should I
+ do?</title>
+ <p>You can configure the proxy in the <code>forrest.properties</code> file. Set the
+ <code>proxy.host</code> and <code>proxy.port</code> accordingly (the port will default
+ to port 80).</p>
+ </section><section id="CVS_revison_tags"><title>3.2. How can I generate html-pages to show the revision tag of cvs?</title>
+ <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.80//your-project"> Using Forrest</link> document.</p>
+ <p>This technique could also be used for a modification date with $Date: 2004/01/15 08:52:47
+ $</p>
+ </section><section id="cli-xconf"><title>3.3. How to control the processing of URIs by Cocoon, e.g. exclude certain URIs, include
+ other additional ones. </title>
+ <p> Forrest uses a configuration file to control the processing done by the Apache Cocoon
+ command-line called cli.xconf </p>
+ <p> Your project can supply its own <code>cli.xconf</code> and define patterns for URIs to
+ exclude. There are also other powerful configuration features. </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/main/webapp/WEB-INF/cli.xconf</code> to it. Declare the location of
+ this file in the forrest.properties configuration, e.g.
+ <code>project.configfile=${project.home}/src/documentation/conf/cli.xconf</code>
+ </p>
+ <p> Then edit cli.xconf, and add any exclude sections that you require. The default
+ cli.xconf ignores directory links and links containing 'apidocs' or starting with 'api/': </p>
+ <source xml:space="preserve">
+ ....
+ <!-- Includes and excludes can be used to limit which URLs are rendered -->
+ <strong>
+ <exclude pattern="**/"/>
+ <exclude pattern="**apidocs**"/>
+ <exclude pattern="api/**"/>
+ </strong>
+ <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.80//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>
+ </section><section id="ignoring_javadocs"><title>3.4. How do I stop Forrest breaking on links to external files that may not exist, like
+ javadocs? </title>
+ <p> This can be done by overriding the <link href="#cli-xconf">
+ <code>cli.xconf</code>
+ </link> Cocoon config file, and defining patterns for URLs to exclude. </p>
+ </section><section id="claimed_patterns"><title>3.5. Some of my files are not being processed because they use common filenames. </title>
+ <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. faq.html or faq-interview.html would fail, but
+ interview-faq.html would be fine. In future versions of Forrest we will attempt to deal
+ with this issue (<link href="http://issues.apache.org/jira/browse/FOR-217">FOR-217</link>).
+ </p>
+ </section><section id="build_msg_a"><title>3.6. What do the symbols and numbers mean when Forrest lists each document that it has
+ built? </title><p>
+ <source xml:space="preserve">...
+* [212/166] [0/0] 1.16s 62.4Kb docs_0_60/your-project.pdf
+X [0] /docs_0_80/upgrading_08.html BROKEN: No pipeline matched...
+* [213/164] [0/0] 0.391s 29.2Kb docs_0_70/howto/howto-buildPlugin.pdf
+^ apidocs/index.html
+* [214/170] [7/66] 1.476s 45.5Kb docs_0_60/sitemap-ref.html
+...</source>
+ <ul>
+ <li>Column 1 is the page build status (*=okay X=brokenLink ^=pageSkipped).</li>
+ <li>Column 2 is the page count - the number of pages processed and the number remaining. The latter will change because during processing one page, Cocoon will discover more.</li>
+ <li>Column 3 is the number of links that were gathered from that page.</li>
+ <li>Column 4 is the time taken.</li>
+ <li>Column 5 is the page size.</li>
+ </ul>
+ </p></section><section id="headless_operation"><title>3.7. When generating PNG images from SVG, I get an error: Can't connect to X11 window
+ server using ':0.0' as the value of the DISPLAY variable. </title>
+ <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>
+ </section><section id="project-logo-svg"><title>3.8.
+ The project logo that is generated from SVG is truncating my project name.
+ </title>
+ <p>
+ In a 'forrest seed site' the project and the group logo are generated from a
+ Scalable Vector Graphics (SVG) file, using the text from the
+ <code><project-name></code> and
+ <code><group-name></code> elements of the <code>skinconf.xml</code> file.
+ If you have a long project-name then you may need to adjust the width of the image.
+ Perhaps you want to change the colours too. Edit the file at
+ <code>src/documentation/content/xdocs/images/project.svg</code> and adjust the "width"
+ attribute of the <svg> element. For further details see
+ <link href="http://www.w3.org/Graphics/SVG/">SVG</link> resources.
+ </p>
+ </section><section id="catalog"><title>3.9. How do i configure my favourite XML editor or parser to find the local Forrest
+ DTDs? </title>
+ <p> Notes are provided for various tools at <link href="site:v0.80//catalog">Using Catalog Entity
+ Resolver for local DTDs</link>. </p>
+ </section><section id="skin"><title>3.10. How to make the site look better and change its skin? </title>
+ <p> There are <link href="site:v0.80//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.80//your-project/skins">configuration</link> of the skins.
+ Some projects may have special needs and can define their <link href="site:v0.80//your-project/new-skin">own skin</link>. </p>
+ </section><section id="xsp"><title>3.11. How do I enable <acronym title="eXtensible Server Pages">XSP</acronym> processing?</title>
+ <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/main/webapp/WEB-INF/lib
+ directory (or lib/core/ directory in the source distribution).</li>
+ <li>
+ <p> Add the following generator definition in the map:generators section of your <link href="site:v0.80//project-sitemap">project sitemap</link>
+ </p>
+ <source xml:space="preserve">
+ <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">
+<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>
+ </section><section id="breadcrumbs"><title>3.12. How do breadcrumbs work? Why don't they work locally?</title>
+ <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">
+ <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>
+ </section><section id="run_port"><title>3.13. How do I make <code>forrest run</code> listen on a different port?</title>
+ <p>
+ <code>forrest run -Dforrest.jvmargs="-Djetty.port=80"</code>
+ </p>
+ <p>Or copy Forrest's main/webapp/jettyconf.xml file to your project's src/documentation
+ directory and set the port number in that file. Then do <code>forrest run</code>
+ </p>
+ </section></section><section id="old_faqs"><title>4. Older version: 0.6</title><section id="old_claimed_patterns"><title>4.1. Some of my files are not being processed because they use common filenames. </title>
+ <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. faq.html or faq-interview.html would fail, but
+ interview-faq.html would be fine. In future versions of Forrest we will attempt to deal
+ with this issue (<link href="http://issues.apache.org/jira/browse/FOR-217">FOR-217</link>).
+ </p>
+ </section></section><section id="general"><title>5. General</title><section id="generating_menus"><title>5.1. What is the relationship between <code>site.xml</code> and <code>book.xml</code>? </title>
+ <p> One <code>site.xml</code> file in your project root can replace all the book.xml files (one per
+ directory) in your site. Internally, Forrest uses <code>site.xml</code> 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
+ <code>site.xml</code>-generated menus aren't appropriate. See <link href="site:v0.80//linking">Menus and
+ Linking</link>. </p>
+ </section><section id="docbook"><title>5.2. How do I use DocBook as the xml documentation format? </title>
+ <p> There are two ways. Forrest has a <code>simplifiedDocbook</code> plugin which can
+ transform the DocBook format into the Forrest "xdocs" format on-the-fly and then render
+ that as normal Forrest documents. Be aware that the stylesheet that does this
+ transformation is deliberately very limited and does not attempt to deal with all DocBook
+ elements. </p>
+ <p> The other way is to use the full DocBook stylesheets directly. The DocBook DTDs are
+ shipped with Forrest and automatically handled. However, you will need to have the DocBook
+ stylesheets on your system (they are too massive to ship with Forrest) and configure
+ Forrest accordingly. You will need to create a <link href="site:v0.80//project-sitemap">project
+ sitemap</link> as explained in <link href="site:v0.80//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"><?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 need to define the xhtml serializer used in <map:serialize type="xhtml"/>
+ in the components section of the sitemap. See the
+ <link href="http://cocoon.apache.org/2.1/userdocs/serializers/xhtml-serializer.html">Cocoon
+ docs</link> for the elements you need to add to define this component. You can see examples
+ of other components being added in the <code>FORREST_HOME/main/webapp/sitemap.xmap</code> file.</p>
+ <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.80//your-project/new_dtd">Using Forrest</link> for
+ configuration guidance. </p>
+ </section><section id="version"><title>5.3. How to report which version of Forrest is being used and the properties that are
+ set? </title>
+ <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>
+ </section><section id="logs"><title>5.4. Where are the log files to find more infomation about errors? </title>
+ <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/main/webapp/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>
+ </section><section id="how_can_I_help"><title>5.5. How to help? </title>
+ <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>
+ </section><section id="patch"><title>5.6. How to contribute a patch? </title>
+ <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> before diving in. </p>
+ </section></section></section></body></document>
\ No newline at end of file
Propchange: forrest/site/docs_0_80/faq.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_80/forrest-contract.html
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/forrest-contract.html?rev=193078&view=auto
==============================================================================
--- forrest/site/docs_0_80/forrest-contract.html (added)
+++ forrest/site/docs_0_80/forrest-contract.html Wed Jun 22 22:36:19 2005
@@ -0,0 +1,398 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta content="Apache Forrest" name="Generator">
+<meta name="Forrest-version" content="0.8-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<title>Our Contract (v0.8-dev)</title>
+<link type="text/css" href="../skin/basic.css" rel="stylesheet">
+<link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet">
+<link media="print" type="text/css" href="../skin/print.css" rel="stylesheet">
+<link type="text/css" href="../skin/profile.css" rel="stylesheet">
+<script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script>
+<link rel="shortcut icon" href="../favicon.ico">
+</head>
+<body onload="init()">
+<script type="text/javascript">ndeSetTextSize();</script>
+<div id="top">
+<div class="breadtrail">
+<a href="http://www.apache.org/">apache</a> > <a href="http://forrest.apache.org/">forrest</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+<div class="header">
+<div class="grouplogo">
+<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../images/apache-forrest.png" title="The Apache Software Foundation"></a>
+</div>
+<div class="projectlogo">
+<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../images/project-logo.gif" title="Apache Forrest"></a>
+</div>
+<div class="searchbox">
+<form action="http://www.google.com/search" method="get" class="roundtopsmall">
+<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">
+ <input attr="value" name="Search" value="Search" type="submit">
+</form>
+</div>
+<ul id="tabs">
+<li>
+<a class="base-not-selected" href="../index.html">Welcome</a>
+</li>
+<li>
+<a class="base-not-selected" href="../contrib.html">Project</a>
+</li>
+<li>
+<a class="base-not-selected" href="../versions/index.html">Versioned Docs</a>
+</li>
+<li>
+<a class="base-not-selected" href="../pluginDocs/index.html">Plugins</a>
+</li>
+<li>
+<a class="base-not-selected" href="../tools/index.html">Tools</a>
+</li>
+</ul>
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<div id="level2tabs"></div>
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+// --></script>
+</div>
+<div class="breadtrail">
+
+
+ </div>
+<div id="menu">
+<div onclick="SwitchMenu('menu_selected_1.1', '../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">0.80-dev</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../docs_0_80/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/faq.html">FAQs</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/changes.html">Changes</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/todo.html">Todo</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/your-project.html">Using Forrest</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/validation.html">XML Validation</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/linking.html">Menus and Linking</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/searching.html">Searching</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/skins.html">Default Skins</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/skin-package.html">Skin Packages</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/views.html">Views-dev</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">Our Contract</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/compliance.html">Standards Compliance</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.14', '../skin/')" id="menu_1.1.14Title" class="menutitle">How-To</div>
+<div id="menu_1.1.14" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_80/howto/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/howto/howto-howto.html">Write a How-to</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/howto/howto-asf-mirror.html">Download mirror</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/howto/howto-pdf-tab.html">Create tab PDF</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/howto/howto-editcss.html">Edit CSS (WYSIWYG)</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/howto/howto-corner-images.html">CSS corner SVG</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/howto/howto-forrest-from-maven.html">Maven Integration</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/howto/howto-buildPlugin.html">Build a Plugin</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/howto/howto-custom-html-source.html">Custom html source</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.14.10', '../skin/')" id="menu_1.1.14.10Title" class="menutitle">Multipage HowTo</div>
+<div id="menu_1.1.14.10" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_80/howto/multi/howto-multi.html">Introduction</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/howto/multi/step1.html">Step 1</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/howto/multi/step2.html">Step 2</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/howto/multi/step3.html">Step 3</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.14.11', '../skin/')" id="menu_1.1.14.11Title" class="menutitle">Views</div>
+<div id="menu_1.1.14.11" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_80/howto/howto-view-install.html">Install views</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/howto/howto-view-dsl.html">forrest:view DSL</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/howto/howto-view-contracts.html">contract implementations</a>
+</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.15', '../skin/')" id="menu_1.1.15Title" class="menutitle">Advanced Topics</div>
+<div id="menu_1.1.15" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_80/build.html">Building Forrest</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/catalog.html">Using DTD Catalogs</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/sitemap-ref.html">Sitemap Reference</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/project-sitemap.html">Project sitemap</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/cap.html">Sourcetype Action</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/upgrading_08.html">Upgrading to 0.8</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.17', '../skin/')" id="menu_1.1.17Title" class="menutitle">Reference docs</div>
+<div id="menu_1.1.17" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.1.17.1', '../skin/')" id="menu_1.1.17.1Title" class="menutitle">DTD documentation</div>
+<div id="menu_1.1.17.1" class="menuitemgroup">
+<div class="menuitem">
+<a href="../dtdx/dtd-docs.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../dtdx/document-v20.dtdx.html">document-v20</a>
+</div>
+<div class="menuitem">
+<a href="../dtdx/howto-v20.dtdx.html">howto-v20</a>
+</div>
+<div class="menuitem">
+<a href="../dtdx/faq-v20.dtdx.html">faq-v20</a>
+</div>
+<div class="menuitem">
+<a href="../dtdx/document-v13.dtdx.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a href="../dtdx/howto-v13.dtdx.html">howto-v13</a>
+</div>
+<div class="menuitem">
+<a href="../dtdx/faq-v13.dtdx.html">faq-v13</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.17.2', '../skin/')" id="menu_1.1.17.2Title" class="menutitle">Doc samples</div>
+<div id="menu_1.1.17.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../dtdx/document-v13.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a href="../dtdx/document-v20.html">document-v20</a>
+</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.18', '../skin/')" id="menu_1.1.18Title" class="menutitle">Older Docs</div>
+<div id="menu_1.1.18" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_80/primer.html">Forrest Primer</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/libre-intro.html">Libre</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/dreams.html">Dream list</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_80/howto/cvs-ssh/howto-cvs-ssh.html">CVS over SSH</a>
+</div>
+</div>
+</div>
+<div id="credit">
+<hr>
+ This is documentation for development version v0.8
+ (<a href="/versions/index.html">More</a>)</div>
+<div id="roundbottom">
+<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
+<div id="credit2">
+<a href="http://apachecon.com/"><img border="0" title="ApacheCon Europe 2005" alt="ApacheCon Europe 2005 - logo" src="http://apache.org/images/ac2005eu_135x50.gif" style="width: 135px;height: 50px;"></a>
+</div>
+</div>
+<div id="content">
+<div title="Portable Document Format" class="pdflink">
+<a class="dida" href="forrest-contract.pdf"><img alt="PDF -icon" src="../skin/images/pdfdoc.gif" class="skin"><br>
+ PDF</a>
+</div>
+<div class="trail">
+<text>Font size:</text>
+ <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
+ <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+ <input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
+</div>
+<h1>Our Contract</h1>
+<div class="abstract">This document describes, in a very techy bullet-style way, how
+ to use Forrest.</div>
+<div id="motd-area">
+ This is documentation for development version v0.8
+ (<a href="/versions/index.html">More</a>)</div>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#forrest-will">Forrest will:</a>
+</li>
+<li>
+<a href="#project-must">TheProject must:</a>
+</li>
+<li>
+<a href="#project-can">TheProject can:</a>
+</li>
+</ul>
+</div>
+
+<div class="frame note">
+<div class="label">Note</div>
+<div class="content">
+ 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".
+ </div>
+</div>
+
+<div class="frame note">
+<div class="label">Note</div>
+<div class="content">
+ Some terminology will assist: <span class="codefrag">{docroot}</span> is the location
+ inside TheProject's file hierarchy where all documentation related
+ resources are stored. Usually <span class="codefrag">{docroot}</span> equals to
+ <span class="codefrag">{projecthome}/src/documentation</span>
+
+</div>
+</div>
+
+
+<a name="N1002C"></a><a name="forrest-will"></a>
+<h2 class="underlined_10">Forrest will:</h2>
+<div class="section">
+<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
+ <a href="../mail-lists.html">mail list</a>.
+ </li>
+
+<li>Use Cocoon to generate the HTML and PDF documentation for
+ TheProject.</li>
+
+</ul>
+</div>
+
+
+<a name="N10046"></a><a name="project-must"></a>
+<h2 class="underlined_10">TheProject must:</h2>
+<div class="section">
+<p>Provide content and configuration ...</p>
+<ul>
+
+<li>Provide XML content in <span class="codefrag">{docroot}/content/xdocs</span>
+ according to the Forrest DTDs or one of the other input formats.
+ </li>
+
+<li>Provide navigation metadata using the configuration files
+ <span class="codefrag">site.xml</span> and <span class="codefrag">tabs.xml</span>
+
+</li>
+
+<li>Provide the skin configuation file in
+ <span class="codefrag">{projecthome}/skinconf.xml</span>
+
+</li>
+
+</ul>
+</div>
+
+
+<a name="N10068"></a><a name="project-can"></a>
+<h2 class="underlined_10">TheProject can:</h2>
+<div class="section">
+<p>Add extra abilities ...</p>
+<ul>
+
+<li>Provide its own skin in
+ <span class="codefrag">{docroot}/skins/{your-skin-name}</span> (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
+ <span class="codefrag">{docroot}/resources/schema/dtd</span>
+
+<ul>
+
+<li>and extra stylesheets to convert own grammar to the
+ intermediate 'document' structure.</li>
+
+<li>and declare those extra DTDs in
+ <span class="codefrag">{docroot}/resources/schema/catalog.xcat</span>
+</li>
+
+</ul>
+
+</li>
+
+<li>Provide its own overwriting versions of sitemaps
+ (<span class="codefrag">{docroot}/sitemap.xmap</span> 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>
+</div>
+
+</div>
+<div class="clearboth"> </div>
+</div>
+<div id="footer">
+<div class="lastmodified">
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+// --></script>
+</div>
+<div class="copyright">
+ Copyright ©
+ 2002-2005 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
+</div>
+</div>
+</body>
+</html>
Propchange: forrest/site/docs_0_80/forrest-contract.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_80/forrest-contract.pdf
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/forrest-contract.pdf?rev=193078&view=auto
==============================================================================
Binary file - no diff available.
Propchange: forrest/site/docs_0_80/forrest-contract.pdf
------------------------------------------------------------------------------
svn:mime-type = application/pdf
Added: forrest/site/docs_0_80/howto/cvs-ssh/howto-cvs-ssh.html
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/howto/cvs-ssh/howto-cvs-ssh.html?rev=193078&view=auto
==============================================================================
--- forrest/site/docs_0_80/howto/cvs-ssh/howto-cvs-ssh.html (added)
+++ forrest/site/docs_0_80/howto/cvs-ssh/howto-cvs-ssh.html Wed Jun 22 22:36:19 2005
@@ -0,0 +1,367 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta content="Apache Forrest" name="Generator">
+<meta name="Forrest-version" content="0.8-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<title>CVS through SSH (v0.8-dev)</title>
+<link type="text/css" href="../../../skin/basic.css" rel="stylesheet">
+<link media="screen" type="text/css" href="../../../skin/screen.css" rel="stylesheet">
+<link media="print" type="text/css" href="../../../skin/print.css" rel="stylesheet">
+<link type="text/css" href="../../../skin/profile.css" rel="stylesheet">
+<script src="../../../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../../../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../../../skin/fontsize.js" language="javascript" type="text/javascript"></script>
+<link rel="shortcut icon" href="../../../favicon.ico">
+</head>
+<body onload="init()">
+<script type="text/javascript">ndeSetTextSize();</script>
+<div id="top">
+<div class="breadtrail">
+<a href="http://www.apache.org/">apache</a> > <a href="http://forrest.apache.org/">forrest</a><script src="../../../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+<div class="header">
+<div class="grouplogo">
+<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../../../images/apache-forrest.png" title="The Apache Software Foundation"></a>
+</div>
+<div class="projectlogo">
+<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../../../images/project-logo.gif" title="Apache Forrest"></a>
+</div>
+<div class="searchbox">
+<form action="http://www.google.com/search" method="get" class="roundtopsmall">
+<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">
+ <input attr="value" name="Search" value="Search" type="submit">
+</form>
+</div>
+<ul id="tabs">
+<li>
+<a class="base-not-selected" href="../../../index.html">Welcome</a>
+</li>
+<li>
+<a class="base-not-selected" href="../../../contrib.html">Project</a>
+</li>
+<li>
+<a class="base-not-selected" href="../../../versions/index.html">Versioned Docs</a>
+</li>
+<li>
+<a class="base-not-selected" href="../../../pluginDocs/index.html">Plugins</a>
+</li>
+<li>
+<a class="base-not-selected" href="../../../tools/index.html">Tools</a>
+</li>
+</ul>
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<div id="level2tabs"></div>
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+// --></script>
+</div>
+<div class="breadtrail">
+
+
+ </div>
+<div id="menu">
+<div onclick="SwitchMenu('menu_1.1', '../../../skin/')" id="menu_1.1Title" class="menutitle">How-To Samples</div>
+<div id="menu_1.1" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../../docs_0_80/howto/index.html">Overview</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_selected_1.2', '../../../skin/')" id="menu_selected_1.2Title" class="menutitle" style="background-image: url('../../../skin/images/chapter_open.gif');">Committers</div>
+<div id="menu_selected_1.2" class="selectedmenuitemgroup" style="display: block;">
+<div class="menupage">
+<div class="menupagetitle">CVS through SSH</div>
+</div>
+</div>
+<div id="credit">
+<hr>
+ This is documentation for development version v0.8
+ (<a href="/versions/index.html">More</a>)</div>
+<div id="roundbottom">
+<img style="display: none" class="corner" height="15" width="15" alt="" src="../../../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
+<div id="credit2">
+<a href="http://apachecon.com/"><img border="0" title="ApacheCon Europe 2005" alt="ApacheCon Europe 2005 - logo" src="http://apache.org/images/ac2005eu_135x50.gif" style="width: 135px;height: 50px;"></a>
+</div>
+</div>
+<div id="content">
+<div title="Portable Document Format" class="pdflink">
+<a class="dida" href="howto-cvs-ssh.pdf"><img alt="PDF -icon" src="../../../skin/images/pdfdoc.gif" class="skin"><br>
+ PDF</a>
+</div>
+<div class="trail">
+<text>Font size:</text>
+ <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
+ <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+ <input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
+</div>
+<h1>CVS through SSH</h1>
+<div class="abstract">This How-To describes the steps necessary to configure an SSH enabled CVS connection. It is recommended to configure an SSH enabled CVS connection to work with Apache code repositories.</div>
+<div id="motd-area">
+ This is documentation for development version v0.8
+ (<a href="/versions/index.html">More</a>)</div>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#Intended audience">Intended audience</a>
+</li>
+<li>
+<a href="#Purpose">Purpose</a>
+</li>
+<li>
+<a href="#Prerequisites">Prerequisites</a>
+</li>
+<li>
+<a href="#Steps">Steps</a>
+<ul class="minitoc">
+<li>
+<a href="#Terms">Terms</a>
+</li>
+<li>
+<a href="#Setting+up+domain+users">Setting up domain users</a>
+</li>
+<li>
+<a href="#ssh_access">Setting up SSH access</a>
+</li>
+<li>
+<a href="#Setting+up+passphrase+access">Setting up passphrase access</a>
+</li>
+<li>
+<a href="#Getting+the+project+from+CVS">Getting the project from CVS</a>
+</li>
+<li>
+<a href="#How+to+setup+WinCVS">How to setup WinCVS</a>
+</li>
+<li>
+<a href="#References">References</a>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+<a name="N10013"></a><a name="Intended audience"></a>
+<h2 class="underlined_10">Intended audience</h2>
+<div class="section">
+<p>This How-to is aimed at developers who have been granted committer access to CVS repositories for particular projects.</p>
+</div>
+<a name="N1001B"></a><a name="Purpose"></a>
+<h2 class="underlined_10">Purpose</h2>
+<div class="section">
+<p>
+ Using SSH to access CVS repositories is recommended for security reasons. By configuring CVS to work with remote repository using private/public SSH keys you'll be able to run CVS commands without a need to enter your password every time you need access to CVS through SSH.
+ </p>
+</div>
+<a name="N10023"></a><a name="Prerequisites"></a>
+<h2 class="underlined_10">Prerequisites</h2>
+<div class="section">
+<ul>
+
+<li>Account on the local machine.</li>
+
+<li>Commiter access to the project(s). <em>This also imply having account on the CVS host machine.</em>
+</li>
+
+<li>Cygwin - a Unix environment for Windows systems. You can get it <a href="http://www.redhat.com/software/tools/cygwin/">here</a>. <em>Not required for Linux/*nix users.</em>
+</li>
+
+<li>A CVS GUI application (for Windows users only), e.g. WinCVS. <em>It is not required, but can be very useful.</em>
+</li>
+
+</ul>
+<div class="frame note">
+<div class="label">Note</div>
+<div class="content">If you are behind a firewall check that you can communicate through the 22 port. For anonymous access you will need 2401 one.</div>
+</div>
+</div>
+<a name="N10044"></a><a name="Steps"></a>
+<h2 class="underlined_10">Steps</h2>
+<div class="section">
+<p>How to proceed.</p>
+<a name="N1004C"></a><a name="Terms"></a>
+<h3 class="underlined_5">Terms</h3>
+<dl>
+
+<dt>SSH</dt>
+
+<dd>Secure Shell. See <a href="http://www.openssh.org">OpenSSH</a>
+</dd>
+
+<dt>CVS</dt>
+
+<dd>Concurrent Version System See <a href="http://www.cvshome.org">CVS Home Page</a>
+</dd>
+
+</dl>
+<div class="frame note">
+<div class="label">Note</div>
+<div class="content">
+<strong>$</strong> represents local, <strong>%</strong> remote machine.</div>
+</div>
+<a name="N10070"></a><a name="Setting+up+domain+users"></a>
+<h3 class="underlined_5">Setting up domain users</h3>
+<div class="frame note">
+<div class="label">Note</div>
+<div class="content">This step is necessary only for Windows users. Linux users can happily skip this section and pass to <a href="#ssh_access">Setting up SSH access</a> section</div>
+</div>
+<p>If you are a domain user then you should be added to Cygwin users list (See <span class="codefrag">[cygwin-dir]/etc/passwd</span>).
+ </p>
+<ul>
+
+<li>Start Cygwin, then enter following commands:</li>
+
+</ul>
+<pre class="code">
+$ whoami
+administrator
+$ mkgroup -d > /etc/group
+$ mkpasswd -d | grep 'userxxx' >> /etc/passwd
+$ exit
+ </pre>
+<div class="frame note">
+<div class="label">Note</div>
+<div class="content">Replace 'userxxx' by your account name</div>
+</div>
+<ul>
+
+<li>Start Cygwin/shell again and check that everything's Ok:</li>
+
+</ul>
+<pre class="code">
+$ whoami
+userxxx
+ </pre>
+<a name="N1009B"></a><a name="ssh_access"></a>
+<h3 class="underlined_5">Setting up SSH access</h3>
+<p>Start Cygwin/shell, then enter:</p>
+<pre class="code">
+$ ssh-user-config
+ Shall I create an SSH1 RSA identity file for you? (yes/no) no
+ Shall I create an SSH2 RSA identity file for you? (yes/no) (yes/no) no
+ Shall I create an SSH2 DSA identity file for you? (yes/no) (yes/no) yes
+ Generating /home/userxxx/.ssh/id_dsa
+ Enter passphrase (empty for no passphrase):
+ Enter same passphrase again:
+ Do you want to use this identity to login to this machine? (yes/no) yes
+ Adding to /home/userxxx/.ssh/authorized_keys2
+
+ Configuration finished. Have fun!
+ </pre>
+<p>
+ Now you have configured SSH on your machine. Next you have to setup access to the CVS machine.
+ </p>
+<div class="frame warning">
+<div class="label">Warning</div>
+<div class="content">Having an empty passphrase isn't recommended for security reasons. See <span class="codefrag">ssh-agent</span> documentation on how to configure automatic passphrase retaining.</div>
+</div>
+<a name="N100B2"></a><a name="Setting+up+passphrase+access"></a>
+<h3 class="underlined_5">Setting up passphrase access</h3>
+<p>Perform the following:</p>
+<pre class="code">
+$ scp ~/.ssh/id_dsa.pub userxxx@cvs.apache.org:.
+$ ssh -l userxxx -L 2401:localhost:2401 cvs.apache.org
+% mkdir ~/.ssh
+% chmod 700 ~/.ssh
+% cat ~/id_dsa.pub >> ~/.ssh/authorized_keys2
+% rm ~/id_dsa.pub
+% chmod 600 ~/.ssh/*
+% exit
+ </pre>
+<div class="frame note">
+<div class="label">Note</div>
+<div class="content">Note, that the account name on CVS machine can differ from your local account name.</div>
+</div>
+<p>
+ Check that your configuration is correct:
+ </p>
+<pre class="code">
+$ ssh userxxx@cvs.apache.org
+ </pre>
+<div class="frame note">
+<div class="label">Note</div>
+<div class="content">If this command doesn't work then it can mean that you have an old version of SSH. In this case try <span class="codefrag">ssh -l userxxx cvs.apache.org</span>. Run <span class="codefrag">ssh --help</span> to get all available options.</div>
+</div>
+<p>
+ If now you are logged in to the to the CVS machine without entering the password then everything's Ok.
+ </p>
+<a name="N100D6"></a><a name="Getting+the+project+from+CVS"></a>
+<h3 class="underlined_5">Getting the project from CVS</h3>
+<p>Now you are ready to get a project from CVS using SSH connection.</p>
+<p>E.g. how it is done using Cygwin/shell</p>
+<pre class="code">
+$ export CVS_RSH=/bin/ssh
+$ cvs -d :ext:userxxx@cvs.apache.org:/home/cvs co xml-cocoon2
+ </pre>
+<a name="N100E7"></a><a name="How+to+setup+WinCVS"></a>
+<h3 class="underlined_5">How to setup WinCVS</h3>
+<ul>
+
+<li>Add ssh.exe directory to your system PATH environment variable. Say: <br>
+
+<span class="codefrag">C:\>set PATH=%PATH%;C:\cygwin\bin</span>
+</li>
+
+<li>Add <span class="codefrag">CVS_RSH=ssh</span> environment variable</li>
+
+</ul>
+<p>
+ Start WinCVS, then:
+ </p>
+<ul>
+
+<li>From the main menu select <strong>Admin</strong>
+</li>
+
+<li>Then select <strong>Preferences</strong>
+</li>
+
+<li>In the dialog that comes up: <br>
+ Set the CVSROOT to <span class="codefrag">userxxx@cvs.apache.org:/home/cvs</span>
+</li>
+
+<li>Set the Authentication to SSH Server</li>
+
+<li>Click Ok</li>
+
+</ul>
+<a name="N1011B"></a><a name="References"></a>
+<h3 class="underlined_5">References</h3>
+<p>
+ You can find more on CVS, SSH and WinCVS here:
+ </p>
+<ul>
+
+<li>
+<a href="http://www.cvshome.org">CVS Home Page</a>
+</li>
+
+<li>
+<a href="http://www.openssh.org">OpenSSH</a>
+</li>
+
+<li>
+<a href="http://www.redhat.com/software/tools/cygwin/">Cygwin Home Page</a>
+</li>
+
+<li>
+<a href="http://odin.himinbi.org/wincvs-over-ssh/">WinCVS over SSH</a>
+</li>
+
+</ul>
+</div>
+</div>
+<div class="clearboth"> </div>
+</div>
+<div id="footer">
+<div class="lastmodified">
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+// --></script>
+</div>
+<div class="copyright">
+ Copyright ©
+ 2002-2005 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
+</div>
+</div>
+</body>
+</html>
Propchange: forrest/site/docs_0_80/howto/cvs-ssh/howto-cvs-ssh.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_80/howto/cvs-ssh/howto-cvs-ssh.pdf
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/howto/cvs-ssh/howto-cvs-ssh.pdf?rev=193078&view=auto
==============================================================================
Binary file - no diff available.
Propchange: forrest/site/docs_0_80/howto/cvs-ssh/howto-cvs-ssh.pdf
------------------------------------------------------------------------------
svn:mime-type = application/pdf